| |
TWiki Plugins |
| | In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, listed in the lib/TWiki/Plugins/EmptyPlugin.pm module. |
|
<
< |
- For best performance, enable only the functions you really need. NOTE:
outsidePREHandler and insidePREHandler are particularly expensive.
|
| |
- All but the initPlugin are disabled. To enable a call back, remove
DISABLE_ from the function name.
|
|
>
> |
- For best performance, enable only the functions you really need. NOTE:
outsidePREHandler and insidePREHandler are particularly expensive.
|
| | Plugin Version Detection |
| | Creating the Perl Module |
|
<
< | 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. 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();
|
| |
Writing the Documentation Topic
The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as FileAttachments for downloading. (The doc topic is also included in the distribution package.) To create a documentation topic: |
|
<
< |
- Copy the Plugin topic template from EmptyPlugin. To copy the text, go to the page and:
- click Edit
- select all in the Edit box & copy
|
>
> |
- Copy the Plugin topic template from TWiki.org. To copy the text, go to TWiki:Plugins/PluginPackage and:
- enter the Plugin name in the "How to Create a Plugin" section
- click Create
- select all in the Edit box & copy
|
| | |
|
<
< |
-
- paste & save as a text file or new topic on your site
- Customize the template for your Plugin; you'll probably want to post a working version on your local TWiki site.
- Save your topic as a text file, for use in packaging and publishing your Plugin.
|
>
> |
-
- go back to your site to the TWiki web
- In the GoBox enter your Plugin name, for example
MyFirstPlugin, press enter and create the new topic
- paste & save new Plugin topic on your site
- 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.
- Save your topic, for use in packaging and publishing your Plugin.
|
| |
OUTLINE: Doc Topic Contents
|
|
<
< | Check EmptyPlugin on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered: |
>
> | 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.>" |
|
<
< | MyFirstPlugin Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>" |
>
> | 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!>" |
| | |
|
<
< |
- Plugins Preferences <If user settings are needed, explain... Entering valuse works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
- Set <EXAMPLE = value added>
|
>
> | Plugin Global Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>" |
| | |
|
<
< | How-to Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>" |
>
> |
- 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>
|
| | |
|
<
< | Test Example: <Include an example of the Plugin in action: if it works, the installation was a success!>" |
>
> | 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.>"
|
| |
- 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
|
|
<
< | -- PeterThoeny - 14 Sep 2001
|
>
> | -- PeterThoeny - 29 Jan 2003
|
| | -- MikeMannix? - 03 Dec 2001 |
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.