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::DebugLogPlugin

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

For increased performance, all handlers except initPlugin are disabled below. To enable a handler remove the leading DISABLE_ from the function name. For efficiency and clarity, you should comment out or delete the whole of handlers you don't use before you release your plugin.

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#FAILEDPLUGINS for error messages.

NOTE: Defining deprecated handlers will cause the handlers to be listed in %SYSTEMWEBWEB%.InstalledPlugins#FAILEDPLUGINS. See InstalledPlugins#Handlig_deprecated_functions for information on regarding deprecated handlers that are defined for compatibility with older Foswiki versions.

NOTE: 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, as at that point in the rendering loop we have lost the information that we the text had been included from another topic.

initPlugin($topic, $web, $user, $installWeb) → $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 is installed in

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

Plugin	Errors
SpreadSheetPlugin	none
SlideShowPlugin	none
AutoViewTemplatePlugin	none
CommentPlugin	none
CompareRevisionsAddonPlugin	none
ConfigurePlugin	none
DebugLogPlugin	none
EditRowPlugin	none
HistoryPlugin	none
HomePagePlugin	none
InterwikiPlugin	none
JQueryPlugin	none
MailerContribPlugin	none
NatEditPlugin	none
PreferencesPlugin	none
RenderListPlugin	none
SmiliesPlugin	none
SubscribePlugin	none
TablePlugin	none
TinyMCEPlugin	none
TwistyPlugin	none
UpdatesPlugin	none
WysiwygPlugin	none

Handler	Plugins
afterCommonTagsHandler	TablePlugin
afterEditHandler	WysiwygPlugin
beforeCommonTagsHandler	PreferencesPlugin WysiwygPlugin
beforeEditHandler	NatEditPlugin TinyMCEPlugin WysiwygPlugin
beforeMergeHandler	WysiwygPlugin
beforeSaveHandler	WysiwygPlugin
commonTagsHandler	SpreadSheetPlugin SlideShowPlugin CompareRevisionsAddonPlugin EditRowPlugin
finishPlugin	JQueryPlugin UpdatesPlugin
initPlugin	SpreadSheetPlugin SlideShowPlugin AutoViewTemplatePlugin CommentPlugin CompareRevisionsAddonPlugin ConfigurePlugin DebugLogPlugin EditRowPlugin HistoryPlugin HomePagePlugin InterwikiPlugin JQueryPlugin MailerContribPlugin NatEditPlugin PreferencesPlugin RenderListPlugin SmiliesPlugin SubscribePlugin TablePlugin TinyMCEPlugin TwistyPlugin UpdatesPlugin WysiwygPlugin
initializeUserHandler	HomePagePlugin
lateInitPlugin	JQueryPlugin
modifyHeaderHandler	WysiwygPlugin
mergeHandler	DebugLogPlugin
postRenderingHandler	EditRowPlugin PreferencesPlugin WysiwygPlugin
preRenderingHandler	InterwikiPlugin RenderListPlugin SmiliesPlugin TablePlugin

23 plugins

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.

You may also call Foswiki::Func::registerTagHandler here to register a function to handle variables that have standard Foswiki syntax - for example, =%MYTAG{"my param" myarg="My Arg"}%. You can also override internal Foswiki variable handling functions this way, though this practice is unsupported and highly dangerous!

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

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 = 1.1

restExample($session) → $text

This is an example of a sub to be called by the rest script. The parameter is:

• $session - The Foswiki object associated to this session.

Additional parameters can be recovered via de query object in the $session.

For more information, check Foswiki:System.Scripts#rest

Since: Foswiki::Plugins::VERSION 1.1