Difference: TWikiPluginsDotPm (1 vs. 4)

Revision 42010-05-29 - TWikiContributor

 

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.

ObjectMethod finish ()

Break circular references.

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.

Added:
>
>

ObjectMethod dispatch ($handlerName,...)

Dispatch the given handler, passing on ... in the parameter vector

 

ObjectMethod haveHandlerFor ($handlerName) -> $boolean

  • $handlerName - name of the handler e.g. preRenderingHandler
Return: true if at least one plugin has registered a handler of this type.
Deleted:
<
<

ObjectMethod *registrationHandler ()

Called by the register script

ObjectMethod *beforeCommonTagsHandler ()

Called at the beginning (for cache Plugins only)

ObjectMethod *commonTagsHandler ()

Called after %INCLUDE:"..."%

ObjectMethod *afterCommonTagsHandler ()

Called at the end (for cache Plugins only)

ObjectMethod *preRenderingHandler ($text,\%map)

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

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 \1 characters so the text will contain \1_pre1\1 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 a pre block you might use this code:

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

ObjectMethod *postRenderingHandler (\$text)

  • \$text - a reference to the HTML, with the head, verbatim and pre blocks replaced with placeholders

ObjectMethod *startRenderingHandler ()

Called just before the line loop

DEPRECATED Use preRenderingHandler instead. This handler correctly handles verbatim and other TWiki ML block types, and exposes them to the plugin.

ObjectMethod *outsidePREHandler ()

Called in line loop outside of <PRE> tag

DEPRECATED Use preRenderingHandler instead. This handler correctly handles pre and other TWiki ML block types, and is called only once instead of line-by-line.

ObjectMethod *insidePREHandler ()

Called in line loop inside of <PRE> tag

DEPRECATED Use preRenderingHandler instead. This handler correctly handles pre and other TWiki ML block types, and is called only once instead of line-by-line.

ObjectMethod *endRenderingHandler ()

Called just after the line loop

DEPRECATED Use postRenderingHandler instead.

ObjectMethod *beforeEditHandler ()

Called by edit

ObjectMethod *afterEditHandler ()

Called by edit

ObjectMethod *beforeSaveHandler ()

Called just before the save action

ObjectMethod *afterSaveHandler ()

Called just after the save action

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

Called just after the rename/move/delete action of a web, topic or attachment.

  • $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)

ObjectMethod mergeHandler ()

Called to handle text merge.

ObjectMethod *beforeAttachmentSaveHandler ($attrHashRef,$topic,$web)

This code provides Plugins with the opportunity to alter an uploaded attachment between the upload and save-to-store processes. It is invoked as per other Plugins.

  • $attrHashRef - Hash reference of attachment attributes (keys are indicated below)
  • $topic - Topic name
  • $web - Web name

Keys in $attrHashRef:

Key Value
attachment Name of the attachment
tmpFilename Name of the local file that stores the upload
comment Comment to be associated with the upload
user Login name of the person submitting the attachment, e.g. 'jsmith'

Note: All keys should be used read-only, except for comment which can be modified.

Example usage:

   my( $attrHashRef, $topic, $web ) = @_;
   $$attrHashRef{'comment'} .= " (NOTE: Extracted from blah.tar.gz)";

ObjectMethod *afterAttachmentSaveHandler ($attachmentAttrHash,$topic,$web,$error)

deal with an uploaded attachment between the upload and save-to-store processes. It is invoked as per other plugins.

  • $attrHashRef - Hash reference of attachment attributes (keys are indicated below)
  • $topic - Topic name
  • $web - Web name
  • $error - Error string of save action, empty if OK

Keys in $attrHashRef:

Key Value
attachment Name of the attachment
tmpFilename Name of the local file that stores the upload
comment Comment to be associated with the upload
user Login name of the person submitting the attachment, e.g. 'jsmith'

Note: The hash is read-only

ObjectMethod *writeHeaderHandler () -> $headers

DEPRECATED Use modifyHeaderHandler instead. it is a lot more flexible, and allows you to modify existing headers as well as add new ones. It also works correctly when multiple plugins want to modify headers.

ObjectMethod *modifyHeaderHandler (\@headers,$query)

ObjectMethod *completePageHandler ($text,$pageType,$contentType)

ObjectMethod *redirectCgiQueryHandler () -> $result

Called by TWiki::redirect

ObjectMethod *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
  • $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 an array (several legal values)
Return HTML text that renders this field. If false, form rendering continues by considering the built-in types.

Note that a common application would be to generate formatting of the field involving generation of javascript. Such usually also requires the insertion of some common javascript into the page header. Unfortunately, there is currently no mechanism to pass that script to where the header of the page is visible. Consequentially, the common javascript may have to be emitted as part of the field formatting and might be duplicated many times throughout the page.

ObjectMethod *renderWikiWordHandler () -> $result

Change how a WikiWord is rendered

Originated from the TWiki:Plugins.SpacedWikiWordPlugin hack

 

Revision 32008-01-22 - TWikiContributor

 

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.

Added:
>
>

ObjectMethod finish ()

Break circular references.

 

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)

Changed:
<
<
  • =$command* - name of the event
>
>
  • $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.

ObjectMethod haveHandlerFor ($handlerName) -> $boolean

  • $handlerName - name of the handler e.g. preRenderingHandler
Return: true if at least one plugin has registered a handler of this type.

ObjectMethod *registrationHandler ()

Called by the register script

ObjectMethod *beforeCommonTagsHandler ()

Called at the beginning (for cache Plugins only)

ObjectMethod *commonTagsHandler ()

Called after %INCLUDE:"..."%

ObjectMethod *afterCommonTagsHandler ()

Called at the end (for cache Plugins only)

ObjectMethod *preRenderingHandler ($text,\%map)

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

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 \1 characters so the text will contain \1_pre1\1 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>
Added:
>
>
 the map will contain:
Changed:
<
<

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

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

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

ObjectMethod *postRenderingHandler (\$text)

  • \$text - a reference to the HTML, with the head, verbatim and pre blocks replaced with placeholders

ObjectMethod *startRenderingHandler ()

Called just before the line loop

DEPRECATED Use preRenderingHandler instead. This handler correctly handles verbatim and other TWiki ML block types, and exposes them to the plugin.

ObjectMethod *outsidePREHandler ()

Called in line loop outside of <PRE> tag

DEPRECATED Use preRenderingHandler instead. This handler correctly handles pre and other TWiki ML block types, and is called only once instead of line-by-line.

ObjectMethod *insidePREHandler ()

Called in line loop inside of <PRE> tag

DEPRECATED Use preRenderingHandler instead. This handler correctly handles pre and other TWiki ML block types, and is called only once instead of line-by-line.

ObjectMethod *endRenderingHandler ()

Called just after the line loop

DEPRECATED Use postRenderingHandler instead.

ObjectMethod *beforeEditHandler ()

Called by edit

ObjectMethod *afterEditHandler ()

Called by edit

ObjectMethod *beforeSaveHandler ()

Called just before the save action

ObjectMethod *afterSaveHandler ()

Called just after the save action

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

Called just after the rename/move/delete action of a web, topic or attachment.

  • $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)

ObjectMethod mergeHandler ()

Called to handle text merge.

ObjectMethod *beforeAttachmentSaveHandler ($attrHashRef,$topic,$web)

This code provides Plugins with the opportunity to alter an uploaded attachment between the upload and save-to-store processes. It is invoked as per other Plugins.

  • $attrHashRef - Hash reference of attachment attributes (keys are indicated below)
Changed:
<
<
  • $topic - | Topic name
  • $web - | Web name
>
>
  • $topic - Topic name
  • $web - Web name
  Keys in $attrHashRef:
Key Value
attachment Name of the attachment
tmpFilename Name of the local file that stores the upload
comment Comment to be associated with the upload
user Login name of the person submitting the attachment, e.g. 'jsmith'

Note: All keys should be used read-only, except for comment which can be modified.

Example usage:

   my( $attrHashRef, $topic, $web ) = @_;
   $$attrHashRef{'comment'} .= " (NOTE: Extracted from blah.tar.gz)";

ObjectMethod *afterAttachmentSaveHandler ($attachmentAttrHash,$topic,$web,$error)

deal with an uploaded attachment between the upload and save-to-store processes. It is invoked as per other plugins.

  • $attrHashRef - Hash reference of attachment attributes (keys are indicated below)
Changed:
<
<
  • $topic - | Topic name
  • $web - | Web name
  • $error - | Error string of save action, empty if OK
>
>
  • $topic - Topic name
  • $web - Web name
  • $error - Error string of save action, empty if OK
  Keys in $attrHashRef:
Key Value
attachment Name of the attachment
tmpFilename Name of the local file that stores the upload
comment Comment to be associated with the upload
user Login name of the person submitting the attachment, e.g. 'jsmith'

Note: The hash is read-only

ObjectMethod *writeHeaderHandler () -> $headers

Deleted:
<
<
Called by TWiki::writePageHeader. DEPRECATED do not use!
 DEPRECATED Use modifyHeaderHandler instead. it is a lot more flexible, and allows you to modify existing headers as well as add new ones. It also works correctly when multiple plugins want to modify headers.

ObjectMethod *modifyHeaderHandler (\@headers,$query)

Added:
>
>

ObjectMethod *completePageHandler ($text,$pageType,$contentType)

 

ObjectMethod *redirectCgiQueryHandler () -> $result

Called by TWiki::redirect

ObjectMethod *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
  • $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 an array (several legal values)
Return HTML text that renders this field. If false, form rendering continues by considering the built-in types.

Note that a common application would be to generate formatting of the field involving generation of javascript. Such usually also requires the insertion of some common javascript into the page header. Unfortunately, there is currently no mechanism to pass that script to where the header of the page is visible. Consequentially, the common javascript may have to be emitted as part of the field formatting and might be duplicated many times throughout the page.

ObjectMethod *renderWikiWordHandler () -> $result

Change how a WikiWord is rendered

Originated from the TWiki:Plugins.SpacedWikiWordPlugin hack

Revision 22007-01-16 - TWikiContributor

 

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

Changed:
<
<
$SESSION object in this package, or via the Func package.
>
>
$SESSION object in this package, or via the Func package.
 For example, the call:
Changed:
<
<
my $pref = TWiki::getPreferencesValue('URGH');
>
>
my $pref = TWiki::getPreferencesValue('URGH');
  should be replaced with
Changed:
<
<
my $pref = TWiki::Func::getPreferencesValue('URGH');
>
>
my $pref = TWiki::Func::getPreferencesValue('URGH');
  and the call
Changed:
<
<
my $t = TWiki::writeWarning($message);
>
>
my $t = TWiki::writeWarning($message);
  should be replaced with
Changed:
<
<
my $pref = $TWiki::Plugins::SESSION->writeWarning($message);
>
>
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
Changed:
<
<
TWiki::Store::saveTopic(...)
>
>
TWiki::Store::saveTopic(...)
  should be replaced with
Changed:
<
<
$TWiki::Plugins::SESSION->{store}->saveTopic(...)
>
>
$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

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

PUBLIC $SESSION

Added:
>
>
 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.

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.

Added:
>
>

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)

Added:
>
>
 
  • =$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.

ObjectMethod haveHandlerFor ($handlerName) -> $boolean

Added:
>
>
 
  • $handlerName - name of the handler e.g. preRenderingHandler
Return: true if at least one plugin has registered a handler of this type.

ObjectMethod *registrationHandler ()

Called by the register script

ObjectMethod *beforeCommonTagsHandler ()

Called at the beginning (for cache Plugins only)

ObjectMethod *commonTagsHandler ()

Called after %INCLUDE:"..."%

ObjectMethod *afterCommonTagsHandler ()

Called at the end (for cache Plugins only)

Changed:
<
<

ObjectMethd preRenderingHandler( $text, \%map )

>
>

ObjectMethod *preRenderingHandler ($text,\%map)

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

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 \1 characters so the text will contain \1_pre1\1 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:
<pre>
$removed->{'pre1'}{text}:   XYZ
$removed->{'pre1'}{params}: class="slobadob"
</pre>
Added:
>
>
  Iterating over blocks for a single tag is easy. For example, to prepend a line number to every line of a pre block you might use this code:

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

Added:
>
>
 

ObjectMethod *postRenderingHandler (\$text)

  • \$text - a reference to the HTML, with the head, verbatim and pre blocks replaced with placeholders

ObjectMethod *startRenderingHandler ()

Called just before the line loop

DEPRECATED Use preRenderingHandler instead. This handler correctly handles verbatim and other TWiki ML block types, and exposes them to the plugin.

ObjectMethod *outsidePREHandler ()

Called in line loop outside of <PRE> tag

DEPRECATED Use preRenderingHandler instead. This handler correctly handles pre and other TWiki ML block types, and is called only once instead of line-by-line.

ObjectMethod *insidePREHandler ()

Called in line loop inside of <PRE> tag

DEPRECATED Use preRenderingHandler instead. This handler correctly handles pre and other TWiki ML block types, and is called only once instead of line-by-line.

ObjectMethod *endRenderingHandler ()

Called just after the line loop

DEPRECATED Use postRenderingHandler instead.

ObjectMethod *beforeEditHandler ()

Called by edit

ObjectMethod *afterEditHandler ()

Called by edit

ObjectMethod *beforeSaveHandler ()

Called just before the save action

ObjectMethod *afterSaveHandler ()

Called just after the save action

Added:
>
>

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

Called just after the rename/move/delete action of a web, topic or attachment.

  • $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)
 

ObjectMethod mergeHandler ()

Called to handle text merge.

ObjectMethod *beforeAttachmentSaveHandler ($attrHashRef,$topic,$web)

This code provides Plugins with the opportunity to alter an uploaded attachment between the upload and save-to-store processes. It is invoked as per other Plugins.

  • $attrHashRef - Hash reference of attachment attributes (keys are indicated below)
  • $topic - | Topic name
  • $web - | Web name

Keys in $attrHashRef:

Key Value
attachment Name of the attachment
tmpFilename Name of the local file that stores the upload
comment Comment to be associated with the upload
user Login name of the person submitting the attachment, e.g. 'jsmith'

Note: All keys should be used read-only, except for comment which can be modified.

Example usage:

   my( $attrHashRef, $topic, $web ) = @_;
   $$attrHashRef{'comment'} .= " (NOTE: Extracted from blah.tar.gz)";

ObjectMethod *afterAttachmentSaveHandler ($attachmentAttrHash,$topic,$web,$error)

deal with an uploaded attachment between the upload and save-to-store processes. It is invoked as per other plugins.

  • $attrHashRef - Hash reference of attachment attributes (keys are indicated below)
  • $topic - | Topic name
  • $web - | Web name
  • $error - | Error string of save action, empty if OK

Keys in $attrHashRef:

Key Value
attachment Name of the attachment
tmpFilename Name of the local file that stores the upload
comment Comment to be associated with the upload
user Login name of the person submitting the attachment, e.g. 'jsmith'

Note: The hash is read-only

ObjectMethod *writeHeaderHandler () -> $headers

Called by TWiki::writePageHeader. DEPRECATED do not use!

DEPRECATED Use modifyHeaderHandler instead. it is a lot more flexible, and allows you to modify existing headers as well as add new ones. It also works correctly when multiple plugins want to modify headers.

ObjectMethod *modifyHeaderHandler (\@headers,$query)

ObjectMethod *redirectCgiQueryHandler () -> $result

Called by TWiki::redirect

ObjectMethod *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
  • $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 an array (several legal values)
Return HTML text that renders this field. If false, form rendering continues by considering the built-in types.

Note that a common application would be to generate formatting of the field involving generation of javascript. Such usually also requires the insertion of some common javascript into the page header. Unfortunately, there is currently no mechanism to pass that script to where the header of the page is visible. Consequentially, the common javascript may have to be emitted as part of the field formatting and might be duplicated many times throughout the page.

ObjectMethod *renderWikiWordHandler () -> $result

Change how a WikiWord is rendered

Originated from the TWiki:Plugins.SpacedWikiWordPlugin hack

Revision 12006-02-01 - TWikiContributor

 

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.

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 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.

ObjectMethod haveHandlerFor ($handlerName) -> $boolean

  • $handlerName - name of the handler e.g. preRenderingHandler
Return: true if at least one plugin has registered a handler of this type.

ObjectMethod *registrationHandler ()

Called by the register script

ObjectMethod *beforeCommonTagsHandler ()

Called at the beginning (for cache Plugins only)

ObjectMethod *commonTagsHandler ()

Called after %INCLUDE:"..."%

ObjectMethod *afterCommonTagsHandler ()

Called at the end (for cache Plugins only)

ObjectMethd preRenderingHandler( $text, \%map )

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

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 \1 characters so the text will contain \1_pre1\1 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:
<pre>
$removed->{'pre1'}{text}:   XYZ
$removed->{'pre1'}{params}: class="slobadob"
</pre>

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

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


---++ ObjectMethod *postRenderingHandler* <tt>(\$text)</tt>

   * =\$text= - a reference to the HTML, with the head, verbatim and pre blocks replaced with placeholders



---++ ObjectMethod *startRenderingHandler* <tt>()</tt>

Called just before the line loop

*DEPRECATED* Use preRenderingHandler instead. This handler correctly 
handles verbatim and other TWiki ML block types, and exposes them to 
the plugin.



---++ ObjectMethod *outsidePREHandler* <tt>()</tt>

Called in line loop outside of &lt;PRE&gt; tag

*DEPRECATED* Use preRenderingHandler instead. 
This handler correctly handles pre and other 
TWiki ML block types, and is called only once 
instead of line-by-line.



---++ ObjectMethod *insidePREHandler* <tt>()</tt>

Called in line loop inside of &lt;PRE&gt; tag

*DEPRECATED* Use preRenderingHandler instead. 
This handler correctly handles pre and other 
TWiki ML block types, and is called only once 
instead of line-by-line.



---++ ObjectMethod *endRenderingHandler* <tt>()</tt>

Called just after the line loop

*DEPRECATED* Use postRenderingHandler instead.



---++ ObjectMethod *beforeEditHandler* <tt>()</tt>

Called by edit



---++ ObjectMethod *afterEditHandler* <tt>()</tt>

Called by edit



---++ ObjectMethod *beforeSaveHandler* <tt>()</tt>

Called just before the save action



---++ ObjectMethod *afterSaveHandler* <tt>()</tt>

Called just after the save action



---++ ObjectMethod *mergeHandler* <tt>()</tt>

Called to handle text merge.



---++ ObjectMethod *beforeAttachmentSaveHandler* <tt>($attrHashRef,$topic,$web)</tt>

This code provides Plugins with the opportunity to alter an uploaded attachment between the upload and save-to-store processes. It is invoked as per other Plugins.
   * =$attrHashRef= - Hash reference of attachment attributes (keys are indicated below)
   * =$topic= -     | Topic name
   * =$web= -       | Web name

Keys in $attrHashRef:
| *Key*       | *Value* |
| attachment  | Name of the attachment |
| tmpFilename | Name of the local file that stores the upload |
| comment     | Comment to be associated with the upload |
| user        | Login name of the person submitting the attachment, e.g. 'jsmith' |

Note: All keys should be used read-only, except for comment which can be modified.

Example usage:

<pre>
   my( $attrHashRef, $topic, $web ) = @_;
   $$attrHashRef{'comment'} .= " (NOTE: Extracted from blah.tar.gz)";
</pre>



---++ ObjectMethod *afterAttachmentSaveHandler* <tt>($attachmentAttrHash,$topic,$web,$error)</tt>

deal with an uploaded attachment between the upload and save-to-store processes. It is invoked as per other plugins.

   * =$attrHashRef= - Hash reference of attachment attributes (keys are indicated below)
   * =$topic= -     | Topic name
   * =$web= -       | Web name
   * =$error= -     | Error string of save action, empty if OK

Keys in $attrHashRef:
| *Key*       | *Value* |
| attachment  | Name of the attachment |
| tmpFilename | Name of the local file that stores the upload |
| comment     | Comment to be associated with the upload |
| user        | Login name of the person submitting the attachment, e.g. 'jsmith' |

Note: The hash is *read-only*



---++ ObjectMethod *writeHeaderHandler* <tt>() -> $headers</tt>

Called by TWiki::writePageHeader. *DEPRECATED* do not use!

*DEPRECATED* Use modifyHeaderHandler instead. it is a lot 
more flexible, and allows you to modify existing headers 
as well as add new ones. It also works correctly when 
multiple plugins want to modify headers.



---++ ObjectMethod *modifyHeaderHandler* <tt>(\@headers,$query)</tt>



---++ ObjectMethod *redirectCgiQueryHandler* <tt>() -> $result</tt>

Called by TWiki::redirect



---++ ObjectMethod *renderFormFieldForEditHandler* <tt>($name,$type,$size,$value,$attributes,$possibleValues) -> $html</tt>

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
   * =$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 an array (several legal values)
Return HTML text that renders this field. If false, form rendering continues by considering the built-in types.

Note that a common application would be to generate formatting of the
field involving generation of javascript. Such usually also requires
the insertion of some common javascript into the page header. Unfortunately,
there is currently no mechanism to pass that script to where the header of
the page is visible. Consequentially, the common javascript may have to
be emitted as part of the field formatting and might be duplicated many
times throughout the page.



---++ ObjectMethod *renderWikiWordHandler* <tt>() -> $result</tt>

Change how a WikiWord is rendered

Originated from the TWiki:Plugins.SpacedWikiWordPlugin hack


 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright &© 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiPluginsDotPm.