internal package
Foswiki::Plugins::TopSecretPlugin
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