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

internal package Foswiki::Plugins::EmptyPlugin

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 ENVironment setting $ENV{FOSWIKI_ASSERTS} setting makes Foswiki less tolerant of errors, and it is recommended to set it during development. It can be set by editing bin/LocalLib.cfg, (If missing, see bin/LocalLib.cfg.txt) 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.

preload($class, $session)

This method is called as early as possible in the processing of a request; before initPlugin is called, before any preferences are loaded, before even the store is loaded, and before the user has been identified.

It is intended for use when there is sufficient information available from the request object and the environment to make a decision on something. For example, it could be used to check the source IP address of a request, and decide whether to service it or not.

preload can use the methods of Foswiki::Func to access the request, but must not access the store, or any user or preference information. Caveat emptor! You have been warned!

The best way to terminate the request from preload is to throw an exception. You can do this using a die, which will result in a text/plain response being sent to the client. More sophisticated implementations can use Foswiki::OopsException to craft a response.

Since: Foswiki 2.0

earlyInitPlugin()

This method is called after preload but before initPlugin. It is called after the Foswiki infrastructure has been set up. If it returns a non-null error string, the plugin will be disabled. You can also terminate the request from this method by throwing one of the exceptions handled by Foswiki::UI (for example, Foswiki::OopsException).

initializeUserHandler( $loginName, $url, $pathInfo )

• $loginName - login name recovered from $ENV{REMOTE_USER}
• $url - request url
• $path_info - path_info from the Foswiki::Request

Allows a plugin to set the username. Normally Foswiki gets the username from the login manager. This handler gives you a chance to override the login manager.

Return the login name.

This handler is called very early, immediately after earlyInitPlugin.

Since: Foswiki::Plugins::VERSION = '2.0'

finishPlugin()

Called when Foswiki is shutting down, this handler can be used by the plugin to release resources - for example, shut down open database connections, release allocated memory etc.

Note that it's important to break any cycles in memory allocated by plugins, or that memory will be lost when Foswiki is run in a persistent context e.g. mod_perl.

validateRegistrationHandler($data)

• $data - a hashref containing all the formfields POSTed to the registration script

Called when a new user registers with this Foswiki. The handler is called after the user data has been validated by the core, but before the user is created and before any validation mail is sent out. The handler will be called on all plugins that implement it.

Note that the handler may modify fields in the $data record, but must be aware that these fields have already been checked and validated before the handler is called, so modifying them is dangerous, and strictly at the plugin author's own risk.

If the handler needs to abort the registration for any reason it can do so by raising an exception ( e.g. using die )

Since: Foswiki::Plugins::VERSION = '2.0'

registrationHandler($web, $wikiName, $loginName, $data )

• $web - the name of the web in the current CGI query
• $wikiName - users wiki name
• $loginName - users login name
• $data - a hashref containing all the formfields POSTed to the registration script

Called when a new user registers with this Foswiki.

Note that the handler is not called when the user submits the registration form if {Register}{NeedVerification} is enabled. In this case it is called when the user submits the activation code. The handler is only called once, on the first plugin seen that implements it.

WARNING The handler is called after the user has been created, and is really designed for nothing more sophisticated than adding a cookie at registration time. For most purposes it is useless, and you really wanted to implement the validateRegistrationHandler instead.

Deprecated in: Foswiki::Plugins::VERSION 2.3

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.

NOTE: Read the developer supplement at Foswiki:Development.AddToZoneFromPluginHandlers if you are calling addToZone() from this handler

Since: $Foswiki::Plugins::VERSION 2.0

beforeCommonTagsHandler($text, $topic, $web, $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
• $meta - meta-data object for the topic MAY BE undef

This handler is called before Foswiki does any expansion of its own internal variables. It is designed for use by cache plugins. Note that when this handler is called, <verbatim> blocks are still present in the text.

NOTE: This handler is called once for each call to commonTagsHandler i.e. it may be called many times during the rendering of a topic.

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

NOTE: This handler is not separately called on included topics.

NOTE: Read the developer supplement at Foswiki:Development.AddToZoneFromPluginHandlers if you are calling addToZone() from this handler

afterCommonTagsHandler($text, $topic, $web, $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
• $meta - meta-data object for the topic MAY BE undef

This handler is called after Foswiki has completed expansion of %MACROS%. It is designed for use by cache plugins. Note that when this handler is called, <verbatim> blocks are present in the text.

NOTE: This handler is called once for each call to commonTagsHandler i.e. it may be called many times during the rendering of a topic.

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

NOTE: Read the developer supplement at Foswiki:Development.AddToZoneFromPluginHandlers if you are calling addToZone() from this handler

preRenderingHandler( $text, \%map )

• $text - text, with the head, verbatim and pre blocks replaced with placeholders
• \%removed - reference to a hash that maps the placeholders to the removed blocks.

Handler called immediately before Foswiki syntax structures (such as lists) are processed, but after all variables have been expanded. Use this handler to process special syntax only recognised by your plugin.

Placeholders are text strings constructed using the tag name and a sequence number e.g. 'pre1', "verbatim6", "head1" etc. Placeholders are inserted into the text inside <!--!marker!--> characters so the text will contain <!--!pre1!--> for placeholder pre1.

Each removed block is represented by the block text and the parameters passed to the tag (usually empty) e.g. for

<pre class='slobadob'>
XYZ
</pre>

the map will contain:

$removed->{'pre1'}{text}:   XYZ
$removed->{'pre1'}{params}: class="slobadob"

Iterating over blocks for a single tag is easy. For example, to prepend a line number to every line of every pre block you might use this code:

foreach my $placeholder ( keys %$map ) {
    if( $placeholder =~ m/^pre/i ) {
        my $n = 1;
        $map->{$placeholder}{text} =~ s/^/$n++/gem;
    }
}

NOTE: This handler is called once for each rendered block of text i.e. it may be called several times during the rendering of a topic.

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

NOTE: Read the developer supplement at Foswiki:Development.AddToZoneFromPluginHandlers if you are calling addToZone() from this handler

Since Foswiki::Plugins::VERSION = '2.0'

postRenderingHandler( $text )

• $text - the text that has just been rendered. May be modified in place.

NOTE: This handler is called once for each rendered block of text i.e. it may be called several times during the rendering of a topic.

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

NOTE: Read the developer supplement at Foswiki:Development.AddToZoneFromPluginHandlers if you are calling addToZone() from this handler

Since Foswiki::Plugins::VERSION = '2.0'

beforeEditHandler($text, $topic, $web )

• $text - text that will be edited
• $topic - the name of the topic in the current CGI query
• $web - the name of the web in the current CGI query

This handler is called by the edit script just before presenting the edit text in the edit box. It is called once when the edit script is run.

NOTE: meta-data may be embedded in the text passed to this handler (using %META: tags)

Since: Foswiki::Plugins::VERSION = '2.0'

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

• $text - text that is being previewed
• $topic - the name of the topic in the current CGI query
• $web - the name of the web in the current CGI query
• $meta - meta-data for the topic.

This handler is called by the preview script just before presenting the text. It is called once when the preview script is run.

NOTE: this handler is not called unless the text is previewed.

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

afterSaveHandler($text, $topic, $web, $error, $meta )

• $text - the text of the topic excluding meta-data tags (see beforeSaveHandler)
• $topic - the name of the topic in the current CGI query
• $web - the name of the web in the current CGI query
• $error - any error string returned by the save.
• $meta - the metadata of the saved topic, 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)

Since: Foswiki::Plugins::VERSION 2.0

afterRenameHandler( $oldWeb, $oldTopic, $oldAttachment, $newWeb, $newTopic, $newAttachment )

• $oldWeb - name of old web
• $oldTopic - name of old topic (empty string if web rename)
• $oldAttachment - name of old attachment (empty string if web or topic rename)
• $newWeb - name of new web
• $newTopic - name of new topic (empty string if web rename)
• $newAttachment - name of new attachment (empty string if web or topic rename)

This handler is called just after the rename/move/delete action of a web, topic or attachment.

Since: Foswiki::Plugins::VERSION = '2.0'

beforeUploadHandler(\%attrHash, $meta )

• \%attrHash - reference to hash of attachment attribute values
• $meta - the Foswiki::Meta object where the upload will happen

This handler is called once when an attachment is uploaded. When this handler is called, the attachment has not been recorded in the database.

The attributes hash will include at least the following attributes:

• attachment => the attachment name - must not be modified
• user - the user id - must not be modified
• comment - the comment - may be modified
• stream - an input stream that will deliver the data for the attachment. The stream can be assumed to be seekable, and the file pointer will be positioned at the start. It is not necessary to reset the file pointer to the start of the stream after you are done, nor is it necessary to close the stream.

The handler may wish to replace the original data served by the stream with new data. In this case, the handler can set the {stream} to a new stream.

For example:

sub beforeUploadHandler {
    my ( $attrs, $meta ) = @_;
    my $fh = $attrs->{stream};
    local $/;
    # read the whole stream
    my $text = <$fh>;
    # Modify the content
    $text =~ s/investment bank/den of thieves/gi;
    $fh = new File::Temp();
    print $fh $text;
    $attrs->{stream} = $fh;

}

Since: Foswiki::Plugins::VERSION = 2.1

afterUploadHandler(\%attrHash, $meta )

• \%attrHash - reference to hash of attachment attribute values
• $meta - a Foswiki::Meta object where the upload has happened

This handler is called just after the after the attachment meta-data in the topic has been saved. The attributes hash will include at least the following attributes, all of which are read-only:

• attachment => the attachment name
• comment - the comment
• user - the user id

Since: Foswiki::Plugins::VERSION = 2.1

mergeHandler( $diff, $old, $new, \%info ) → $text

Try to resolve a difference encountered during merge. The differences array is an array of hash references, where each hash contains the following fields:

• $diff => one of the characters '+', '-', 'c' or ' '.
  • '+' - new contains text inserted in the new version
  • '-' - old contains text deleted from the old version
  • 'c' - old contains text from the old version, and new text from the version being saved
  • ' ' - new contains text common to both versions, or the change only involved whitespace
• $old => text from version currently saved
• $new => text from version being saved
• \%info is a reference to the form field description { name, title, type, size, value, tooltip, attributes, referenced }. It must not be wrtten to. This parameter will be undef when merging the body text of the topic.

Plugins should try to resolve differences and return the merged text. For example, a radio button field where we have { diff=>'c', old=>'Leafy', new=>'Barky' } might be resolved as 'Treelike'. If the plugin cannot resolve a difference it should return undef.

The merge handler will be called several times during a save; once for each difference that needs resolution.

If any merges are left unresolved after all plugins have been given a chance to intercede, the following algorithm is used to decide how to merge the data:

1. new is taken for all radio, checkbox and select fields to resolve 'c' conflicts
2. '+' and '-' text is always included in the the body text and text fields
3. <del>conflict</del> <ins>markers</ins> are used to mark 'c' merges in text fields

The merge handler is called whenever a topic is saved, and a merge is required to resolve concurrent edits on a topic.

Since: Foswiki::Plugins::VERSION = 2.0

modifyHeaderHandler( \%headers, $query )

• \%headers - reference to a hash of existing header values
• $query - reference to CGI query object

Lets the plugin modify the HTTP headers that will be emitted when a page is written to the browser. \%headers= will contain the headers proposed by the core, plus any modifications made by other plugins that also implement this method that come earlier in the plugins list.

$headers->{expires} = '+1h';

Note that this is the HTTP header which is not the same as the HTML <HEAD> tag. The contents of the <HEAD> tag may be manipulated using the Foswiki::Func::addToHEAD method.

Since: Foswiki::Plugins::VERSION 2.0

renderFormFieldForEditHandler($name, $type, $size, $value, $attributes, $possibleValues) → $html

This handler is called before built-in types are considered. It generates the HTML text rendering this form field, or false, if the rendering should be done by the built-in type handlers.

• $name - name of form field
• $type - type of form field (checkbox, radio etc)
• $size - size of form field
• $value - value held in the form field
• $attributes - attributes of form field
• $possibleValues - the values defined as options for form field, if any. May be a scalar (one legal value) or a ref to an array (several legal values)

Return HTML text that renders this field. If false, form rendering continues by considering the built-in types.

Since: Foswiki::Plugins::VERSION 2.0

Note that you can also extend the range of available types by providing a subclass of Foswiki::Form::FieldDefinition to implement the new type (see Foswiki::Extensions.JSCalendarContrib and Foswiki::Extensions.RatingContrib for examples). This is the preferred way to extend the form field types.

renderWikiWordHandler($linkText, $hasExplicitLinkLabel, $web, $topic) → $linkText

• $linkText - the text for the link i.e. for [[Link][blah blah]] it's blah blah, for BlahBlah it's BlahBlah, and for Blah Blah it's Blah Blah.
• $hasExplicitLinkLabel - true if the link is of the form [[Link][blah blah]] (false if it's =[Blah]] or =BlahBlah)
• $web, $topic - specify the link being rendered

Called during rendering, this handler allows the plugin a chance to change the rendering of labels used for links.

Return the new link text.

NOTE: this handler is to allow a plugin to change the link text for a possible link - it may never be used. for example, Set ALLOWTOPICVIEW = is a possible ACRONYM link that will not be displayed unless the topic exists similarly, this handler is called before the Plurals code has a chance to remove the 's' from WikiWords

Since: Foswiki::Plugins::VERSION 2.0

completePageHandler($html, $httpHeaders)

This handler is called on the ingredients of every page that is output by the standard CGI scripts. It is designed primarily for use by cache and security plugins.

• $html - the body of the page (normally <html>..$lt;/html>)
• $httpHeaders - the HTTP headers. Note that the headers do not contain a Content-length. That will be computed and added immediately before the page is actually written. This is a string, which must end in \n\n.

Since: Foswiki::Plugins::VERSION 2.0

restExample($session, $subject, $verb, $response) → $text

• $session - The Foswiki object associated with this request.
• $subject - The invoked subject (may be ignored)
• $verb - The invoked verb (may be ignored)
• $response reference to the Foswiki::Response object that is used to compose a reply to the request

If the redirectto parameter is not present on the request, then the return value from the handler is used to determine the endpoint for the request. It can be:

• undef - causes the core to assume the handler handled the complete request i.e. the core will not generate any response to the request.
• text - any other non-undef value will be written out as the content of an HTTP 200 response. Only the standard headers in the response are written.

Additional parameters can be recovered via the query object in the $session, for example:

my $query = $session->{request}; my $web = $query->{param}->{web}[0];

If your rest handler adds or replaces equivalent functionality to a standard script provided with Foswiki, it should set the appropriate context in its switchboard entry. In addition to the obvous contexts: view, diff, etc. the static context is used to indicate that the resulting output will be read offline, such as in a PDF, and dynamic links (edit, sorting, etc) should not be rendered.

A comprehensive list of core context identifiers used by Foswiki is found in IfStatements#Context_identifiers. Please be careful not to overwrite any of these identifiers!

For more information, check CommandAndCGIScripts#rest

For information about handling error returns from REST handlers, see Foswiki:Support.Faq1

Since: Foswiki::Plugins::VERSION 2.0

Deprecated handlers

redirectCgiQueryHandler($query, $url )

• $query - the CGI query
• $url - the URL to redirect to

This handler can be used to replace Foswiki's internal redirect function.

If this handler is defined in more than one plugin, only the handler in the earliest plugin in the INSTALLEDPLUGINS list will be called. All the others will be ignored.

Deprecated in: Foswiki::Plugins::VERSION 2.1

This handler was deprecated because it cannot be guaranteed to work, and caused a significant impediment to code improvements in the core.

beforeAttachmentSaveHandler(\%attrHash, $topic, $web )

• \%attrHash - reference to hash of attachment attribute values
• $topic - the name of the topic in the current CGI query
• $web - the name of the web in the current CGI query

This handler is called once when an attachment is uploaded. When this handler is called, the attachment has not been recorded in the database.

The attributes hash will include at least the following attributes:

• attachment => the attachment name
• comment - the comment
• user - the user id
• tmpFilename - name of a temporary file containing the attachment data

Deprecated in: Foswiki::Plugins::VERSION 2.1

The efficiency of this handler (and therefore it's impact on performance) is very bad. Please use beforeUploadHandler() instead.

afterAttachmentSaveHandler(\%attrHash, $topic, $web )

• \%attrHash - reference to hash of attachment attribute values
• $topic - the name of the topic in the current CGI query
• $web - the name of the web in the current CGI query
• $error - any error string generated during the save process (always undef in 2.1)

This handler is called just after the save action. The attributes hash will include at least the following attributes:

• attachment => the attachment name
• comment - the comment
• user - the user id

Deprecated in: Foswiki::Plugins::VERSION 2.1

This handler has a number of problems including security and performance issues. Please use afterUploadHandler() instead.