Difference: TWikiPlugins (35 vs. 36)

Revision 362011-06-06 - TWikiContributor

Line: 1 to 1
 

TWiki Plugins

Line: 67 to 67
  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.
Added:
>
>
 

Plugin-Specific Settings

Changed:
<
<
Some plugins are configured with plugin preferences variables, newer plugins with configure variables.
>
>
Plugins can be configured with 1. preferences settings and/or 2. with configure settings. Older plugins use plugin preferences settings defined in the plugin topic, which is no longer recommended.
 
Changed:
<
<
Configure variables are accessible though the configure interface.
>
>
1. Use preferences settings:
 
Changed:
<
<
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:
>
>
Adinistrators can set plugin-specific settings in the local site preferences at Main.TWikiPreferences and users can overload them at the web level and page level. This approach is recommended if users should be able to overload settings. For security this is not recommended for system settings, such as a path to an executable. By convention, preferences setting names start with the plugin name in all caps, and an underscore. For example, to set the cache refresh period of the TWiki:Plugins.VarCachePlugin, add this bullet in Main.TWikiPreferences
 
Changed:
<
<
  • Set SHORTDESCRIPTION = Control attributes of tables and sorting of table columns
>
>
  • Set VARCACHEPLUGIN_REFRESH = 24
 
Changed:
<
<
Preferences variables of active plugins can be retrieved anywhere in TWiki with %<pluginname>_<var>%, such as %TABLEPLUGIN_SHORTDESCRIPTION%. They can also be redefined with the %<pluginname>_<var>% setting at a lower level in the Main.TWikiPreferences or at the web level. For an easier upgrade it is recommended to customize plugin preferences variables in Main.TWikiPreferences only.
>
>
Preferences settings that have been defined in Main.TWikiPreferences can be retrieved anywhere in TWiki with %<pluginname>_<setting>%, such as %VARCACHEPLUGIN_REFRESH%.

To learn how this is done, use the TWiki:Plugins.VarCachePlugin documentation and Perl plugin code as a reference.

2. Use configure settings:

The administrator can set plugin settings in the configure interface. Recommended if only site administrators should be able to change settings. Chose this option to set sensitive or dangerous system settings, such as passwords or path to executables. To define plugin-specific configure settings,

  • Create a Config.spec file in lib/TWiki/Plugins/YourPlugin/ with variables, such as
    $TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} = 0;
  • In the plugin, use those those variables, such as
    $showIP = $TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} || 0;

To learn how this is done, use the TWiki:Plugins.RecentVisitorPlugin documentation and Perl plugin code as a reference.

In either case, define a SHORTDESCRIPTION setting in two places:

  • As a setting in the plugin documentation, which is needed for the extension reports on twiki.org. Example:
    • Set SHORTDESCRIPTION = Show recent visitors to a TWiki site
  • As a global Perl package variable in the plugin package, which is needed by TWiki to show info on installed plugins. Example:
    our $SHORTDESCRIPTION = 'Show recent visitors to a TWiki site';

For better performance, make sure you define this in the plugin package:
our $NO_PREFS_IN_TOPIC = 1;

 

Listing Active Plugins

Line: 112 to 136
  In addition to TWiki core functions, plugins can use predefined hooks, or callbacks, as described in the lib/TWiki/Plugins/EmptyPlugin.pm module.
Changed:
<
<
  • All but the initPlugin are disabled. To enable a callback, remove DISABLE_ from the function name.
>
>
  • All but the initPlugin are commented out. To enable a callback, remove the leading # from all lines of the callback.
 
Changed:
<
<
TWiki:Codev/StepByStepRenderingOrder helps you decide which rendering handler to use.
>
>
TWiki:Codev.StepByStepRenderingOrder helps you decide which rendering handler to use.
 

Hints on Writing Fast Plugins

Line: 124 to 148
  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/TWiki/Plugins/BathPlugin/.
Changed:
<
<
  • Avoid using preferences in the plugin topic; set $NO_PREFS_IN_TOPIC if you possibly can, as that will stop TWiki from reading the plugin topic for every page. Use Config.spec instead.
  • Use registered tag handlers
  • Measure the performance to see the difference
>
>
  • Avoid using preferences in the plugin topic; Define $NO_PREFS_IN_TOPIC in your plugin package as that will stop TWiki from reading the plugin topic for every page. Use Config.spec or preferences settings instead. (See details).
  • Use registered tag handlers.
  • Measure the performance to see the difference.
 

Version Detection

Line: 207 to 231
  Plugin Settings: <Description and settings for custom plugin %VARIABLES%, and those required by TWiki.>"
Deleted:
<
<
  • Plugins Preferences <If user settings are needed, explain... Entering values works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
    • Set <EXAMPLE = value added>
 Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>"

Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"

Line: 291 to 312
 

Structure of a Config.spec file

The Config.spec file for an extension starts with the extension announcing what it is:
Changed:
<
<
# ---+ BathPlugin
>
>
# ---+ 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.
Line: 316 to 338
 }
Changed:
<
<
The config.spec file is read by configure, which then writes LocalSite.cfg with the values chosen by the local site admin.
>
>
The Config.spec file is read by configure, which then writes LocalSite.cfg with the values chosen by the local site admin.
  A range of types are available for use in Config.spec files:
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding ZIVwiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiPlugins.