TWiki Plugins

Preinstalled Plugins

• DefaultPlugin? : Optionally handles some legacy variables from older versions of TWiki. You can control this option from TWikiPreferences. (Perl programmers can also add rules for simple custom processing.)
• EmptyPlugin: Is a fully functional module, minus active code; it does nothing and serves as a template for new Plugin development
• CommentPlugin: Allows users to quickly post comments to a page without an edit/preview/save cycle.
• InterwikiPlugin: Use it for shorthand linking to remote sites, ex: TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can edit the predefined set of of Wiki-related sites, and add your own
• EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
• RenderListPlugin: Render bullet lists in a variety of formats
• SlideShowPlugin: Create web based presentations based on topics with headings.
• SmiliesPlugin: Render smilies as icons, like for  :-) or for  :eek:
• SpreadSheetPlugin: Add spreadsheet calculation like "$SUM( $ABOVE() )" to TWiki tables and other topic text
• TablePlugin: Control attributes of tables and sorting of table columns

1. Download the zip file containing the Plugin, documentation, and any other required files, from TWiki:Plugins.
2. Distribute the files to their proper locations - unzip the zip archive in your TWiki installation directory - if have a standard TWiki installation, this will distribute automatically. Otherwise, place the files according to the directory paths listed on the Plugin top in TWiki:Plugins.
3. Check the demo example on the Plugin topic: if it's working, the installation was fine!

Special Requests: Some Plugins need certain Perl modules to be preinstalled on the host system. Plugins may also use other resources, like graphics, other modules, applications, templates. In these cases, detailed instructions are in the Plugin documentation.

Each Plugin has a standard release page, located in the TWiki:Plugins web at TWiki.org. In addition to the documentation topic (SomePlugin), there's a separate development page.

• Doc page: Read all available info about the Plugin; download the attached distribution files.
• Dev page: Post feature requests, bug reports and general dev comments; topic title ends in Dev (SomePluginDev).
• User support: Post installation, how to use type questions (and answers, if you have them) in the TWiki:Support web.

• Method 1: Safely test on-the-fly by creating separate Production and Test branches in your live TWiki installation.
  • Duplicate the twiki/bin and twiki/lib directories for the Test version, and adjust the paths in the new lib/TWiki.cfg. The following directories are shared: twiki/data, twiki/templates and twiki/pub.
  • Test Plugins and other new features in the Test installation until you're satisfied.
    • If you modify topics using the new features, live users will likely see unfamiliar new META tags showing up on their pages - to avoid this, create and edit test-only topics to try out new features.
  • Copy the modified files to the Production installation. You can update a TWiki installation live and users won't even notice.

• Method 2: List the Plugin being tested in the DISABLEDPLUGINS variable in TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the Sandbox web and do the testing there.

Checking that Plugins are Working on a Live Server

A Note on Plugin Performance

Managing Plugins

Setting Preferences

• All Plugin modules present in the lib/TWiki/Plugins directory are activated automatically unless disabled by the DISABLEDPLUGINS Preferences variable in TWikiPreferences. You can optionally list the installed Plugins in the INSTALLEDPLUGINS Preferences variable. This is useful to define the sequence of Plugin execution, or to specify other webs than the TWiki web for the Plugin topics. Settings in TWikiPreferences are:
  • Set INSTALLEDPLUGINS = DefaultPlugin, ...
  • Set DISABLEDPLUGINS = EmptyPlugin, ...

Plugin-specific settings are done in individual Plugin topics. Two settings are standard for each Plugin:

• • Set SHORTDESCRIPTION = Blah blah woof woof.

• The settings can be retrieved as Preferences variables like %<pluginname>_<var>%, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.

• The %ACTIVATEDPLUGINS% variable lists activated Plugins by name. (This variable is displayed in TWikiPreferences for debugging use.)
• The %PLUGINDESCRIPTIONS% variable displays a bullet list with a one-line description of each active Plugins. This variable is based on the %<plugin>_SHORTDESCRIPTION% Preferences variables of individual topics and is shown in TextFormattingRules.

DEMO: Automatically List Active Plugins Using Variables

Using %PLUGINDESCRIPTIONS%:
You can use any of these active TWiki Plugins:

• For best performance, enable only the functions you really need. NOTE: outsidePREHandler and insidePREHandler are particularly expensive.

Most Plugins use either the commonTagsHandler or startRenderingHandler for rendering tasks:

• commonTagsHandler: Use it to expand %XYZPLUGIN% and %XYZPLUGIN{...}% variables
• startRenderingHandler: Use it for your own rendering rules or to overload TWiki's internal rendering like [[links]]

• Delay the Plugin initialization to the actual function which is handling the tag. This way all the expensive initialization is done only when needed.
• For example, use an eval block like:
  

• You could return errors as strings to show what happened

• • You can also use the %PLUGINVERSION{}% variable to query the Plugin API version or the version of installed Plugins.

The DefaultPlugin Alternative

• DefaultPlugin can handle some outdated TWiki variables, found, for example, in sites recently updated from an old version. Settings are in DefaultPlugin? topic. You can also add your own simple custom processing rules here, though in all but very simple cases, writing a new Plugin is preferable.

1. Customize your Plugin topic.
   • In case you plan to publish your Plugin at TWiki.org, use Interwiki names for author names, like TWiki:Main/TWikiGuest.
2. Save your topic, for use in packaging and publishing your Plugin.

1. Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them ALL:

• • paste in the topic text from Creating Plugin Documentation and save

1. Put the Plugin into the CVS repository, see TWiki:Plugins/ReadmeFirst (optional)

Recommended Storage of Plugin Data

Where to store Plugin Internal Data

• The Plugin's attachment directory is pubdir/Installweb/FooBarPlugin
  • Installweb refers to the name of the web where the Plugin is installed
• The Plugin's attachment URL is %PUBURL%/Installweb/FooBarPlugin
• The filename should start with an underscore, followed by an identifier, e.g. _any_name.ext
  • The leading underscore avoids a nameclash with files attached to the Plugin topic
  • Use only alphanumeric characters, underscores and periods to avoid platform dependency issues and URL issues
  • Do not use subdirectories (rename and delete would fail)
• Use Plugin API functions documented in TWikiFuncModule? to ensure portability:
  • Use getPubDir() to get the attachment root directory
  • Use getUrlHost() and getPubUrlPath() to build the URL in case you create content for the browser
  • Use $installWeb to get the name of the web where the Plugin is installed
  • Create the web directory and topic attachment directory if needed
• Hint: Package the Plugin at least with one file attachment. This ensures that the attachment directory already exists

Where to Store Data for Topics using the Plugin

In case the Plugin generates data which is specific to a topic, store it in the topic's attachment directory.

• The topic's attachment directory is pubdir/Webname/TopicName
• The topic's attachment URL is %PUBURL%/Webname/TopicName
• The filename should start with an underscore, followed by the Plugin name, an underscore and an identifier, e.g. _FooBarPlugin_any_name.ext
  • The leading underscore avoids a nameclash with files attached to the same topic
  • Use only alphanumeric characters, underscores and periods to avoid platform dependency issues and URL issues
  • Do not use subdirectories (rename and delete would fail)
• Use Plugin API functions documented in TWikiFuncModule? to ensure portability:
  • Use getPubDir() to get the attachment root directory
  • Use getUrlHost() and getPubUrlPath() to build the URL in case you create content for the browser

# Create web directory "pub/$web" if needed my $dir = TWiki::Func::getPubDir() . "/$web"; unless( -e "$dir" ) { umask( 002 ); mkdir( $dir, 0775 ); } # Create topic directory "pub/$web/$topic" if needed $dir .= "/$topic"; unless( -e "$dir" ) { umask( 002 ); mkdir( $dir, 0775 ); } return "$dir/_FooBarPlugin_$name"; }