Ignore:
Timestamp:
12/09/08 18:16:48 (3 years ago)
Author:
CrawfordCurrie
Message:

Item253: remove TWikiDrawPlugin hack; analyse, rationalise and document usage of redirectto; Item5926: added encodings that were proposed to make chinese work (they don't break anything AFAICT). Deprecate Foswiki::Func::getRegularExpression (the regex array is published)

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r1041 r1221  
    11---+ Developing Plugins 
    22 
    3 Foswiki has a large number of internal (perl code) interfaces that give access to all the internal functionality. However in general it's a bad idea to use these interfaces to extend Foswiki, because that would result in your code breaking every time the core changes. 
     3Foswiki has a large number of internal (perl code) interfaces. However in general it's a bad idea to use these interfaces to extend Foswiki, because that would result in your code breaking every time the core changes. 
    44 
    55To address this problem Foswiki provides a number of Application Program Interfaces (APIs) that allow you to extend Foswiki in a robust way. 
    … …  
    77The usual way Foswiki is extended is by writing a _Plugin_. Plugins extend Foswiki by providing functions that 'listen' to events in the Foswiki core, and handling these events. These functions are called "Plugin Handlers" and they are described in depth in %SYSTEMWEB%.EmptyPlugin and =lib/Foswiki/Plugins/EmptyPlugin.pm=. 
    88 
    9 To be robust plugins must avoid using any unpublished functionality from the Foswiki core. Functionality that is available to plugins consists of the following perl packages. Click on the name of the packge to see the full documentation. 
     9To be robust extensions must avoid using any unpublished functionality from the Foswiki core. The following perl packages give access to features for extension authors. These APIs are not just for Plugins, they can be used in any type of extension. Click on the name of the package to see the full documentation. 
    1010   * =[[%SCRIPTURL{view}%/%SYSTEMWEB%/PerlDoc?module=Foswiki::Plugins::EmptyPlugin][Foswiki::Plugins::EmptyPlugin]]= - template plugin for you to use as a starting point for your own plugins. 
    1111   * =[[%SCRIPTURL{view}%/%SYSTEMWEB%/PerlDoc?module=Foswiki::Func][Foswiki::Func]]= - bridge to core functions. This is the package you will use most. 
    … …  
    1919   * =$Foswiki::Plugins::SESSION= - reference to =Foswiki= singleton object 
    2020   * =$Foswiki::cfg= - reference to configuration hash 
     21   * =$Foswiki::regex - see 'Standard Regular Expressions', below 
    2122   * =$Foswiki::sandbox= - reference to the static sandbox object (type =Foswiki::Sandbox=), used for calling external programs. 
    2223%I% Foswiki:Development.GettingStarted  is the starting point for more comprehensive documentation on developing for Foswiki. 
    2324 
    24 ---+++ Predefined Hooks 
    25  
    26 Plugins 'listen' to events happening in the core by registering an interest in those events. They do this using 'plugin handlers'. these are simply functions with a particular name that, if they exist in your plugin, will be called by the core. 
    27  
    28 Foswiki:Development.StepByStepRenderingOrder helps you decide which rendering handler to use. See EmptyPlugin for a full list of the handlers that are defined. 
     25__Note__ the APIs are available to all extensions, but rely on a 
     26=Foswiki= singleton object having been created before the APIs can be used. 
     27This will only be a problem if you are writing an extension that doesn't 
     28use the standard initialisation sequence. 
     29 
     30---+++ Standard Regular Expressions 
     31A number of standard regular expressions are available for use in extensions, in the =$Foswiki::regex= hash. these regular expressions are precompiled in an 
     32<nop>I18N-compatible manner. The 
     33following are guaranteed to be present. Others may exist, but their use 
     34is unsupported and they may be removed in future Foswiki versions. 
     35 
     36In the table below, the expression marked type 'String' are intended for 
     37use within character classes (i.e. for use within square brackets inside 
     38a regular expression), for example: 
     39<verbatim> 
     40   my $isCapitalizedWord = 
     41     ( $s =~ /[$Foswiki::regex{upperAlpha}][$Foswiki::regex{mixedAlpha}]+/ ); 
     42</verbatim> 
     43Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example: 
     44<verbatim> 
     45   my $isWebName = ( $s =~ m/$Foswiki::regex{webNameRegex}/ ); 
     46</verbatim> 
     47 
     48| *Name*         | *Matches*                        | *Type* | 
     49| upperAlpha     | Upper case characters            | String | 
     50| upperAlphaNum  | Upper case characters and digits | String | 
     51| lowerAlpha     | Lower case characters            | String | 
     52| lowerAlphaNum  | Lower case characters and digits | String | 
     53| numeric        | Digits                           | String | 
     54| mixedAlpha     | Alphabetic characters            | String | 
     55| mixedAlphaNum  | Alphanumeric characters          | String | 
     56| wikiWordRegex  | WikiWords                        | RE | 
     57| webNameRegex   | User web names                   | RE | 
     58| topicNameRegex | Topic names                      | RE | 
     59| anchorRegex    | #AnchorNames                     | RE | 
     60| abbrevRegex    | Abbreviations/Acronyms e.g. GOV, IRS | RE | 
     61| emailAddrRegex | email@address.com                | RE | 
     62| tagNameRegex   | Standard macro names e.g. %<nop>THIS_BIT% (THIS_BIT only) | RE | 
     63 
     64---+++ Predefined Hooks for Plugins 
     65 
     66Plugins 'listen' to events happening in the core by registering an interest in those events. They do this by declaring 'plugin handlers'. These are simply functions with a particular name that, if they exist in your plugin, will be called by the core. 
     67 
     68Foswiki:Development.StepByStepRenderingOrder helps you decide which rendering handler to use. See [[EmptyPlugin]] for a full list of the handlers that are defined. 
    2969 
    3070#FastPluginHints 
    … …  
    4484 
    4585   * All plugin packages require a =$VERSION= variable. This should be an integer, or a subversion version id. 
    46  
    4786   * The =initPlugin= handler should check all dependencies and return 1 if the initialization is OK or 0 if something went wrong. 
    4887      * The plugin initialization code does not register a plugin that returns 0 (or that has no =initPlugin= handler). 
    49  
    5088   * =$Foswiki::Plugins::VERSION= in the =Foswiki::Plugins= module contains the Foswiki plugin API version, currently *%PLUGINVERSION{}%*. 
    5189      * You can also use the =[[VarPLUGINVERSION][%<nop>PLUGINVERSION{}%]]= macro to query the plugin API version or the version of installed plugins. 
    … …  
    5391---+++ Security 
    5492 
    55    * 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. 
    56    * 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. 
     93   * Badly written plugins can open security holes in Foswiki. This is especially true if care isn't taken to prevent execution of arbitrary commands on the server. 
     94   * Don't allow sensitive configuration data to be edited by users. Use the =%Foswiki::cfg= hash for configuration options. Don't ask installers to edit topics in the System web. 
    5795      * [[#ConfigSpec][Integrating with <code>configure</code>]] describes the steps 
    5896      * Foswiki:Extensions.MailInContrib has an example 
    5997      * Foswiki:Extensions.BuildContrib can help you with this 
    60    * Always use the Foswiki::Sandbox to execute commands. 
     98   * Make sure that all user input is checked and validated. Be especially careful to filter characters that might be used in perl string interpolation. 
     99   * Avoid =eval=, and if you must use it make sure you sanitise parameters 
     100   * Always use the Foswiki::sandbox to execute commands. Never use backtick or qx//. 
    61101   * 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. 
    62102 
Note: See TracChangeset for help on using the changeset viewer.