internal package Foswiki::Plugins::TopSecretPlugin

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:

Child packagesChild packages

internal package Foswiki::Plugins::TopSecretPlugin

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.

commonTagsHandler($text, $topic, $web, $included, $meta )

• $text - text to be processed
• $topic - the name of the topic in the current CGI query
• $web - the name of the web in the current CGI query
• $included - Boolean flag indicating whether the handler is invoked on an included topic
• $meta - meta-data object for the topic MAY BE undef

This handler is called by the code that expands %MACROS% syntax in the topic body and in form fields. It may be called many times while a topic is being rendered.

Only plugins that have to parse the entire topic content should implement this function. For expanding macros with trivial syntax it is far more efficient to use Foswiki::Func::registerTagHandler (see initPlugin).

Internal Foswiki macros, (and any macros declared using Foswiki::Func::registerTagHandler) are expanded before, and then again after, this function is called to ensure all %MACROS% are expanded.

NOTE: when this handler is called, <verbatim> blocks have been removed from the text (though all other blocks such as <pre> and <noautolink> are still present).

NOTE: meta-data is not embedded in the text passed to this handler. Use the $meta object.

Since: $Foswiki::Plugins::VERSION 2.0

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