Foswiki Plugins

Extensions that use a simple API to talk to Foswiki

Overview

You can add plugins to extend Foswiki functionality without altering the core code. A plug-in approach lets you:

• add virtually unlimited features while keeping the main Foswiki code compact and efficient;
• heavily customize an installation and still do clean updates to new versions of Foswiki;
• rapidly develop new Foswiki functions in Perl using the plugin API.

Everything to do with Foswiki plugins - demos, new releases, downloads, development, general discussion - is available at Foswiki.org, in the Foswiki:Extensions web.

Foswiki plugins are developed and contributed by interested members of the community. Plugins are provided on an 'as is' basis; they are not a part of Foswiki, but are independently developed and maintained.

Most TWiki^® plugins can also be used with Foswiki if the TWikiCompatibilityPlugin is installed.

See other types of extensions: AddOns,Contribs, Skins

See InstalledPlugins for a list of plugins installed on this site.

Installing Plugins

Each plugin comes with its own documentation page, which includes step-by-step installation instructions, a detailed description of any special requirements, and version details. Many also have a working example for testing.

The easiest way to install plugins is to use the configure interface. However you can also install plugins from the command-line. Every plugin comes with installation instructions.

Each 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. After installation, a copy of this page will be installed to your System web.

If you install a plugin and it doesn't seem to work, then you can get information on all the installed plugins that may help to resolve the issue.

Failing that, you may want to check your webserver error log and the various Foswiki log files, and any notes in the support topic for the plugin (linked from the plugin front page).

Some Notes on Plugin Performance

The 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.

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 %DISABLEDPLUGINS% setting.

Define DISABLEDPLUGINS to be a comma-separated list of names of plugins to disable. Define it in 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,

   * Set DISABLEDPLUGINS = SpreadSheetPlugin, EditTablePlugin

Managing Installed Plugins

Some 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:

Listing Active Plugins

Plugin status macros let you list all active plugins wherever needed.

This site is running Foswiki version v2.1.9, plugin API version 2.5

• %ACTIVATEDPLUGINS% - shows the activated plugins
• %PLUGINVERSION% - shows the plugins API version
• %FAILEDPLUGINS% - shows what plugins failed, and why

Enabling Plugins

Plugins can be enabled and disabled with the configure script. An installed plugin needs to be enabled before it can be used. Plugins can also be selectively disabled again using the DISABLED_PLUGINS preference, as described above.

Plugin Evaluation Order

By default, plugins are executed in alphabetical order of plugin name. It is possible to change the order, for example to evaluate database macros before the spreadsheet CALCs, using the {PluginsOrder} in the Extensions section of configure.

Plugin-Specific Settings

Some plugins are configured with plugin preference settings, some with configure settings, and some with both. The plugin topic will contain details.

configure settings are accessible though the configure interface.

Note that some older plugins use preference settings defined in the plugin topic. For example, the (fictional) BathPlugin topic might contain:

• Set ELECTRIC = on

This setting defines the default value for the preference BATHPLUGIN_ELECTRIC. You should never edit the BathPlugin topic to change this setting; instead, override the setting by defining BATHPLUGIN_ELECTRIC as described in preference settings.

Developing your own plugins

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.

Related Topics: DeveloperDocumentationCategory, AdminDocumentationCategory