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 GenPDFAddOnPlugin

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. You can also print STDERR; the output will appear in the webserver error log. 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.

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.