Changeset 920


Ignore:
Timestamp:
11/24/08 14:27:56 (3 years ago)
Author:
CrawfordCurrie
Message:

Item287: Rewrote significant chunk of plugins doc to simplify and improve developer doc. Added doc: protocol to %INCLUDE to support including core module documentation

Location:
trunk
Files:
2 added
7 edited

Legend:

Unmodified
Added
Removed

  • trunk/EmptyPlugin/data/System/EmptyPlugin.txt

    r878 r920  
    11%META:TOPICINFO{author="ProjectContributor" date="1111929255" format="1.0" version="$Rev: 14040 $"}% 
    2 ---+ Empty TWiki Plugin 
     2---+ Empty Plugin 
    33 
    44This is an empty Plugin you can use as a template to build your own [[%SYSTEMWEB%.Plugins][Plugins]]. This Plugin does nothing, but is ready to be used. 
    … …  
    66To create your own Plugin: 
    77 
    8    * Copy file ==TWiki/Plugins/EmptyPlugin.pm== to ==<name>Plugin.pm== and customize the plugin. 
     8   * Copy file ==lib/Foswiki/Plugins/EmptyPlugin.pm== to ==lib/Foswiki/Plugins/<name>Plugin.pm==. 
    99   * Create a  ==<name>Plugin== topic in the %SYSTEMWEB% web. Do so by visiting http://foswiki.org/Extensions/PluginPackage#NewPlugin and starting a new topic to get the default plugin topic text (don't save the topic). Customize your plugin topic to your needs. 
    10    * See details in [[%SYSTEMWEB%.Plugins][Plugins]]. 
     10   * See details in [[%SYSTEMWEB%.DevelopingPlugins][DevelopingPlugins]]. 
    1111 
    12 ---++ Syntax Rules 
     12---++ Plugin Handlers 
     13The following plugin handlers are defined. 
    1314 
    14 (none) 
     15%INCLUDE{"pod:Foswiki::Plugins::EmptyPlugin" level="3"}% 
    1516 
    1617---++ Plugin Settings 
    … …  
    2223      * Set SHORTDESCRIPTION = Empty Plugin used as a template for new Plugins 
    2324 
    24    * Your own setting, for example: 
    25       * Set EXAMPLE = got it! 
    26  
    27    * Debug plugin: ( TWiki sets =$debug= in your plugin. See output in =data/debug.txt=.) 
    28       * Set DEBUG = 0 
    29  
    30 ---++ Plugin Installation Instructions 
    31  
    32    * This plugin is preinstalled, you do not need to install it. 
    33  
    3425---++ Plugin Info 
    3526 
    36 |  Plugin Author: | TWiki:Main.AndreaSterbini, TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie | 
    37 |  Copyright: | © 2001-2007, %SYSTEMWEB%.ProjectContributor | 
     27|  Plugin Author: | Foswiki:Main.AndreaSterbini, TWiki:Main.PeterThoeny, Foswiki:Main.CrawfordCurrie | 
     28|  Copyright: | &copy; 2008, Foswiki Contributors<br>&copy; 2001-2007, TWiki Contributors | 
    3829|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) | 
    3930|  Plugin Version: | %$VERSION% | 
    40 |  Change History: | <!-- versions below in reverse order -->&nbsp; | 
    41 |  20 May 2007 | Added renderWikiWordHandler | 
    42 |  01 Feb 2006: | Dakar changes | 
    43 |  21 Mar 2004: | Added afterSaveHandler | 
    44 |  14 Jul 2001: | Changed to plug&amp;play | 
    45 |  27 Feb 2001: | Initial version | 
    46 |  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 | 
    47 |  Dependencies: | %$DEPENDENCIES | 
    48 |  Foswiki:Extensions/Benchmark: | %SYSTEMWEB%.GoodStyle 99%, %SYSTEMWEB%.FormattedSearch 99%, %TOPIC% 99% | 
    49 |  Plugin Home: | http://foswiki.org/Extensions/%TOPIC% | 
    50 |  Feedback: | http://foswiki.org/Extensions/%TOPIC%Dev | 
    51 |  Appraisal: | http://foswiki.org/Extensions/%TOPIC%Appraisal | 
    5231 
    53 __Related Topics:__ [[%SYSTEMWEB%.Plugins][Plugins]], %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.DefaultPreferences, %USERSWEB%.SitePreferences 
    5432 
    55 -- %SYSTEMWEB%.ProjectContributor - 01 Feb 2006 
     33 

  • trunk/EmptyPlugin/lib/Foswiki/Plugins/EmptyPlugin.pm

    r836 r920  
    3636for information on regarding deprecated handlers that are defined for 
    3737compatibility with older Foswiki versions. 
     38 
     39__BNOTE:__ All but the initPlugin are disabled. To enable a callback, remove =DISABLE_= from the function name. 
     40 
     41%STARTINCLUDE% 
    3842 
    3943__NOTE:__ When writing handlers, keep in mind that these may be invoked 
    … …  
    97101a non-zero value. On non-fatal failure, should write a message 
    98102using Foswiki::Func::writeWarning and return 0. In this case 
    99 %FAILEDPLUGINS% will indicate which plugins failed. 
     103%<nop>FAILEDPLUGINS% will indicate which plugins failed. 
    100104 
    101105In the case of a catastrophic failure that will prevent the whole 
    … …  
    105109You may also call =Foswiki::Func::registerTagHandler= here to register 
    106110a function to handle variables that have standard Foswiki syntax - for example, 
    107 =%MYTAG{"my param" myarg="My Arg"}%. You can also override internal 
     111=%<nop>MYTAG{"my param" myarg="My Arg"}%. You can also override internal 
    108112Foswiki variable handling functions this way, though this practice is unsupported 
    109113and highly dangerous! 
    … …  
    355359XYZ 
    356360</pre> 
     361</verbatim> 
    357362the map will contain: 
    358363<pre> 

  • trunk/core/data/System/Plugins.txt

    r877 r920  
    33---+ Plugins 
    44 
    5 _Add functionality to Foswiki with readily available plugins; create plugins based on APIs_ 
     5_Add functionality to Foswiki with readily available plugins_ 
    66 
    77%TOC% 
    … …  
    2121Most TWiki<sup>&reg;</sup> plugins can also be used with Foswiki if the TWikiCompatibilityPlugin is installed. 
    2222 
    23 __See other types of extensions:__ ContributedAddOns, [[Contribs]], [[Skins]] 
     23__See other types of extensions:__ [[Contribs]], [[Skins]] 
     24 
     25---+ Installed Plugins 
     26%PLUGINDESCRIPTIONS% 
     27 
     28#FailedPlugins 
     29---+ Failed Plugins 
     30%FAILEDPLUGINS% 
    2431 
    2532#InstallPlugin 
    … …  
    5562Some plugins require additional settings or offer extra options that you have to select. Also, you may want to make a plugin available only in certain webs, or temporarily disable it. And may want to list all available plugins in certain topics. You can handle all of these management tasks with simple procedures: 
    5663 
     64---+++ Listing Active Plugins 
     65 
     66Plugin status macros let you list all active plugins wherever needed. 
     67 
     68This site is running Foswiki version *%WIKIVERSION%*, plugin API version 
     69*%PLUGINVERSION{}%* 
     70 
     71#ActivatedPlugins 
     72   * =%<nop>ACTIVATEDPLUGINS%= - shows the activated plugins 
     73   * =%<nop>PLUGINVERSION%= - shows the plugins API version 
     74   * =%<nop>FAILEDPLUGINS%= - shows what plugins failed, and why 
     75 
    5776---+++ Enabling Plugins 
    5877 
    … …  
    7594[[Preference settings]] of active plugins can be retrieved anywhere in Foswiki with =%&lt;pluginname&gt;_&lt;var&gt;%=, such as =%<nop>TABLEPLUGIN_SHORTDESCRIPTION%=. They can also be redefined with the =%&lt;pluginname&gt;_&lt;var&gt;%= setting at a lower level in the [[%LOCALSITEPREFS%]] or at the web level. For an easier upgrade it is recommended to customize plugin preference settings in <nop>%LOCALSITEPREFS% only. 
    7695 
    77 ---+++ Listing Active Plugins 
     96#InstallPlugin 
     97---++ Installing Plugins 
    7898 
    79 Plugin status macros let you list all active plugins wherever needed. 
     99Each Foswiki plugin comes with its own documentation: step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing. Many plugins have an install script that automates these steps for you. 
    80100 
    81 This site is running Foswiki version *%WIKIVERSION%*, plugin API version 
    82 *%PLUGINVERSION{}%* 
     101*Special Requirements:* Some plugins need certain Perl modules to be preinstalled on the host system. Plugins may also use other resources, like graphics, other modules, applications, and templates. You should be able to find detailed instructions in the plugin's documentation. 
    83102 
    84 #ActivatedPlugins 
    85 ---++++ =%<nop>ACTIVATEDPLUGINS%= 
    86 On this Foswiki site, the enabled plugins are: %ACTIVATEDPLUGINS%. 
     103Each plugin has a standard release topic, located in the Foswiki:Extensions web at Foswiki.org. There's usually a number of other related topics, such as a developers page, and an appraisal page. 
    87104 
    88 ---++++ =%<nop>PLUGINDESCRIPTIONS%= 
    89 %PLUGINDESCRIPTIONS% 
     105#PreTesting 
     106---+++ On-Site Pretesting 
    90107 
    91 #FailedPlugins 
    92 ---++++ =%<nop>FAILEDPLUGINS%= 
    93 %FAILEDPLUGINS% 
     108The recommended approach to testing new plugins before making them public is to create a second local Foswiki installation, and test the plugin there. You can allow selected users access to the test area. Once you are satisfied that it won't compromise your main installation, you can install it there as well. 
     109 
     110InstalledPlugins shows which plugins are: 1) installed, 2) loading properly, and 3) what plugin handlers they invoke. Any failures are shown in the Errors section. The =[[VarFAILEDPLUGINS][%<nop>FAILEDPLUGINS%]]= macro can be used to debug failures. You may also want to check your webserver error log and the various Foswiki log files. 
     111 
     112---+++ Some Notes on Plugin Performance 
     113 
     114The performance of the system depends to some extent on the number of plugins installed and on the plugin implementation. Some plugins impose no measurable performance decrease, some do. For example, a Plugin might use many Perl libraries that need to be initialized with each page view (unless you run mod_perl). You can only really tell the performance impact by installing the plugin and by measuring the performance with and without the new plugin, on real data. 
     115 
     116%T% If you need to install an "expensive" plugin, but you only need its functionality only in a subset of your data, you can disable it elsewhere by defining the %<nop>DISABLEDPLUGINS% setting. 
     117 
     118Define =DISABLEDPLUGINS= to be a comma-separated list of names of plugins to disable. Define it in %USERSWEB%.<nop>SitePreferences to disable those plugins everywhere, in the !WebPreferences topic to disable them in an individual web, or in a topic to disable them in that topic. For example, 
     119<pre> 
     120   * <nop>Set DISABLEDPLUGINS = SpreadSheetPlugin, EditTablePlugin 
     121</pre> 
    94122 
    95123#PluginAPI 
    96 ---++ The Foswiki Plugin API 
     124---++ The Foswiki Perl Application Programming Interface 
    97125 
    98 The Application Programming Interface (API) for Foswiki plugins provides the specifications for hooking into the core Foswiki code from your external Perl plugin module. 
    99  
    100 ---+++ Available Core Functions 
    101  
    102 The FoswikiFuncDotPm module (=lib/Foswiki/Func.pm=) describes *all* the interfaces available to plugins. Plugins should *only* use the interfaces described in this module. 
    103  
    104 __%X% Note:__ If you use other core functions not described in =Func.pm=, you run the risk of creating security holes. Also, your plugin will likely break and require updating when you upgrade to a new version of Foswiki. 
    105  
    106 ---+++ Predefined Hooks 
    107  
    108 In addition to Foswiki core functions, plugins can use *predefined hooks*, or *callbacks*, as described in the =lib/Foswiki/Plugins/EmptyPlugin.pm= module. 
    109  
    110    * All but the initPlugin are disabled. To enable a callback, remove =DISABLE_= from the function name. 
    111  
    112 Foswiki:Codev/StepByStepRenderingOrder helps you decide which rendering handler to use. 
    113  
    114 #FastPluginHints 
    115 ---+++ Hints on Writing Fast Plugins 
    116  
    117    * Delay initialization as late as possible. For example, if your plugin is a simple syntax processor, you might delay loading extra Perl modules until you actually see the syntax in the text. 
    118       * For example, use an =eval= block like this:%BR% 
    119         =eval { require IPC::Run }= %BR% 
    120         =return "&lt;font color=\"red\"&gt;SamplePlugin: Can't load required modules ($@)&lt;/font&gt;" if $@;= 
    121    * Keep the main plugin package as small as possible; create other packages that are loaded if and only if they are used. For example, create sub-packages of !BathPlugin in =lib/Foswiki/Plugins/BathPlugin/=. 
    122    * Avoid using preferences in the plugin topic; set =$NO_PREFS_IN_TOPIC= if you possibly can, as that will stop Foswiki from reading the plugin topic for every page. Use [[#ConfigSpec][Config.spec]] instead.  
    123    * Use registered tag handlers 
    124  
    125 ---+++ Version Detection 
    126  
    127 To eliminate the incompatibility problems that are bound to arise from active open plugin development, a plugin versioning system is provided for automatic compatibility checking. 
    128  
    129    * All plugin packages require a =$VERSION= variable. This should be an integer, or a subversion version id. 
    130  
    131    * The =initPlugin= handler should check all dependencies and return 1 if the initialization is OK or 0 if something went wrong. 
    132       * The plugin initialization code does not register a plugin that returns 0 (or that has no =initPlugin= handler). 
    133  
    134    * =$Foswiki::Plugins::VERSION= in the =Foswiki::Plugins= module contains the Foswiki plugin API version, currently *%PLUGINVERSION{}%*. 
    135       * You can also use the =[[VarPLUGINVERSION][%<nop>PLUGINVERSION{}%]]= macro to query the plugin API version or the version of installed plugins. 
    136  
    137 ---+++ Security 
    138  
    139    * Badly written plugins can open huge security holes in Foswiki. This is especially true if care isn't taken to prevent execution of arbitrary commands on the server. 
    140    * Don't allow sensitive configuration data to be edited by users. it is better to add sensitive configuration options to the =%Foswiki::cfg= hash than adding it as preferences in the plugin topic. 
    141       * [[#ConfigSpec][Integrating with <code>configure</code>]] describes the steps 
    142       * Foswiki:Extensions.MailInContrib has an example 
    143       * Foswiki:Extensions.BuildContrib can help you with this 
    144    * Always use the Foswiki::Sandbox to execute commands. 
    145    * Always audit the plugins you install, and make sure you are happy with the level of security provided. While every effort is made to monitor plugin authors activities, at the end of the day they are uncontrolled user contributions. 
    146  
    147 #CreatePlugins 
    148 ---++ Creating Plugins 
    149  
    150 With a reasonable knowledge of the Perl scripting language, you can create new plugins or modify and extend existing ones. Basic plug-in architecture uses an Application Programming Interface (API), a set of software instructions that allow external code to interact with the main program. The [[#PluginAPI][Foswiki Plugin API]] provides the programming interface for Foswiki. 
    151  
    152 ---+++ Anatomy of a Plugin 
    153  
    154 A (very) basic Foswiki plugin consists of two files: 
    155  
    156    * a Perl module, e.g. =MyFirstPlugin.pm= 
    157    * a documentation topic, e.g. =MyFirstPlugin.txt= 
    158  
    159 The Perl module can be a block of code that talks to with Foswiki alone, or it can include other elements, like other Perl modules (including other plugins), graphics, Foswiki templates, external applications (ex: a Java applet), or just about anything else it can call. 
    160 In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the =MyFirstPlugin= topic. Other needed Perl code is best placed in a =lib/Foswiki/Plugins/MyFirstPlugin/= directory. 
    161  
    162 The plugin API handles the details of connecting your Perl module with main Foswiki code. When you're familiar with the [[#PluginAPI][Plugin API]], you're ready to develop plugins. 
    163  
    164 _The Foswiki:Extensions.BuildContrib module provides a lot of support for plugins development, including a plugin creator, automatic publishing support, and automatic installation script writer. If you plan on writing more than one plugin, you probably need it_. 
    165  
    166 ---+++ Creating the Perl Module  
    167  
    168 Copy file =lib/Foswiki/Plugins/EmptyPlugin.pm= to =&lt;name&gt;Plugin.pm=. The =EmptyPlugin.pm= module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the [[#PluginAPI][Plugin API]] specs for more information. 
    169  
    170 If your plugin uses its own modules and objects, you must include the name of the plugin in the package name. For example, write =Package <nop>MyFirstPlugin::Attrs;= instead of just =Package Attrs;=. Then call it using: 
    171 <pre> 
    172 use Foswiki::Plugins::MyFirstPlugin::Attrs; 
    173 $var = MyFirstPlugin::Attrs->new(); 
    174 </pre> 
    175  
    176 #CreatePluginTopic 
    177 ---+++ Writing the Documentation Topic 
    178  
    179 The plugin documentation topic contains usage instructions and version details. It serves the plugin files as %SYSTEMWEB%.FileAttachments for downloading. (The doc topic is also included _in_ the [[#CreatePluginPackage][distribution package]].) To create a documentation topic: 
    180  
    181    1. *Copy* the plugin topic template from Foswiki.org. To copy the text, go to Foswiki:Plugins/PluginPackage and: 
    182       * enter the plugin name in the "How to Create a Plugin" section 
    183       * click Create 
    184       * select all in the Edit box &amp; copy  
    185       * Cancel the edit 
    186       * go back to your site to the %SYSTEMWEB% web 
    187       * In the GoBox enter your plugin name, for example =MyFirstPlugin=, press enter and create the new topic 
    188       * paste &amp; save new plugin topic on your site 
    189    1. *Customize* your plugin topic. 
    190       * Important: In case you plan to publish your plugin on Foswiki.org, use Interwiki names for author names and links to Foswiki.org topics, such as Foswiki:Main/%WIKINAME%. This is important because links should work properly in a plugin topic installed on any Foswiki, not just on Foswiki.org. 
    191    1. *Save* your topic, for use in [[#CreatePluginPackage][packaging]] and [[#PublishPlugin][publishing]] your plugin. 
    192  
    193 <blockquote style="background-color:#f5f5f5"> 
    194 *OUTLINE: Doc Topic Contents* <br /> 
    195 Check the plugins web on Foswiki.org for the latest plugin doc topic template. Here's a quick overview of what's covered: 
    196  
    197 *Syntax Rules:* &lt;<i>Describe any special text formatting that will be rendered.</i>&gt;"  
    198  
    199 *Example:* &lt;<i>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!</i>&gt;" 
    200  
    201 *Plugin Settings:* &lt;<i>Description and settings for custom plugin settings, and those required by Foswiki.</i>&gt;" 
    202  
    203    * *Plugins Preferences* &lt;<i>If user settings are needed, link to [[%SYSTEMWEB%.PreferenceSettings][preference settings]] and explain the role of the plugin name prefix</i> 
    204  
    205 *Plugin Installation Instructions:* &lt;<i>Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.</i>&gt;" 
    206  
    207 *Plugin Info:* &lt;<i>Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the Foswiki:Plugins web.</i>&gt; 
    208 </blockquote> 
    209  
    210 #CreatePluginPackage 
    211 ---+++ Packaging for Distribution 
    212  
    213 The Foswiki:Extensions.BuildContrib is a powerful build environment that is used by the Foswiki project to build Foswiki itself, as well as many of the plugins. You don't *have* to use it, but it is highly recommended! 
    214  
    215 If you don't want (or can't) use the !BuildContrib, then a minimum plugin release consists of a Perl module with a WikiName that ends in =Plugin=, ex: =MyFirstPlugin.pm=, and a documentation page with the same name(=MyFirstPlugin.txt=). 
    216  
    217    1. Distribute the plugin files in a directory structure that mirrors Foswiki. If your plugin uses additional files, include them all: 
    218       * =lib/Foswiki/Plugins/MyFirstPlugin.pm= 
    219       * =data/Foswiki/MyFirstPlugin.txt= 
    220       * =pub/Foswiki/MyFirstPlugin/uparrow.gif= [a required graphic] 
    221    2. Create a zip archive with the plugin name (=MyFirstPlugin.zip=) and add the entire directory structure from Step 1. The archive should look like this: 
    222       * =lib/Foswiki/Plugins/MyFirstPlugin.pm= 
    223       * =data/Foswiki/MyFirstPlugin.txt= 
    224       * =pub/Foswiki/MyFirstPlugin/uparrow.gif= 
    225  
    226 #PublishPlugin 
    227 ---+++ Publishing for Public Use 
    228  
    229 You can release your tested, packaged plugin to the Foswiki community through the Foswiki:Plugins web. All plugins submitted to Foswiki.org are available for download and further development in Foswiki:Plugins/PluginPackage. 
    230  
    231 Publish your plugin by following these steps: 
    232    1. *Post* the plugin documentation topic in the Foswiki:Plugins/PluginPackage: 
    233       * enter the plugin name in the "How to Create a Plugin" section, for example =MyFirstPlugin= 
    234       * paste in the topic text from [[#CreatePluginTopic][Writing the Documentation Topic]] and save 
    235    1. *Attach* the distribution zip file to the topic, ex: =MyFirstPlugin.zip= 
    236    1. *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 Foswiki:Support.) 
    237    1. *Put* the plugin into the SVN repository, see Foswiki:Plugins/ReadmeFirst (optional) 
    238  
    239 %N% Once you have done the above steps once, you can use the !BuildContrib to upload updates to your plugin. 
    240  
    241 Thank you very much for sharing your plugin with the Foswiki community :-) 
    242  
    243 #RecommendedStorageOfPluginData 
    244 ---++ Recommended Storage of Plugin Specific Data 
    245  
    246 Plugins sometimes need to store data. This can be plugin internal data such as cache data, or data generated for browser consumption such as images. Plugins should store data using FoswikiFuncDotPm functions that support saving and loading of topics and attachments. 
    247  
    248 ---+++ Plugin Internal Data 
    249  
    250 You can create a plugin "work area" using the =Foswiki::Func::getWorkArea()= function, which gives you a persistent directory where you can store data files. By default they will not be web accessible. The directory is guaranteed to exist, and to be writable by the webserver user. For convenience, =Foswiki::Func::storeFile()= and =Foswiki::Func::readFile()= are provided to persistently store and retrieve simple data in this area. 
    251  
    252 ---+++ Web Accessible Data 
    253  
    254 __Topic-specific data__ such as generated images can be stored in the topic's attachment area, which is web accessible. Use the =Foswiki::Func::saveAttachment()= function to store the data. 
    255  
    256 Recommendation for file name: 
    257    * Prefix the filename with an underscore (the leading underscore avoids a name clash with files attached to the same topic) 
    258    * Identify where the attachment originated from, typically by including the plugin name in the file name 
    259    * Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues 
    260    * Example: =_GaugePlugin_img123.gif= 
    261  
    262 __Web specific data__ can be stored in the plugin's attachment area, which is web accessible. Use the =Foswiki::Func::saveAttachment()= function to store the data. 
    263  
    264 Recommendation for file names in plugin attachment area: 
    265    * Prefix the filename with an underscore 
    266    * Include the name of the web in the filename 
    267    * Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues 
    268    * Example: =_Main_roundedge-ul.gif= 
    269  
    270 #ConfigSpec 
    271 ---++ Integrating with <code>configure</code> 
    272 Some extensions have setup requirements that are best integrated into =configure= rather than trying to use [[%SYSTEMWEB%.PreferenceSettings][preference settings]]. These extensions use =Config.spec= files to publish their configuration requirements. 
    273  
    274 =Config.spec= files are read during configuration. Once a =Config.spec= has defined a configuration item, it is available for edit through the standard =configure= interface. =Config.spec= files are stored in the 'plugin directory' e.g. =lib/Foswiki/Plugins/BathPlugin/Config.spec=. 
    275  
    276 ---+++ Structure of a <code>Config.spec</code> file 
    277 The =Config.spec= file for a plugin starts with the plugin announcing what it is: 
    278 <verbatim> 
    279 # ---+ BathPlugin 
    280 # This plugin senses the level of water in your bath, and ensures the plug 
    281 # is not removed while the water is still warm. 
    282 </verbatim>  
    283 This is followed by one or more configuration items. Each configuration item has a _type_, a _description_ and a _default_. For example: 
    284 <verbatim> 
    285 # **SELECT Plastic,Rubber,Metal** 
    286 # Select the plug type 
    287 $Foswiki::cfg{BathPlugin}{PlugType} = 'Plastic'; 
    288  
    289 # **NUMBER** 
    290 # Enter the chain length in cm 
    291 $Foswiki::cfg{BathPlugin}{ChainLength} = '30'; 
    292  
    293 # **BOOLEAN EXPERT** 
    294 # Turn this option off to disable the water temperature alarm 
    295 $Foswiki::cfg{BathPlugin}{TempSensorEnabled} = '1'; 
    296 </verbatim> 
    297 The type (e.g. =**SELECT**= ) tells =configure= to how to prompt for the value. It also tells configure how to do some basic checking on the value you actually enter. All the comments between the type and the configuration item are taken as part of the description. The configuration item itself defines the default value for the configuration item. The above spec defines the configuration items =$Foswiki::cfg{BathPlugin}{PlugType}=, =$Foswiki::cfg{BathPlugin}{ChainLength}=, and =$Foswiki::cfg{BathPlugin}{TempSensorEnabled}= for use in your plugin. For example, 
    298 <verbatim> 
    299 if( $Foswiki::cfg{BathPlugin}{TempSensorEnabled} && $curTemperature > 50 ) { 
    300     die "The bathwater is too hot for comfort"; 
    301 } 
    302 </verbatim> 
    303  
    304 The config.spec file is read by configure, and =configure= then writes =LocalSite.cfg= with the values chosen by the local site admin. 
    305  
    306 A range of types are available for use in =Config.spec= files: 
    307  
    308 | BOOLEAN | A true/false value, represented as a checkbox | 
    309 | COMMAND _length_ | A shell command | 
    310 | LANGUAGE | A language (selected from ={LocalesDir}= | 
    311 | NUMBER | A number | 
    312 | OCTAL | An octal number | 
    313 | PASSWORD _length_ | A password (input is hidden) | 
    314 | PATH _length_ | A file path | 
    315 | PERL | A perl structure, consisting of arrays and hashes | 
    316 | REGEX _length_ | A perl regular expression | 
    317 | SELECT _choices_ | Pick one of a range of choices | 
    318 | SELECTCLASS _root_ | Select a perl package (class) | 
    319 | STRING _length_ | A string | 
    320 | URL _length_ | A url | 
    321 | URLPATH _length_ | A relative URL path | 
    322  
    323 All types can be followed by a comma-separated list of _attributes_. 
    324 | EXPERT | means this an expert option | 
    325 | M | means the setting is mandatory (may not be empty) | 
    326 | H | means the option is not visible in =configure= | 
    327  
    328 See =lib/Foswiki.spec= for many more examples. 
    329  
    330 =Config.spec= files are also used for other (non-plugin) extensions. in this case they are stored under the =Contrib= directory instead of the =Plugins= directory. 
    331  
    332 Foswiki:Foswiki/SpecifyingConfigurationItemsForExtensions has supplemental documentation on configure settings. 
    333  
    334 #MaintainPlugins 
    335 ---++ Maintaining Plugins 
    336  
    337 ---+++ Discussions and Feedback on Plugins 
    338  
    339 Each published plugin has a plugin development topic on Foswiki.org. Plugin development topics are named after your plugin and end in =Dev=, such as =MyFirstPluginDev=. The plugin development topic is a great resource to discuss feature enhancements and to get feedback from the Foswiki community. 
    340  
    341 ---+++ Maintaining Compatibility with Earlier Foswiki Versions 
    342  
    343 The plugin interface (FoswikiFuncDotPm functions and plugin handlers) evolve over time. Foswiki introduces new API functions to address the needs of plugin authors. Plugins using unofficial Foswiki internal functions may no longer work on a Foswiki upgrade. 
    344  
    345 Organizations typically do not upgrade to the latest Foswiki for many months. However, many administrators still would like to install the latest versions of a plugin on their older Foswiki installation. This need is fulfilled if plugins are maintained in a compatible manner.  
    346  
    347 __%T% Tip:__ Plugins can be written to be compatible with older and newer Foswiki releases. This can be done also for plugins using unofficial Foswiki internal functions of an earlier release that no longer work on the latest Foswiki codebase.  
    348 Here is an example; the Foswiki:Support.PluginsSupplement has more details. 
    349  
    350 <verbatim> 
    351     if( $Foswiki::Plugins::VERSION >= 1.1 ) { 
    352         @webs = Foswiki::Func::getListOfWebs( 'user,public' ); 
    353     } else { 
    354         @webs = Foswiki::Func::getPublicWebList( ); 
    355     } 
    356 </verbatim> 
    357  
    358 ---+++ Handling deprecated functions 
    359  
    360 From time-to-time, the Foswiki developers will add new functions to the interface (either to FoswikiFuncDotPm, or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable. When this happens, the deprecated functions will be supported in the interface for at least one more Foswiki release, and probably longer, though this cannot be guaranteed. 
    361  
    362 When a plugin defines deprecated handlers, a warning will be shown in the list generated by %<nop>FAILEDPLUGINS%. Admins who see these warnings should check Foswiki.org and if necessary, contact the plugin author, for an updated version of the plugin. 
    363  
    364 Updated plugins may still need to define deprecated handlers for compatibility with old Foswiki versions. In this case, the plugin package that defines old handlers can suppress the warnings in %<nop>FAILEDPLUGINS%. 
    365  
    366 This is done by defining a map from the handler name to the =Foswiki::Plugins= version _in which the handler was first deprecated_. For example, if we need to define the =endRenderingHandler= for compatibility with =Foswiki::Plugins= versions before 1.1, we would add this to the plugin: 
    367  
    368 <verbatim> 
    369 package Foswiki::Plugins::SinkPlugin; 
    370 use vars qw( %FoswikiCompatibility ); 
    371 $FoswikiCompatibility{endRenderingHandler} = 1.1; 
    372 </verbatim> 
    373 If the currently-running Foswiki version is 1.1 _or later_, then the _handler will not be called_ and _the warning will not be issued_. Foswiki with versions of =Foswiki::Plugins= before 1.1 will still call the handler as required. 
     126[[Developing plugins]] provides a simple introduction to hooking into Foswiki code from your own Perl modules. Foswiki:Development.GettingStarted is the starting point for more comprehensive documentation. 
    374127 
    375128%STOPINCLUDE% 
    376 __Related Topics:__ DeveloperDocumentationCategory, AdminDocumentationCategory, Foswiki:Support.PluginsSupplement 
    377  
     129__Related Topics:__ DeveloperDocumentationCategory, AdminDocumentationCategory 

  • trunk/core/data/System/VarINCLUDE.txt

    r851 r920  
    99     | ="Web.Topic"= | A topic in another web, i.e. =%<nop>INCLUDE{"%SYSTEMWEB%.SiteMap"}%= | | 
    1010     | ="http://..."= | A full qualified URL, i.e. =%<nop>INCLUDE{"http://foswiki.org:80/index.html"}%=. Supported content types are =text/html= and =text/plain=. <br /> %I% if the URL resolves to an attachment file on the server this will _automatically_ translate to a server-side include. | | 
     11     | ="doc:Foswiki::..." level="3" | Generates the embedded documentation in the given perl module. The optional =level= parameter lets you define the base level for headings in the included text. | 
    1112     | =pattern="..."= |Include a subset of a topic or a web page. Specify a RegularExpression that scans from start (='^'=) to end and contains the text you want to keep in parenthesis, e.g., =pattern="^.*?(from here.*?to here).*"=. IncludeTopicsAndWebPages has more. | none | 
    1213     | =rev="2"= | Include a previous topic revision; N/A for URLs | top revision | 

  • trunk/core/lib/Foswiki.pm

    r840 r920  
    193193        ATTACHURL         => \&ATTACHURL, 
    194194        ATTACHURLPATH     => \&ATTACHURLPATH, 
     195        COREPOD           => \&COREPOD, 
    195196        DATE              => \&DATE, 
    196197        DISPLAYTIME       => \&DISPLAYTIME, 
    … …  
    35533554      || $this->{prefs}->getPreferencesValue('INCLUDEWARNING'); 
    35543555 
    3555     if ( $path =~ /^https?\:/ ) { 
     3556    if ( $path =~ /^https?:/ ) { 
    35563557 
    35573558        # include web page 
    3558         return _includeUrl( $this, $path, $pattern, $includingWeb, 
     3559        return $this->_includeUrl( $path, $pattern, $includingWeb, 
    35593560            $includingTopic, $raw, $params, $warn ); 
     3561    } 
     3562 
     3563    if ( $path =~ s/^doc:// ) { 
     3564 
     3565        # include web page 
     3566        return $this->_includeCodeDoc( $path, $pattern, $params ); 
    35603567    } 
    35613568 
    … …  
    45054512 
    45064513    return '| *Group* | *Members* |' . "\n" . join( "\n", sort @table ); 
     4514} 
     4515 
     4516# Include embedded doc in a core module 
     4517sub _includeCodeDoc { 
     4518    my ( $this, $class, $pattern, $params ) = @_; 
     4519 
     4520    return '' unless $class && $class =~ /^Foswiki/; 
     4521    $class =~ s/[^\w:]//g; 
     4522 
     4523    my $pmfile; 
     4524    $class =~ s#::#/#g; 
     4525    foreach my $inc (@INC) { 
     4526        if ( -f "$inc/$class.pm" ) { 
     4527            $pmfile = "$inc/$class.pm"; 
     4528            last; 
     4529        } 
     4530    } 
     4531    return '' unless $pmfile; 
     4532 
     4533    open( PMFILE, '<', $pmfile ) || return ''; 
     4534    my $inPod = 0; 
     4535    my $pod = ''; 
     4536    local $/ = "\n"; 
     4537    while ( my $line = <PMFILE> ) { 
     4538        if ( $line =~ /^=(begin|pod)/ ) { 
     4539            $inPod = 1; 
     4540        } 
     4541        elsif ( $line =~ /^=cut/ ) { 
     4542            $inPod = 0; 
     4543        } 
     4544        elsif ($inPod) { 
     4545            $pod .= $line; 
     4546        } 
     4547    } 
     4548    close(PMFILE); 
     4549 
     4550    $pod =~ s/.*?%STARTINCLUDE%//s; 
     4551    $pod =~ s/%STOPINCLUDE%.*//s; 
     4552 
     4553    $pod = applyPatternToIncludedText( $pod, $pattern ) if ($pattern); 
     4554 
     4555    # Adjust the root heading level 
     4556    if ( $params->{level} ) { 
     4557        my $minhead = '+' x 100; 
     4558        $pod =~ s/^---(\++)/ 
     4559          $minhead = $1 if length($1) < length($minhead); "---$1"/gem; 
     4560        return $pod if length($minhead) == 100; 
     4561        my $newroot = '+' x $params->{level}; 
     4562        $minhead =~ s/\+/\\+/g; 
     4563        $pod =~ s/^---$minhead/---$newroot/gm; 
     4564    } 
     4565    return $pod; 
    45074566} 
    45084567 

  • trunk/core/lib/Foswiki/Contrib/core/MANIFEST

    r906 r920  
    8585data/System/DeleteOrRenameAnAttachment.txt 0644 
    8686data/System/DeveloperDocumentationCategory.txt 0644 
     87data/System/DevelopingPlugins.txt 0644 
    8788data/System/DocumentGraphics.txt 0644 
    8889data/System/DontNotify.txt 0644 
    … …  
    120121data/System/MoveTopic.txt 0644 
    121122data/System/ObjectMethod.txt 0644 
     123data/System/PerlDoc.txt 0644 
    122124data/System/PlainSkin.txt 0644 
    123125data/System/Plugins.txt 0644 

  • trunk/core/lib/Foswiki/OopsException.pm

    r830 r920  
    2525                            topic => $topic, 
    2626                            params => [ 'bigtoe', 'hot tap' ] ); 
     27</verbatim> 
    2728 
    2829=cut 
Note: See TracChangeset for help on using the changeset viewer.