Difference: TWikiPlugins (13 vs. 14)

Revision 1415 Sep 2001 - MikeMannix

Line: 1 to 1
 

TWiki Plugins

Changed:
<
<
Plugin use and development; about the Plugin API.
>
>
Plug-in enhanced feature add-ons, with a Plugin API for developers
 

Overview

Changed:
<
<
You can add Plugins to greatly extend TWiki's functionality, without alering the program core. With a plug-in approach, you can:
>
>
You can add Plugins to extend TWiki's functionality, without altering the core program code. With a plug-in approach, you can:
 
  • add virtually unlimited features while keeping the main TWiki code compact and efficient;
  • heavily customize an installation and still do clean updates to new versions of TWiki;
Line: 23 to 23
 
  • EmptyPlugin is a fully functional module, minus active code; it does nothing and serves as a template for new Plugin development.
Changed:
<
<
  • InterwikiPlugin is preinstalled but can be disabled or removed. Use it for quick linking to to remote sites: TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can add your own shortcuts and URLs to the existing directory of Wiki-related and other probably useful sites.
>
>
  • InterwikiPlugin is preinstalled but can be disabled or removed. Use it for quick linking to to remote sites: TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can add your own shortcuts and URLs to the existing directory of Wiki-related and other probably useful sites.
 

Installing Plugins

Line: 37 to 37
  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.
Changed:
<
<
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.
>
>
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.
Changed:
<
<
  • Dev page: Post feature requests, bug reports and general dev comments; topic title ends in Dev (SomePluginDev).
>
>
  • 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.

On-Site Pretesting

Line: 47 to 47
 To test new Plugins on your installation before making them public, you may want to use one of these two approaches:

  • Method 1: Create Production and a Test installation of TWiki.
Changed:
<
<
    • Duplicate the twiki/bin and twiki/lib directories for the Test version, adjusting the paths in the new lib/TWiki.cfg, the twiki/data; the twiki/templates and twiki/pub directories are shared.
>
>
    • Duplicate the twiki/bin and twiki/lib directories for the Test version, adjusting the paths in the new lib/TWiki.cfg, the twiki/data; the twiki/templates and twiki/pub directories are shared.
 
    • Test Plugins and other new features in the Test installation until you're satisfied.
    • Copy the modified files to the Production installation. You can update a live TWiki installation and users won't even notice.
Changed:
<
<
  • Method 2: List the Plugin under Test in the DISABLEDPLUGINS variable in TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the Test web and do the testing there.
>
>
  • Method 2: List the Plugin under Test in the DISABLEDPLUGINS variable in TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the Test web and do the testing there.
 

Managing Plugins

Line: 61 to 61
  Installed Plugins can be toggled on or off, site-wide or by web, through TWikiPreferences and individual WebPreferences:
Changed:
<
<
  • 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, ...
>
>
  • 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, ...
 
Changed:
<
<
Plugin execution order in TWiki is determined by searching Plugin topics in a specific sequence: First, full web.topicname name, if specified in INSTALLEDPLUGINS; next, the TWiki web is searched; and finally, the current web.
>
>
Plugin execution order in TWiki is determined by searching Plugin topics in a specific sequence: First, full web.topicname name, if specified in INSTALLEDPLUGINS; next, the TWiki web is searched; and finally, the current web.
  Plugin-specific settings are done in individual Plugin topics. Two settings are standard for each Plugin:
  1. One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
Changed:
<
<
    • Set SHORTDESCRIPTION = Blah blah woof woof.
  1. Debug Plugin, output can be seen in data/debug.txt. Set to 0=off or 1=on:
    • Set DEBUG = 0
  • The settings can be retrieved as Preferences variables like %<pluginname>_<var>%, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.
>
>
    • Set SHORTDESCRIPTION = Blah blah woof woof.
  1. Debug Plugin, output can be seen in data/debug.txt. Set to 0=off or 1=on:
    • Set DEBUG = 0
  • The settings can be retrieved as Preferences variables like %<pluginname>_<var>%, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.
 

Listing Active Plugins

Plugin status variables let you list all active Plugins wherever needed. There are two list formats:

Changed:
<
<
  • 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.
>
>
  • 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: Active Plugin Variables
Changed:
<
<
%ACTIVATEDPLUGINS%
>
>
%ACTIVATEDPLUGINS%
 On this TWiki site, the active Plugins are: SpreadSheetPlugin, AlbumOfSnapsPlugin, ApprovalPlugin, AttachmentListPlugin, CaptchaPlugin, CommentPlugin, CounterPlugin, EditTablePlugin, EmptyPlugin, ImageGalleryPlugin, ImagePlugin, InterwikiPlugin, NewsPlugin, PreferencesPlugin, RenderListPlugin, SendEmailPlugin, SlideShowPlugin, SmiliesPlugin, TablePlugin, TagMePlugin, TinyMCEPlugin, TopicTranslationsPlugin, TwistyPlugin, WysiwygPlugin.
Changed:
<
<
%PLUGINDESCRIPTIONS%
>
>
%PLUGINDESCRIPTIONS%
 You can use any of these active TWiki Plugins:
  • SpreadSheetPlugin (any TWiki, $Rev: 17387 (11 Aug 2008) $): Add spreadsheet calculation like "$SUM( $ABOVE() )" to TWiki tables and other topic text
  • AlbumOfSnapsPlugin (Dakar, $Rev: 10613 (12 Dec 2008) $):
  • ApprovalPlugin (1.0, $Rev: 3923 (2009-05-16) $): Defines a set of states for one more or topics, with each state requiring approval by one or more users.
  • AttachmentList: (disabled)
  • AttachmentListPlugin (1.2.6, $Rev: 17172 (28 Jul 2008) $): Displays a formattable list of topic attachments, anywhere in a topic.
  • BatchUploadPlugin: (disabled)
  • CaptchaPlugin (Dakar, 1.5-pre4): To prevent automated bots from spamming
  • CommentPlugin (03 Aug 2008, $Rev: 17302 (11 Aug 2008) $): Allows users to quickly post comments to a page without an edit/preview/save cycle
  • CounterPlugin (Dakar, $Rev: 14404 (12 Dec 2008) $): This plugin maintains the Visitor Count for the site.
  • EditTablePlugin (4.8.4, $Rev: 17302 (11 Aug 2008) $): Edit TWiki tables using edit fields, date pickers and drop down boxes
  • EmptyPlugin (TWiki-4.2, $Rev: 15942 (11 Aug 2008) $): Empty Plugin used as a template for new Plugins
  • ImageGalleryPlugin (3.72, $Rev: 17034 (16 Jul 2008) $): Displays image gallery with auto-generated thumbnails from attachments
  • ImagePlugin (2010-08-01, $Rev: 19301 (2010-08-01) $): Control the display and alignment of images using an easy syntax
  • InterwikiPlugin (03 Aug 2008, $Rev: 14913 (17 Sep 2007) $): Link ExternalSite:Page text to external sites based on aliases defined in a rules topic
  • MultiEditPlugin: (disabled)
  • NewsPlugin (Dakar, $Rev: 15565 (12 Dec 2008) $): %NEWS% generates a short headlines topic from a list of news
  • PreferencesPlugin (TWiki-4.2, $Rev: 15487 (11 Aug 2008) $): Allows editing of preferences using fields predefined in a form
  • RenderListPlugin (2.0, $Rev: 16235 (11 Aug 2008) $): Render bullet lists in a variety of formats
  • SendEmailPlugin (1.2.2, $Rev: 17666 (12 Dec 2008) $): Allows to send e-mail through an e-mail form
  • SlideShowPlugin (02 Aug 2008, $Rev: 17260 (11 Aug 2008) $): Create web based presentations based on topics with headings.
  • SmiliesPlugin (Dakar, $Rev: 16049 (11 Aug 2008) $): Render smilies as icons, like smile for  :-) or eek! for  :eek:
  • TablePlugin (1.034, $Rev: 17367 (11 Aug 2008) $): Control attributes of tables and sorting of table columns
  • TagMePlugin (TWiki 4, 1.046): Tag wiki content collectively to find content by keywords
  • TinyMCEPlugin (03 Aug 2008, $Rev: 17302 (11 Aug 2008) $): Integration of TinyMCE? with WysiwygPlugin
  • TopicTranslationsPlugin (Dakar, $Rev: 15568 (12 Dec 2008) $): Manages a topic's translations into several languages.
  • TwistyPlugin (1.4.10, $Rev: 15653 (19 Nov 2007) $): Twisty section JavaScript library to open/close content dynamically
  • WysiwygPlugin (03 Aug 2008, $Rev: 17359 (11 Aug 2008) $): Translator framework for Wysiwyg editors
Line: 98 to 98
 

Available Core Functions

Changed:
<
<
The lib/TWiki/Func.pm implements ALL official Plugin functions. Plugins should ONLY use functions published in this module.
>
>
The lib/TWiki/Func.pm implements ALL official Plugin functions. Plugins should ONLY use functions published in this module.
 
Changed:
<
<
DevALERT: If you use functions not in 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.
>
>
DevALERT: If you use functions not in 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.
 
Changed:
<
<
  • For best performance, enable only the functions you really need. NOTE: outsidePREHandler and insidePREHandler are particularly expensive.
>
>
  • For best performance, enable only the functions you really need. NOTE: outsidePREHandler and insidePREHandler are particularly expensive.
 

Predefined Hooks

Changed:
<
<
In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, listed in the lib/TWiki/Plugins/EmptyPlugin.pm module.
>
>
In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, listed in the lib/TWiki/Plugins/EmptyPlugin.pm module.
 
Changed:
<
<
  • All but the initPlugin are disabled. To enable a call back, remove DISABLE_ from the function name.
>
>
  • All but the initPlugin are disabled. To enable a call back, remove DISABLE_ from the function name.
 

Plugin Version Detection

Changed:
<
<
To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are provided for automatic compatibility checking.
>
>
To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are provided for automatic compatibility checking.
 
Changed:
<
<
  • All modules require a $VERSION='0.000' variable, beginning at 1.000.
>
>
  • All modules require a $VERSION='0.000' variable, beginning at 1.000.
 
Changed:
<
<
  • The initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
    • The Plugin initialization code does not register a Plugin that returns FALSE (or that has no initPlugin handler).
>
>
  • The initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
    • The Plugin initialization code does not register a Plugin that returns FALSE (or that has no initPlugin handler).
 
Changed:
<
<
  • $VERSION='1.000' is the current setting in TWiki::Plugins.pm and in the preinstalled system Plugins (DefaultPlugin? , EmptyPlugin, InterwikiPlugin).
>
>
  • $VERSION='1.000' is the current setting in TWiki::Plugins.pm and in the preinstalled system Plugins (DefaultPlugin? , EmptyPlugin, InterwikiPlugin).
 

Creating Plugins

Line: 134 to 134
  A basic TWiki Plugin consists of two elements:
Changed:
<
<
  • a Perl module, ex: MyFirstPlugin.pm
  • a documentation topic, ex: MyFirstPlugin.txt
>
>
  • a Perl module, ex: MyFirstPlugin.pm
  • a documentation topic, ex: MyFirstPlugin.txt
  The Perl module can be a block of code that connects 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.
Changed:
<
<
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.
>
>
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, you're ready to develop Plugins.

Creating the Perl Module

Changed:
<
<
Copy file lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. EmptyPlugin.pm contains no executable code, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.
>
>
Copy file lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. EmptyPlugin.pm contains no executable code, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.
 

Writing the Documentation Topic

Line: 180 to 180
 

Packaging for Distribution

Changed:
<
<
A minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).
>
>
A minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).
 
  1. Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them ALL:
Changed:
<
<
    • lib/TWiki/Plugins/MyFirstPlugin.pm
    • data/TWiki/MyFirstPlugin.txt
    • pub/TWiki/MyFirstPlugin/uparrow.gif [a required graphic]
  1. Create a zip archive with the Plugin name (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
>
>
    • lib/TWiki/Plugins/MyFirstPlugin.pm
    • data/TWiki/MyFirstPlugin.txt
    • pub/TWiki/MyFirstPlugin/uparrow.gif [a required graphic]
  1. Create a zip archive with the Plugin name (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
 

Publishing for Public Use

Changed:
<
<
You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web, where all Plugins submitted to TWiki.org are available for download and further development discussion. Publish your Plugin in three steps:
>
>
You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins. Publish your Plugin in three steps:
 
  1. Post the Plugin documentation topic in the TWiki:Plugins web:
Changed:
<
<
  1. Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip.
  2. Link from the doc page to a new, blank page named after the Plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
>
>
  1. Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip
  2. Link from the doc page to a new, blank page named after the Plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
  -- AndreaSterbini? - 29 May 2001
-- MikeMannix? - 01 Sep 2001
 
This site is powered by the TWiki collaboration platformCopyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiPlugins