Developing Plugins

The 3048m view of how Foswiki works

The scripts are responsible for interpreting the parameters passed in the request, and generating a response that is sent back to the browser, usually in the form of an HTML page.

1. The template engine reads predefined templates from files on the server. These templates contain directives that are expanded by the engine to create the output HTML skeleton. One of these directives expands to the topic text.
2. The macro engine then expands the Macros in the skeleton. This is also where macros registered by plugins are expanded.
   • Macros, including those registered by plugins, are processed in a strict left-right-inside-out processing order. See Macros for more details.
   • Macros include things like searches, so this is usually the slowest part of generating a page.
3. The TML (Topic Markup Language) engine now processes the expanded text, looking for TML constructs such as bulleted lists and tables. It generates HTML for these constructs.

Once all the engines have run, the output is sent to the browser.

1. They can register macros that are expanded by the macro engine. This is the simplest kind of plugin.
2. The can interact with various points in the rendering pipeline by implementing handlers (callbacks).
3. They can register REST handlers that are invoked via the rest script to support some form of transaction outside those supported by the standard scripts.

APIs available to Extensions

• Foswiki::Func - this is the package you will use most. This package exposes a lot of core functionality in a way that is friendly to extension writers. If you find that there are two ways of doing something - a Foswiki::Func way, and another call to one of the packages below, then the Foswiki::Func way is almost always the right way.
• Foswiki::Meta - topic and web meta-data. Certain Foswiki::Func methods, and some plugin handlers, are passed (or return) objects of this type. Almost all of the methods of Foswiki::Meta have analagous methods in Foswiki::Func - in general you should call the Foswiki::Func methods in preference to calling Foswiki::Meta methods directly.
• Foswiki::OopsException - special exception for invoking the 'oops' script
• Foswiki::AccessControlException - access control exception
• Foswiki::Attrs - parser and storage object for macro parameters
• Foswiki::Time - time parsing and formatting
• Foswiki::Sandbox - safe server-side program execution, used for calling external programs.
• Iterators - these are classes that implement the Foswiki::Iterator specification
  • Foswiki::ListIterator - utility class for iterator objects that iterate over list contents
  • Foswiki::LineIterator - utility class for iterator objects that iterate over lines in a block of text
  • Foswiki::AggregateIterator - utility class for iterator objects that aggregate other iterators into a single iteration

• $Foswiki::Plugins::VERSION - plugin handler API version number
• $Foswiki::Plugins::SESSION - reference to Foswiki singleton object
• $Foswiki::cfg - reference to configuration hash
• $Foswiki::regex - see Standard Regular Expressions, below

Foswiki:Development.GettingStarted is the starting point for more comprehensive documentation on developing for Foswiki.

Standard Regular Expressions

   my $isCapitalizedWord =
     ( $s =~ /[$Foswiki::regex{upperAlpha}][$Foswiki::regex{mixedAlpha}]+/ );

   my $isWebName = ( $s =~ m/$Foswiki::regex{webNameRegex}/ );

Name	Matches	Type
wikiWordRegex	WikiWords	RE
webNameRegex	User web names	RE
topicNameRegex	Topic names	RE
anchorRegex	#AnchorNames	RE
abbrevRegex	Abbreviations/Acronyms e.g. GOV, IRS	RE
emailAddrRegex	email@address.com	RE
tagNameRegex	Standard macro names e.g. %THIS_BIT% (THIS_BIT only)	RE
upperAlpha	Upper case characters	String
upperAlphaNum	Upper case characters and digits	String
lowerAlpha	Lower case characters	String
lowerAlphaNum	Lower case characters and digits	String
numeric	Digits	String
mixedAlpha	Alphabetic characters	String
mixedAlphaNum	Alphanumeric characters	String

Creating New Plugins

With a reasonable knowledge of the Perl scripting language, you can create new plugins or modify and extend existing ones.

Anatomy of a Plugin

A (very) basic Foswiki plugin consists of two files:

• a Perl module, e.g. lib/Foswiki/Plugins/MyFirstPlugin.pm
• a documentation topic, e.g. MyFirstPlugin.txt

The Perl module can invoke other, non-Foswiki, elements, like other Perl modules (including other plugins), graphics, external applications, or just about anything else that Perl can call.

The plugin API handles the details of connecting your Perl module with the Foswiki core.

Creating the Perl Module

Writing the Documentation Topic

1. Copy the plugin topic template from EmptyPlugin
2. Customize your plugin topic.
   • 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/WikiGuest. This is important because links should work properly in a plugin topic installed on any Foswiki, not just on Foswiki.org.
3. Save your topic, for use in packaging and publishing your plugin.

Packaging for Distribution

1. Distribute the plugin files in a directory structure that mirrors Foswiki. If your plugin uses additional files, include them all:
   • lib/Foswiki/Plugins/MyFirstPlugin.pm
   • data/Foswiki/MyFirstPlugin.txt
   • pub/Foswiki/MyFirstPlugin/uparrow.gif [a required graphic]
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:
   • lib/Foswiki/Plugins/MyFirstPlugin.pm
   • data/Foswiki/MyFirstPlugin.txt
   • pub/Foswiki/MyFirstPlugin/uparrow.gif

Publishing for Public Use

1. Post the plugin documentation topic to the Foswiki:Extensions web
2. Attach the distribution zip file(s) to the topic, eg: MyFirstPlugin.zip
3. Add a user support hub by visiting Foswiki:Support.CreateNewSupportHub
4. Optionally, check in the sources to the Foswiki subversion repository (see Foswiki:Development.HowToStartExtensionDevelopmentInSubversion)

Hints on Writing Fast Plugins

• 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.
  • For example, use an eval block like this:
    eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
• 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/.
• 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 Config.spec instead.
• Use registered tag handlers

Security

• 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.
• 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.
  • Integrating with configure describes the steps
  • Foswiki:Extensions.MailInContrib has an example
  • Foswiki:Extensions.BuildContrib can help you with this
• Make sure that all user input is checked and validated. Be especially careful to filter characters that might be used in perl string interpolation.
• Avoid eval, and if you must use it make sure you sanitise parameters
• Always use the Foswiki::sandbox to execute commands. Never use backtick or qx//.
• Use Foswiki::Func::checkAccessPermission to check the access rights of the current user.
• 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.

Recommended Storage of Plugin Specific Data

Plugin Internal Data

Web Accessible Data

The internal data area is not normally made web-accessible for security reasons. If yoou want to store web accessible data, for example generated images, then you should use Foswiki's attachment mechanisms.

• Prefix the filename with an underscore (the leading underscore avoids a name clash with files attached to the same topic)
• Identify where the attachment originated from, typically by including the plugin name in the file name
• Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues
• Example: _GaugePlugin_img123.gif

Integrating with configure

Naming of Config.spec elements

Config namespace Rules going forward:

• Existing extensions should probably not be restructured, to avoid configuration migration issues.
• If developing a "Contrib" or "Skin", configuration should live under {Extensions}, even if it has a Plugin component.
• If developing a "Plugin", it can use {Plugins} space but this is no longer recommended.
• Never store settings at the root level.

Never assign a value to a level that will have sub-values: THIS WILL FAIL! Don't do this.

   $Foswiki::cfg{Plugins}{BathPlugin} = "Take a bath here";
   $Foswiki::cfg{Plugins}{BathPlugin}{PlugType} = "rubber stopper";

Structure of a Config.spec file

# ---+ Extensions

# ----++ BathPlugin
# This plugin senses the level of water in your bath, and ensures the plug
# is not removed while the water is still warm.

# **SELECT Plastic,Rubber,Metal**
# Select the plug type
$Foswiki::cfg{Plugins}{BathPlugin}{PlugType} = 'Plastic';

# **NUMBER**
# Enter the chain length in cm
$Foswiki::cfg{Plugins}{BathPlugin}{ChainLength} = '30';

# **BOOLEAN EXPERT**
# Turn this option off to disable the water temperature alarm
$Foswiki::cfg{BathPlugin}{TempSensorEnabled} = '1';

if( $Foswiki::cfg{Plugins}{BathPlugin}{TempSensorEnabled} && $curTemperature > 50 ) {
    die "The bathwater is too hot for comfort";
}

$Foswiki::cfg{Plugins}{BathPlugin}{MyBath} = "$Foswiki::cfg{PubDir}/enamel.gif"; # BAD
# Perl will interpolate variables in double-quotes, so $Foswiki::cfg{PubDir}
# will be evaluated at configuration time, which will make reconfiguration
# difficult.

$Foswiki::cfg{Plugins}{BathPlugin}{MyBath} = '$Foswiki::cfg{PubDir}/enamel.gif'; # GOOD
# The single quotes make sure $Foswiki::cfg{PubDir} will only be evaluated
# at run-time.

# **ENHANCE {Store}{Implementation}**
# Documentation for a new store implementation here

DISPLAY_IF and ENABLE_IF

# **BOOLEAN DISPLAY_IF {Other}{Option}=='RequiredValue'**

# **BOOLEAN DISPLAY_IF {An}{Option}=='RequiredValue' /DISPLAY_IF ENABLE_IF {Another}{Option}=='AnotherValue' **

**STRING DISPLAY_IF {This}{BOOLEAN}{Option} **

---+ Extensions
---++ BathPlugin
$Foswiki::cfg{Plugins}{BathPlugin}{PlugType} = 'rubber';
$Foswiki::cfg{Extensions}{BathPlugin}{ToyType} = 'duckie';
$Foswiki::cfg{foobar} = 'some archaic root-level setting';

Linking to configure

(As of Foswiki 2.0, it is no longer possible to directly link into Configure tabs.

Maintaining Plugins

Discussions and Feedback on Plugins

Usually published plugins have a support hub in the Support web on Foswiki.org.Support hubs have links to where to discuss feature enhancements and give feedback to the developer and user communities.

Maintaining Compatibility with Earlier Foswiki Versions

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.

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. Here is an example; the Foswiki:Support.PluginsSupplement has more details.

    if( $Foswiki::Plugins::VERSION >= 1.1 ) {
        @webs = Foswiki::Func::getListOfWebs( 'user,public' );
    } else {
        @webs = Foswiki::Func::getPublicWebList( );
    }

Handling deprecated functions

When a plugin defines deprecated handlers, a warning will be shown in the list generated by %FAILEDPLUGINS%. Admins who see these warnings should check Foswiki.org and if necessary, contact the plugin author, for an updated version of the plugin.

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 %FAILEDPLUGINS%.

package Foswiki::Plugins::SinkPlugin;
use vars qw( %FoswikiCompatibility );
$FoswikiCompatibility{endRenderingHandler} = 1.1;

TWiki^® Plugins