# TWiki Plugins _Add functionality to TWiki with readily available plugins; create plugins based on APIs_
[[%FAILEDPLUGINS%|Main/VarFAILEDPLUGINS]]
variable can be used to debug failures. You may also want to check your webserver error log and the various TWiki log files.
### 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. Use the TWiki:Plugins.PluginBenchmarkAddOn, or test manually with the Apache `ab` utility. Example on Unix:%BR% `time wget -qO /dev/null http://www.dementia.org/twiki/view/%SYSTEMWEB%/AbcPlugin`
%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 %DISABLEDPLUGINS% TWiki variable.
Define `DISABLEDPLUGINS` to be a comma-separated list of names of plugins to disable. Define it in %USERSWEB%.TWikiPreferences 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:
### Enabling Plugins
Plugins can be enabled and disabled with the [configure](http://www.dementia.org/twiki/configure) script. An installed plugin needs to be enabled before it can be used.
### Plugin Evaluation Order
By default, TWiki executes plugins in alphabetical order on plugin name. It is possible to change the order, for example to evaluate database variables before the spreadsheet CALCs. This can be done with `{PluginsOrder}` in the plugins section of [configure](http://www.dementia.org/twiki/configure).
### Plugin-Specific Settings
Some plugins are configured with plugin preferences variables, newer plugins with configure variables.
Configure variables are accessible though the [configure](http://www.dementia.org/twiki/configure) interface.
Plugin preferences variables are defined in the plugin topic and can be overloaded. The SHORTDESCRIPTION preferences variable is always present, it is needed for the TWiki:Plugins repository on twiki.org. Example preferences variable defined in the [[TablePlugin]] topic:
- `Set SHORTDESCRIPTION = Control attributes of tables and sorting of table columns`
Preferences variables of active plugins can be retrieved anywhere in TWiki with `%Plugin | Errors |
---|---|
[[TWiki/SpreadSheetPlugin]] | Plugins: could not fully register SpreadSheetPlugin, no plugin topic |
[[TWiki/CommentPlugin]] | Plugins: could not fully register CommentPlugin, no plugin topic |
[[TWiki/EditTablePlugin]] | Plugins: could not fully register EditTablePlugin, no plugin topic |
[[TWiki/InterwikiPlugin]] | Plugins: could not fully register InterwikiPlugin, no plugin topic |
[[TWiki/PreferencesPlugin]] | Plugins: could not fully register PreferencesPlugin, no plugin topic |
[[TWiki/SlideShowPlugin]] | Plugins: could not fully register SlideShowPlugin, no plugin topic |
[[TWiki/SmiliesPlugin]] | Plugins: could not fully register SmiliesPlugin, no plugin topic |
[[TWiki/TablePlugin]] | Plugins: could not fully register TablePlugin, no plugin topic |
[[TWiki/TwistyPlugin]] | Plugins: could not fully register TwistyPlugin, no plugin topic |
Handler | Plugins |
---|---|
beforeCommonTagsHandler | PreferencesPlugin TwistyPlugin |
beforeSaveHandler | CommentPlugin |
commonTagsHandler | SpreadSheetPlugin CommentPlugin EditTablePlugin SlideShowPlugin SmiliesPlugin |
initPlugin | SpreadSheetPlugin CommentPlugin EditTablePlugin InterwikiPlugin PreferencesPlugin SlideShowPlugin SmiliesPlugin TablePlugin TwistyPlugin |
postRenderingHandler | EditTablePlugin PreferencesPlugin TwistyPlugin |
preRenderingHandler | InterwikiPlugin SmiliesPlugin TablePlugin |
[[%PLUGINVERSION{}%|Main/VarPLUGINVERSION]]
variable to query the plugin API version or the version of installed plugins.
### Security
- Badly written plugins can open huge security holes in TWiki. 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. it is better to add sensitive configuration options to the `%TWiki::cfg` hash than adding it as preferences in the plugin topic.
- [[Integrating with configure|Main/WebHome#ConfigSpec]] describes the steps
- TWiki:Plugins.MailInContrib has an example
- TWiki:Plugins.BuildContrib can help you with this
- Always use the TWiki::Sandbox to execute commands.
- 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.
## Creating Plugins
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 [[TWiki Plugin API|Main/WebHome#PluginAPI]] provides the programming interface for TWiki.
### Anatomy of a Plugin
A (very) basic TWiki plugin consists of two files:
- a Perl module, e.g. `MyFirstPlugin.pm`
- a documentation topic, e.g. `MyFirstPlugin.txt`
The Perl module can be a block of code that talks to with TWiki alone, or it can include other elements, like other Perl modules (including other plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call. 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/TWiki/Plugins/MyFirstPlugin/` directory.
The plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the [[Plugin API|Main/WebHome#PluginAPI]], you're ready to develop plugins.
_The TWiki:Plugins.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_.
### Creating the Perl Module
Copy file `lib/TWiki/Plugins/EmptyPlugin.pm` to `BOOLEAN | A true/false value, represented as a checkbox |
COMMAND length | A shell command |
LANGUAGE | A language (selected from {LocalesDir} |
NUMBER | A number |
OCTAL | An octal number |
PASSWORD length | A password (input is hidden) |
PATH length | A file path |
PERL | A perl structure, consisting of arrays and hashes |
REGEX length | A perl regular expression |
SELECT choices | Pick one of a range of choices |
SELECTCLASS root | Select a perl package (class) |
STRING length | A string |
URL length | A url |
URLPATH length | A relative URL path |
EXPERT | means this an expert option |
M | means the setting is mandatory (may not be empty) |
H | means the option is not visible in configure |