none

diff --git a/TWiki/TWikiPlugins.mdwn b/TWiki/TWikiPlugins.mdwn
index c18ca6b..4ee2a3b 100644 (file)
--- a/TWiki/TWikiPlugins.mdwn
+++ b/TWiki/TWikiPlugins.mdwn
@@ -29,6 +29,11 @@
             <li><a href="#Publishing for Public Use"> Publishing for Public Use</a></li>
           </ul>
         </li>
+        <li><a href="#Recommended Storage of Plugin Da"> Recommended Storage of Plugin Data</a><ul>
+            <li><a href="#Where to store Plugin Internal D"> Where to store Plugin Internal Data</a></li>
+            <li><a href="#Where to Store Data for Topics u"> Where to Store Data for Topics using the Plugin</a></li>
+          </ul>
+        </li>
       </ul>
     </li>
   </ul>
@@ -252,7 +257,7 @@ The Plugin documentation topic contains usage instructions and version details.
 >
 > **Example:** &lt;_Include an example of the Plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!_&gt;"
 >
-> **Plugin Global Settings:** &lt;_Description and settings for custom Plugin %VARIABLES%, and those required by TWiki._&gt;"
+> **Plugin Settings:** &lt;_Description and settings for custom Plugin %VARIABLES%, and those required by TWiki._&gt;"
 >
 > - **Plugins Preferences** &lt;_If user settings are needed, explain... Entering values works exactly like [[TWikiPreferences]] and [[WebPreferences]]: six (6) spaces and then:_&gt;"
 >   - **Set &lt;_EXAMPLE = value added_&gt;**
@@ -280,12 +285,74 @@ A minimum Plugin release consists of a Perl module with a [[WikiName]] that ends
 
 ### <a name="Publishing for Public Use"></a> Publishing for Public Use
 
-You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins. Publish your Plugin in three steps:
+You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins/PluginPackage. Publish your Plugin in these steps:
 
-1. **Post** the Plugin documentation topic in the TWiki:Plugins web:
-  - create a new topic using the Plugin name, ex: `MyFirstPlugin.txt`
+1. **Post** the Plugin documentation topic in the TWiki:Plugins/PluginPackage:
+  - enter the Plugin name in the "How to Create a Plugin" section, for example `MyFirstPlugin`
   - paste in the topic text from [[Creating Plugin Documentation|Main/WebHome#CreatePluginTopic]] and save
 2. **Attach** the distribution zip file to the topic, ex: `MyFirstPlugin.zip`
 3. **Link** from the doc page to a new, blank page named after the Plugin, and ending in `Dev`, ex: `MyFirstPluginDev`. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
-
--- [[AndreaSterbini]] - 29 May 2001 <br /> -- [[PeterThoeny]] - 11 Dec 2003 <br /> -- [[MikeMannix]] - 03 Dec 2001
+4. **Put** the Plugin into the CVS repository, see TWiki:Plugins/ReadmeFirst (optional)
+
+Thank you very much for sharing your Plugin with the TWiki community :-)
+
+<a name="RecommendedStorageOfPluginData"></a>
+
+## <a name="Recommended Storage of Plugin Da"></a> Recommended Storage of Plugin Data
+
+Plugins sometimes need to store data. This can be Plugin internal data like cache data, or generated data for the browser like images. The following is a recommendation where to store the data.
+
+### <a name="Where to store Plugin Internal D"></a> Where to store Plugin Internal Data
+
+In case the Plugin generates data just for internal use, or data which is not specific to a topic, store it in the Plugin's attachment directory.
+
+- The Plugin's attachment directory is `pubdir/Installweb/FooBarPlugin`
+  - `Installweb` refers to the name of the web where the Plugin is installed
+- The Plugin's attachment URL is `%PUBURL%/Installweb/FooBarPlugin`
+- The filename should start with an underscore, followed by an identifier, e.g. `_any_name.ext`
+  - The leading underscore avoids a nameclash with files attached to the Plugin topic
+  - Use only alphanumeric characters, underscores and periods to avoid platform dependency issues and URL issues
+  - Do not use subdirectories (rename and delete would fail)
+- Use Plugin API functions documented in [[TWikiFuncModule]] to ensure portability:
+  - Use `getPubDir()` to get the attachment root directory
+  - Use `getUrlHost()` and `getPubUrlPath()` to build the URL in case you create content for the browser
+  - Use `$installWeb` to get the name of the web where the Plugin is installed
+  - Create the web directory and topic attachment directory if needed
+- Hint: Package the Plugin at least with one file attachment. This ensures that the attachment directory already exists
+
+### <a name="Where to Store Data for Topics u"></a> Where to Store Data for Topics using the Plugin
+
+In case the Plugin generates data which is specific to a topic, store it in the topic's attachment directory.
+
+- The topic's attachment directory is `pubdir/Webname/TopicName`
+- The topic's attachment URL is `%PUBURL%/Webname/TopicName`
+- The filename should start with an underscore, followed by the Plugin name, an underscore and an identifier, e.g. `_FooBarPlugin_any_name.ext`
+  - The leading underscore avoids a nameclash with files attached to the same topic
+  - Use only alphanumeric characters, underscores and periods to avoid platform dependency issues and URL issues
+  - Do not use subdirectories (rename and delete would fail)
+- Use Plugin API functions documented in [[TWikiFuncModule]] to ensure portability:
+  - Use `getPubDir()` to get the attachment root directory
+  - Use `getUrlHost()` and `getPubUrlPath()` to build the URL in case you create content for the browser
+
+Example code to build the file name:
+
+    sub _make_filename
+    {
+        my ( $web, $topic, $name ) = @_;
+
+        # Create web directory "pub/$web" if needed
+        my $dir = TWiki::Func::getPubDir() . "/$web";
+        unless( -e "$dir" ) {
+            umask( 002 );
+            mkdir( $dir, 0775 );
+        }
+        # Create topic directory "pub/$web/$topic" if needed
+        $dir .= "/$topic";
+        unless( -e "$dir" ) {
+            umask( 002 );
+            mkdir( $dir, 0775 );
+        }
+        return "$dir/_FooBarPlugin_$name";
+    }
+
+-- TWiki:Main/PeterThoeny - 11 Dec 2003 <br /> -- TWiki:Main/AndreaSterbini - 29 May 2001 <br /> -- TWiki:Main/MikeMannix - 03 Dec 2001