Module name TWiki::Plugins PluginsDotPm Location TWIKIROOT/lib/TWiki/Plugins.pm Summary this is the plugin discoverer, loader and runner Primary Author AndreaSterbini CVS history CVS:lib/TWiki/Plugins.pm CVS alpha CVSget:lib/TWiki/Plugins.pm Contributing authors (see CVS History) Is Class NO First Release to be filled out

File Hierarchy   TWIKIROOT   lib   TWiki   Plugins.pm

Please see CodevDocumentationProject and CodevDocumentationProjectDev for comments on the format of these pages.

Purpose

To dicover, load, initialize and run all the plugins.

Used by

This module is primarily used to expose several hooks during several phases of the twiki execution.

Callback handlers with version

The column Version shows when the handler has been introduced.

Existing Plugin Hooks in latest Alpha

See PluginHandlersProposed for handlers that have been suggested but not implemented, and TWiki.InstalledPlugins for hooks and handlers active on TWikiDotOrg.

package TWiki::Plugins

This module defines the singleton object that handles Plugins loading, initialization and execution.

This class uses Chain of Responsibility (GOF) pattern to dispatch handler calls to registered plugins.

Note that as of version 1.026 of this module, TWiki internal methods are no longer available to plugins. Any calls to TWiki internal methods must be replaced by calls via the $SESSION object in this package, or via the Func package. For example, the call:

my $pref = TWiki::getPreferencesValue('URGH');

should be replaced with

my $pref = TWiki::Func::getPreferencesValue('URGH');

and the call

my $t = TWiki::writeWarning($message);

should be replaced with

my $pref = $TWiki::Plugins::SESSION->writeWarning($message);

Methods in other modules such as Store must be accessed through the relevant TWiki sub-object, for example

TWiki::Store::saveTopic(...)

should be replaced with

$TWiki::Plugins::SESSION->{store}->saveTopic(...)

Note that calling TWiki internal methods is very very bad practice, and should be avoided wherever practical.

The developers of TWiki reserve the right to change internal methods without warning, unless those methods are clearly marked as PUBLIC. PUBLIC methods are part of the core specification of a module and can be trusted.

PUBLIC constant $VERSION

This is the version number of the plugins package. Use it for checking if you have a recent enough version.

PUBLIC $SESSION

This is a reference to the TWiki session object. It can be used in plugins to get at the methods of the TWiki kernel.

You are highly recommended to only use the methods in the Func interface, unless you have no other choice, as kernel methods may change between TWiki releases.

ClassMethod new( $session )

Construct new singleton plugins collection object. The object is a container for a list of plugins and the handlers registered by the plugins. The plugins and the handlers are carefully ordered.

=begin twiki

ObjectMethod finish()

ObjectMethod load($allDisabled) -> $loginName

Find all active plugins, and invoke the early initialisation. Has to be done after prefs are read.

Returns the user returned by the last initializeUserHandler to be called.

If allDisabled is set, no plugin handlers will be called.

ObjectMethod settings()

Push plugin settings onto preference stack

ObjectMethod enable()

Initialisation that is done after the user is known.

ObjectMethod getPluginVersion() -> $number

Returns the $TWiki::Plugins::VERSION number if no parameter is specified, else returns the version number of a named Plugin. If the Plugin cannot be found or is not active, 0 is returned.

ObjectMethod addListener( $command, $handler )

• $command - name of the event
• $handler - the handler object.

Add a listener to the end of the list of registered listeners for this event. The listener must implement invoke($command,...), which will be triggered when the event is to be processed.

=begin twiki

ObjectMethod dispatch( $handlerName, ...)

ObjectMethod haveHandlerFor( $handlerName ) -> $boolean

• $handlerName - name of the handler e.g. preRenderingHandler

Contributors:
-- MartinCleaver - 23 Jun 2002
-- AndreaSterbini - 12 Sep 2003
-- PeterThoeny - 02 Feb 2004

Discussions

Has anyone noticed that a plugin does no know what version of a topic it is looking at? I'm going to add a $rev to the initPlugin in my test system, but even this is a continuation of a mess. To stop doing all this the hard way (I will need access to $meta, from 2-3 versions of a topic, and also know which i am displaying, and a few other things) I'd like to suggest that we begin looking at passing around a reference to a topic object. This TopicObject would contain references to all loaded information (as each version is loaded it is cached, and references to these cached bits are kept for the duration of the transaction (or more for mod_perl). Obviously there is a requested version/DateTime in this TopicObject, which would also allow us to display an object as it was back then, rather than INCLUDEing current topics when showing a previous version of a topic.

This work is being done for my workplaces iso9001 web, and will probably be extended to indlude the idea of documentation versions.

-- SvenDowideit - 16 Apr 2004

Somehow, I like the idea of the TopicObject

Anyway, if the plugin has access to the topic metadata, then is pretty easy to get the information.

-- RafaelAlvarez - 24 Aug 2004

I was thinking about the current mechanism to handle the plugins. Right now it first scans the plugins to register the handlers that the plugin can use, and then it calls only those plugins that has the hook defined.

If the idea in RefactorPluginApi of having a "Base Plugin" and make the other plugins to subclass it, then an improvement can be done: The base plugin could have an empty implementation of each handler, and for each hook call the handler in all the plugins. I have tested it, and the improve over calling an empty method over calling "defined &sub " is between 8% and 10% .

(more on that later)

-- RafaelAlvarez - 24 Aug 2004