%FAILEDPLUGINS%
variable can be used to debug failures. You may also want to check your webserver error log and the various TWiki log files.
ab
utility. Example on Unix:time wget -qO /dev/null /wiki501/bin/view.pl/TWiki/AbcPlugin
DISABLEDPLUGINS
to be a comma-separated list of names of plugins to disable. Define it in Main.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
{PluginsOrder}
in the plugins section of configure.
Set SHORTDESCRIPTION = Control attributes of tables and sorting of table columns
%<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.
%ACTIVATEDPLUGINS%
%PLUGINDESCRIPTIONS%
"$SUM( $ABOVE() )"
to TWiki tables or anywhere in topic text %FAILEDPLUGINS%
Plugin | Errors |
---|---|
SpreadSheetPlugin | none |
BackupRestorePlugin |
TWiki::Plugins::BackupRestorePlugin could not be loaded. Errors were: syntax error at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Func.pm line 2935, near "$type qw( ALLOW DENY )" Can't redeclare "my" in "my" at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Func.pm line 2937, near "" Can't redeclare "my" in "my" at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Func.pm line 2938, near "" Global symbol "$pref" requires explicit package name (did you forget to declare "my $pref"?) at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Func.pm line 2938. syntax error at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Func.pm line 2941, near "}" syntax error at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Func.pm line 2963, near "}" syntax error at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Func.pm line 2988, near "}" Can't use global @_ in "my" at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Func.pm line 3044, near "= @_" syntax error at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Func.pm line 3080, near "}" Compilation failed in require at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/BackupRestorePlugin.pm line 24. Compilation failed in require at (eval 27) line 1. BEGIN failed--compilation aborted at (eval 27) line 1. ---- |
CommentPlugin |
TWiki::Plugins::CommentPlugin could not be loaded. Errors were: Attempt to reload TWiki/Func.pm aborted. Compilation failed in require at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/CommentPlugin.pm line 27. Compilation failed in require at (eval 28) line 1. BEGIN failed--compilation aborted at (eval 28) line 1. ---- |
EditTablePlugin | none |
HeadlinesPlugin | none |
InterwikiPlugin |
TWiki::Plugins::InterwikiPlugin could not be loaded. Errors were: Attempt to reload TWiki/Func.pm aborted. Compilation failed in require at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/InterwikiPlugin.pm line 40. Compilation failed in require at (eval 35) line 1. BEGIN failed--compilation aborted at (eval 35) line 1. ---- |
JQueryPlugin | none |
PreferencesPlugin |
TWiki::Plugins::PreferencesPlugin could not be loaded. Errors were: Attempt to reload TWiki/Func.pm aborted. Compilation failed in require at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/PreferencesPlugin.pm line 28. Compilation failed in require at (eval 39) line 1. BEGIN failed--compilation aborted at (eval 39) line 1. ---- |
RenderListPlugin | none |
SlideShowPlugin | none |
SmiliesPlugin |
TWiki::Plugins::SmiliesPlugin could not be loaded. Errors were: Attempt to reload TWiki/Func.pm aborted. Compilation failed in require at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/SmiliesPlugin.pm line 27. BEGIN failed--compilation aborted at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/SmiliesPlugin.pm line 27. Compilation failed in require at (eval 46) line 1. BEGIN failed--compilation aborted at (eval 46) line 1. ---- |
TablePlugin |
TWiki::Plugins::TablePlugin could not be loaded. Errors were: Attempt to reload TWiki/Func.pm aborted. Compilation failed in require at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/TablePlugin.pm line 28. Compilation failed in require at (eval 47) line 1. BEGIN failed--compilation aborted at (eval 47) line 1. ---- |
TagMePlugin | none |
TinyMCEPlugin |
TWiki::Plugins::TinyMCEPlugin could not be loaded. Errors were: Attempt to reload TWiki/Func.pm aborted. Compilation failed in require at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/TinyMCEPlugin.pm line 29. BEGIN failed--compilation aborted at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/TinyMCEPlugin.pm line 29. Compilation failed in require at (eval 51) line 1. BEGIN failed--compilation aborted at (eval 51) line 1. ---- |
TwistyPlugin |
TWiki::Plugins::TwistyPlugin could not be loaded. Errors were: Attempt to reload TWiki/Func.pm aborted. Compilation failed in require at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/TwistyPlugin.pm line 32. BEGIN failed--compilation aborted at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/TwistyPlugin.pm line 32. Compilation failed in require at (eval 52) line 1. BEGIN failed--compilation aborted at (eval 52) line 1. ---- |
WysiwygPlugin |
TWiki::Plugins::WysiwygPlugin could not be loaded. Errors were: Attempt to reload TWiki/Func.pm aborted. Compilation failed in require at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/WysiwygPlugin.pm line 48. BEGIN failed--compilation aborted at /kunden/sevke.net/www/sevke.net/wiki501/lib/TWiki/Plugins/WysiwygPlugin.pm line 48. Compilation failed in require at (eval 53) line 1. BEGIN failed--compilation aborted at (eval 53) line 1. ---- |
Handler | Plugins |
---|---|
afterSaveHandler | TagMePlugin |
beforeCommonTagsHandler | EditTablePlugin |
commonTagsHandler | SpreadSheetPlugin EditTablePlugin HeadlinesPlugin JQueryPlugin SlideShowPlugin TagMePlugin |
initPlugin | SpreadSheetPlugin EditTablePlugin HeadlinesPlugin JQueryPlugin RenderListPlugin SlideShowPlugin TagMePlugin |
postRenderingHandler | EditTablePlugin |
startRenderingHandler | RenderListPlugin This handler is deprecated - please check for updated versions of the plugins that use it! |
lib/TWiki/Func.pm
) describes all the interfaces available to plugins. Plugins should only use the interfaces described in this module.
Func.pm
, you run the risk of creating security holes. Also, your plugin will likely break and require updating when you upgrade to a new version of TWiki.
lib/TWiki/Plugins/EmptyPlugin.pm
module.
DISABLE_
from the function name.
eval
block like this:eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
lib/TWiki/Plugins/BathPlugin/
.
$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.
$VERSION
variable. This should be an integer, or a subversion version id.
initPlugin
handler should check all dependencies and return 1 if the initialization is OK or 0 if something went wrong. initPlugin
handler).
$TWiki::Plugins::VERSION
in the TWiki::Plugins
module contains the TWiki plugin API version, currently 1.3. %PLUGINVERSION{}%
variable to query the plugin API version or the version of installed plugins.
%TWiki::cfg
hash than adding it as preferences in the plugin topic. configure
describes the steps
MyFirstPlugin.pm
MyFirstPlugin.txt
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, 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.
lib/TWiki/Plugins/EmptyPlugin.pm
to <name>Plugin.pm
. The EmptyPlugin.pm
module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.
If your plugin uses its own modules and objects, you must include the name of the plugin in the package name. For example, write Package MyFirstPlugin::Attrs;
instead of just Package Attrs;
. Then call it using:
use TWiki::Plugins::MyFirstPlugin::Attrs; $var = MyFirstPlugin::Attrs->new();
MyFirstPlugin
, press enter and create the new topic
OUTLINE: Doc Topic Contents
Check the plugins web on TWiki.org for the latest plugin doc topic template. Here's a quick overview of what's covered: Syntax Rules: <Describe any special text formatting that will be rendered.>" Example: <Include an example of the plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>" Plugin Settings: <Description and settings for custom plugin %VARIABLES%, and those required by TWiki.>"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.>"
- 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
, ex: MyFirstPlugin.pm
, and a documentation page with the same name(MyFirstPlugin.txt
).
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
[a required graphic]
MyFirstPlugin.zip
) and add the entire directory structure from Step 1. The archive should look like this: lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
MyFirstPlugin
MyFirstPlugin.zip
Dev
, ex: MyFirstPluginDev
. This is the discussion page for future development. (User support for plugins is handled in TWiki:Support.)
TWiki::Func::getWorkArea()
function, which gives you a persistent directory where you can store data files. By default they will not be web accessible. The directory is guaranteed to exist, and to be writable by the webserver user. For convenience, TWiki::Func::storeFile()
and TWiki::Func::readFile()
are provided to persistently store and retrieve simple data in this area.
TWiki::Func::saveAttachment()
function to store the data.
Recommendation for file name: _GaugePlugin_img123.gif
TWiki::Func::saveAttachment()
function to store the data.
Recommendation for file names in plugin attachment area: _Main_roundedge-ul.gif
configure
configure
rather than trying to use TWiki preferences variables. These extensions use Config.spec
files to publish their configuration requirements.
Config.spec
files are read during TWiki configuration. Once a Config.spec
has defined a configuration item, it is available for edit through the standard configure
interface. Config.spec
files are stored in the 'plugin directory' e.g. lib/TWiki/Plugins/BathPlugin/Config.spec
.
Config.spec
file Config.spec
file for an extension starts with the extension announcing what it is:
# ---+ BathPlugin # This plugin senses the level of water in your bath, and ensures the plug # is not removed while the water is still warm.This is followed by one or more configuration items. Each configuration item has a type, a description and a default. For example:
# **SELECT Plastic,Rubber,Metal** # Select the plug type $TWiki::cfg{BathPlugin}{PlugType} = 'Plastic'; # **NUMBER** # Enter the chain length in cm $TWiki::cfg{BathPlugin}{ChainLength} = 30; # **BOOLEAN EXPERT** # Set this option to 0 to disable the water temperature alarm $TWiki::cfg{BathPlugin}{TempSensorEnabled} = 1;The type (e.g.
**SELECT**
) tells configure
to how to prompt for the value. It also tells configure
how to do some basic checking on the value you actually enter. All the comments between the type and the configuration item are taken as part of the description. The configuration item itself defines the default value for the configuration item. The above spec defines the configuration items $TWiki::cfg{BathPlugin}{PlugType}
, $TWiki::cfg{BathPlugin}{ChainLength}
, and $TWiki::cfg{BathPlugin}{TempSensorEnabled}
for use in your plugin. For example,
if( $TWiki::cfg{BathPlugin}{TempSensorEnabled} && $curTemperature > 50 ) { die "The bathwater is too hot for comfort"; }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:
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 |
lib/TWiki.spec
for many more examples.
Config.spec
files for non-plugin extensions are stored under the Contrib
directory instead of the Plugins
directory.
Note that from TWiki 5.0 onwards, CGI scripts (in the TWiki bin
directory) provided by extensions must also have an entry in the Config.spec
file. This entry looks like this (example taken from PublishContrib)
# **PERL H** # Bin script registration - do not modify $TWiki::cfg{SwitchBoard}{publish} = [ "TWiki::Contrib::Publish", "publish", { publishing => 1 } ];
PERL
specifies a perl data structure, and H
a hidden setting (it won't appear in configure
). The first field of the data value specifies the class where the function that implements the script can be found. The second field specifies the name of the function, which must be the same as the name of the script. The third parameter is a hash of initial context settings for the script.
TWiki:TWiki/SpecifyingConfigurationItemsForExtensions has supplemental documentation on configure settings.
Dev
, such as MyFirstPluginDev
. The plugin development topic is a great resource to discuss feature enhancements and to get feedback from the TWiki community.
if( $TWiki::Plugins::VERSION >= 1.1 ) { @webs = TWiki::Func::getListOfWebs( 'user,public' ); } else { @webs = TWiki::Func::getPublicWebList( ); }
TWiki::Plugins
version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler
for compatibility with TWiki::Plugins
versions before 1.1, we would add this to the plugin:
package TWiki::Plugins::SinkPlugin; use vars qw( %TWikiCompatibility ); $TWikiCompatibility{endRenderingHandler} = 1.1;If the currently-running TWiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. TWiki with versions of
TWiki::Plugins
before 1.1 will still call the handler as required.
Related Topics: DeveloperDocumentationCategory, AdminDocumentationCategory, TWiki:TWiki.TWikiPluginsSupplement
-- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.AndreaSterbini, TWiki:Main.MikeMannix, TWiki:Main.CrawfordCurrie, TWiki:Main.ArthurClemens, TWiki:Main.WillNorris