PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

---

Parent package: Foswiki::Plugins
Child packages:

More ...Less ...

internal package Foswiki::Plugins::SetFormValuesPlugin

Foswiki plugins 'listen' to events happening in the core by registering an interest in those events. They do this by declaring 'plugin handlers'. These are simply functions with a particular name that, if they exist in your plugin, will be called by the core.

This is an empty Foswiki plugin. It is a fully defined plugin, but is disabled by default in a Foswiki installation. Use it as a template for your own plugins.

To interact with Foswiki use ONLY the official APIs documented in DevelopingPlugins. Do not reference any packages, functions or variables elsewhere in Foswiki, as these are subject to change without prior warning, and your plugin may suddenly stop working.

Error messages can be output using the Foswiki::Func writeWarning and writeDebug functions. These logs can be found in the Foswiki/working/logs directory. You can also print STDERR; the output will appear in the webserver error log. The {WarningsAreErrors} configure setting makes Foswiki less tolerant of errors, and it is recommended to set it during development. It can be set using configure, in the 'Miscellaneous' section. Most handlers can also throw exceptions (e.g. Foswiki::OopsException)

For increased performance, all handler functions except initPlugin are commented out below. To enable a handler remove the leading # from each line of the function. For efficiency and clarity, you should only uncomment handlers you actually use.

NOTE: When developing a plugin it is important to remember that Foswiki is tolerant of plugins that do not compile. In this case, the failure will be silent but the plugin will not be available. See InstalledPlugins for error messages.

NOTE: Foswiki:Development.StepByStepRenderingOrder helps you decide which rendering handler to use. When writing handlers, keep in mind that these may be invoked on included topics. For example, if a plugin generates links to the current topic, these need to be generated before the afterCommonTagsHandler is run. After that point in the rendering loop we have lost the information that the text had been included from another topic.

NOTE: Not all handlers (and not all parameters passed to handlers) are available with all versions of Foswiki. Where a handler has been added the POD comment will indicate this with a "Since" line e.g. Since: Foswiki::Plugins::VERSION 1.1

Deprecated handlers are still available, and can continue to be used to maintain compatibility with earlier releases, but will be removed at some point in the future. If you do implement deprecated handlers, then you can do no harm by simply keeping them in your code, but you are recommended to implement the alternative as soon as possible.

See http://foswiki.org/Download/ReleaseDates for a breakdown of release versions.

initPlugin($topic, $web, $user) → $boolean

• $topic - the name of the topic in the current CGI query
• $web - the name of the web in the current CGI query
• $user - the login name of the user
• $installWeb - the name of the web the plugin topic is in (usually the same as $Foswiki::cfg{SystemWebName})

REQUIRED

Called to initialise the plugin. If everything is OK, should return a non-zero value. On non-fatal failure, should write a message using Foswiki::Func::writeWarning and return 0. In this case %FAILEDPLUGINS% will indicate which plugins failed.

In the case of a catastrophic failure that will prevent the whole installation from working safely, this handler may use 'die', which will be trapped and reported in the browser.

Note: Please align macro names with the Plugin name, e.g. if your Plugin is called FooBarPlugin, name macros FOOBAR and/or FOOBARSOMETHING. This avoids namespace issues.

beforeSaveHandler($text, $topic, $web, $meta )

• $text - text with embedded meta-data tags
• $topic - the name of the topic in the current CGI query
• $web - the name of the web in the current CGI query
• $meta - the metadata of the topic being saved, represented by a Foswiki::Meta object.

This handler is called each time a topic is saved.

NOTE: meta-data is embedded in $text (using %META: tags). If you modify the $meta object, then it will override any changes to the meta-data embedded in the text. Modify either the META in the text or the $meta object, never both. You are recommended to modify the $meta object rather than the text, as this approach is proof against changes in the embedded text format.

Since: Foswiki::Plugins::VERSION = 2.0