TWiki/TWikiPluginsDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Plugins="></a> Package =TWiki::Plugins
   2
   3 This module defines the singleton object that handles Plugins loading, initialization and execution.
   4
   5 This class uses Chain of Responsibility (GOF) pattern to dispatch handler calls to registered plugins.
   6
   7 <div>
   8   <ul>
   9     <li><a href="#Package =TWiki::Plugins="> Package TWiki::Plugins</a><ul>
  10         <li><a href="#PUBLIC constant $VERSION"> PUBLIC constant $VERSION</a></li>
  11         <li><a href="#PUBLIC $SESSION"> PUBLIC $SESSION</a></li>
  12         <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
  13         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
  14         <li><a href="#ObjectMethod <strong>load</strong> ($allDisable"> ObjectMethod load <tt>($allDisabled) -&gt; $loginName</tt></a></li>
  15         <li><a href="#ObjectMethod <strong>settings</strong> ()"> ObjectMethod settings <tt>()</tt></a></li>
  16         <li><a href="#ObjectMethod <strong>enable</strong> ()"> ObjectMethod enable <tt>()</tt></a></li>
  17         <li><a href="#ObjectMethod *get_PluginVersion*"> ObjectMethod getPluginVersion <tt>() -&gt; $number</tt></a></li>
  18         <li><a href="#ObjectMethod <strong>addListener</strong> ($com"> ObjectMethod addListener <tt>($command,$handler)</tt></a></li>
  19         <li><a href="#ObjectMethod <strong>have_HandlerFor</strong> ("> ObjectMethod haveHandlerFor <tt>($handlerName) -&gt; $boolean</tt></a></li>
  20         <li><a href="#ObjectMethod *registrationHandle"> ObjectMethod registrationHandler <tt>()</tt></a></li>
  21         <li><a href="#ObjectMethod *before_CommonTagsH"> ObjectMethod beforeCommonTagsHandler <tt>()</tt></a></li>
  22         <li><a href="#ObjectMethod *common_TagsHandler"> ObjectMethod commonTagsHandler <tt>()</tt></a></li>
  23         <li><a href="#ObjectMethod *after_CommonTagsHa"> ObjectMethod afterCommonTagsHandler <tt>()</tt></a></li>
  24         <li><a href="#ObjectMethod *pre_RenderingHandl"> ObjectMethod preRenderingHandler <tt>($text,\%map)</tt></a></li>
  25         <li><a href="#ObjectMethod *post_RenderingHand"> ObjectMethod postRenderingHandler <tt>(\$text)</tt></a></li>
  26         <li><a href="#ObjectMethod *start_RenderingHan"> ObjectMethod startRenderingHandler <tt>()</tt></a></li>
  27         <li><a href="#ObjectMethod *outsidePREHandler*"> ObjectMethod outsidePREHandler <tt>()</tt></a></li>
  28         <li><a href="#ObjectMethod *insidePREHandler*"> ObjectMethod insidePREHandler <tt>()</tt></a></li>
  29         <li><a href="#ObjectMethod *end_RenderingHandl"> ObjectMethod endRenderingHandler <tt>()</tt></a></li>
  30         <li><a href="#ObjectMethod *before_EditHandler"> ObjectMethod beforeEditHandler <tt>()</tt></a></li>
  31         <li><a href="#ObjectMethod *after_EditHandler*"> ObjectMethod afterEditHandler <tt>()</tt></a></li>
  32         <li><a href="#ObjectMethod *before_SaveHandler"> ObjectMethod beforeSaveHandler <tt>()</tt></a></li>
  33         <li><a href="#ObjectMethod *after_SaveHandler*"> ObjectMethod afterSaveHandler <tt>()</tt></a></li>
  34         <li><a href="#ObjectMethod *after_RenameHandle"> ObjectMethod afterRenameHandler <tt>($oldWeb,$oldTopic,$oldAttachment,$newWeb,$newTopic,$newAttachment)</tt></a></li>
  35         <li><a href="#ObjectMethod <strong>mergeHandler</strong> ()"> ObjectMethod mergeHandler <tt>()</tt></a></li>
  36         <li><a href="#ObjectMethod *before_AttachmentS"> ObjectMethod beforeAttachmentSaveHandler <tt>($attrHashRef,$topic,$web)</tt></a></li>
  37         <li><a href="#ObjectMethod *after_AttachmentSa"> ObjectMethod afterAttachmentSaveHandler <tt>($attachmentAttrHash,$topic,$web,$error)</tt></a></li>
  38         <li><a href="#ObjectMethod *write_HeaderHandle"> ObjectMethod writeHeaderHandler <tt>() -&gt; $headers</tt></a></li>
  39         <li><a href="#ObjectMethod *modify_HeaderHandl"> ObjectMethod modifyHeaderHandler <tt>(\@headers,$query)</tt></a></li>
  40         <li><a href="#ObjectMethod *complete_PageHandl"> ObjectMethod completePageHandler <tt>($text,$pageType,$contentType)</tt></a></li>
  41         <li><a href="#ObjectMethod *redirect_CgiQueryH"> ObjectMethod redirectCgiQueryHandler <tt>() -&gt; $result</tt></a></li>
  42         <li><a href="#ObjectMethod *render_FormFieldFo"> ObjectMethod renderFormFieldForEditHandler <tt>($name,$type,$size,$value,$attributes,$possibleValues) -&gt; $html</tt></a></li>
  43         <li><a href="#ObjectMethod *render_WikiWordHan"> ObjectMethod renderWikiWordHandler <tt>() -&gt; $result</tt></a></li>
  44       </ul>
  45     </li>
  46   </ul>
  47 </div>
  48
  49 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:
  50
  51 `my $pref = TWiki::getPreferencesValue('URGH');`
  52
  53 should be replaced with
  54
  55 `my $pref = TWiki::Func::getPreferencesValue('URGH');`
  56
  57 and the call
  58
  59 `my $t = TWiki::writeWarning($message);`
  60
  61 should be replaced with
  62
  63 `my $pref = $TWiki::Plugins::SESSION->writeWarning($message);`
  64
  65 Methods in other modules such as Store must be accessed through the relevant TWiki sub-object, for example
  66
  67 `TWiki::Store::saveTopic(...)`
  68
  69 should be replaced with
  70
  71 `$TWiki::Plugins::SESSION->{store}->saveTopic(...)`
  72
  73 Note that calling TWiki internal methods is very very bad practice, and should be avoided wherever practical.
  74
  75 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.
  76
  77 ## <a name="PUBLIC constant $VERSION"></a> PUBLIC constant $VERSION
  78
  79 This is the version number of the plugins package. Use it for checking if you have a recent enough version.
  80
  81 ## <a name="PUBLIC $SESSION"></a> PUBLIC $SESSION
  82
  83 This is a reference to the TWiki session object. It can be used in plugins to get at the methods of the TWiki kernel.
  84
  85 You are _highly_ recommended to only use the methods in the [[Func|Main/TWikiFuncDotPm]] interface, unless you have no other choice, as kernel methods may change between TWiki releases.
  86
  87 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session)"></a> [[ClassMethod]] **new** `($session)`
  88
  89 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.
  90
  91 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
  92
  93 Break circular references.
  94
  95 ## <a name="ObjectMethod &lt;strong&gt;load&lt;/strong&gt; ($allDisable"></a> [[ObjectMethod]] **load** `($allDisabled) -> $loginName`
  96
  97 Find all active plugins, and invoke the early initialisation. Has to be done _after_ prefs are read.
  98
  99 Returns the user returned by the last `initializeUserHandler` to be called.
 100
 101 If allDisabled is set, no plugin handlers will be called.
 102
 103 ## <a name="ObjectMethod &lt;strong&gt;settings&lt;/strong&gt; ()"></a> [[ObjectMethod]] **settings** `()`
 104
 105 Push plugin settings onto preference stack
 106
 107 ## <a name="ObjectMethod &lt;strong&gt;enable&lt;/strong&gt; ()"></a> [[ObjectMethod]] **enable** `()`
 108
 109 Initialisation that is done after the user is known.
 110
 111 ## <a name="ObjectMethod &lt;strong&gt;get_PluginVersion*"></a> [[ObjectMethod]] \*getPluginVersion `() -> $number`
 112
 113 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.
 114
 115 ## <a name="ObjectMethod &lt;strong&gt;addListener&lt;/strong&gt; ($com"></a> [[ObjectMethod]] **addListener** `($command,$handler)`
 116
 117 - `$command` - name of the event
 118 - `$handler` - the handler object.
 119
 120 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.
 121
 122 ## <a name="ObjectMethod &lt;strong&gt;have_HandlerFor&lt;/strong&gt; ("></a> [[ObjectMethod]] **haveHandlerFor** `($handlerName) -> $boolean`
 123
 124 - `$handlerName` - name of the handler e.g. preRenderingHandler
 125
 126 Return: true if at least one plugin has registered a handler of this type.
 127
 128 ## <a name="ObjectMethod &lt;strong&gt;registrationHandle"></a> [[ObjectMethod]] \*registrationHandler `()`
 129
 130 Called by the register script
 131
 132 ## <a name="ObjectMethod &lt;strong&gt;before_CommonTagsH"></a> [[ObjectMethod]] \*beforeCommonTagsHandler `()`
 133
 134 Called at the beginning (for cache Plugins only)
 135
 136 ## <a name="ObjectMethod &lt;strong&gt;common_TagsHandler"></a> [[ObjectMethod]] \*commonTagsHandler `()`
 137
 138 Called after %INCLUDE:"..."%
 139
 140 ## <a name="ObjectMethod &lt;strong&gt;after_CommonTagsHa"></a> [[ObjectMethod]] \*afterCommonTagsHandler `()`
 141
 142 Called at the end (for cache Plugins only)
 143
 144 ## <a name="ObjectMethod &lt;strong&gt;pre_RenderingHandl"></a> [[ObjectMethod]] \*preRenderingHandler `($text,\%map)`
 145
 146 - `$text` - the text, with the head, verbatim and pre blocks replaced with placeholders
 147 - `\%removed` - reference to a hash that maps the placeholders to the removed blocks.
 148
 149 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.
 150
 151 Each removed block is represented by the block text and the parameters passed to the tag (usually empty) e.g. for
 152
 153     <pre class='slobadob'>
 154     XYZ
 155     </pre>
 156
 157 the map will contain:
 158
 159     $removed->{'pre1'}{text}:   XYZ
 160     $removed->{'pre1'}{params}: class="slobadob"
 161
 162 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:
 163
 164     foreach my $placeholder ( keys %$map ) {
 165         if( $placeholder =~ /^pre/i ) {
 166            my $n = 1;
 167            $map->{$placeholder}{text} =~ s/^/$n++/gem;
 168         }
 169     }
 170
 171 ## <a name="ObjectMethod &lt;strong&gt;post_RenderingHand"></a> [[ObjectMethod]] \*postRenderingHandler `(\$text)`
 172
 173 - `\$text` - a reference to the HTML, with the head, verbatim and pre blocks replaced with placeholders
 174
 175 ## <a name="ObjectMethod &lt;strong&gt;start_RenderingHan"></a> [[ObjectMethod]] \*startRenderingHandler `()`
 176
 177 Called just before the line loop
 178
 179 **DEPRECATED** Use preRenderingHandler instead. This handler correctly handles verbatim and other TWiki ML block types, and exposes them to the plugin.
 180
 181 ## <a name="ObjectMethod &lt;strong&gt;outsidePREHandler*"></a> [[ObjectMethod]] \*outsidePREHandler `()`
 182
 183 Called in line loop outside of &lt;PRE&gt; tag
 184
 185 **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.
 186
 187 ## <a name="ObjectMethod &lt;strong&gt;insidePREHandler*"></a><a name="ObjectMethod *insidePREHandler&lt;/strong&gt; "></a> [[ObjectMethod]] **insidePREHandler** `()`
 188
 189 Called in line loop inside of &lt;PRE&gt; tag
 190
 191 **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.
 192
 193 ## <a name="ObjectMethod &lt;strong&gt;end_RenderingHandl"></a> [[ObjectMethod]] \*endRenderingHandler `()`
 194
 195 Called just after the line loop
 196
 197 **DEPRECATED** Use postRenderingHandler instead.
 198
 199 ## <a name="ObjectMethod &lt;strong&gt;before_EditHandler"></a> [[ObjectMethod]] \*beforeEditHandler `()`
 200
 201 Called by edit
 202
 203 ## <a name="ObjectMethod &lt;strong&gt;after_EditHandler*"></a> [[ObjectMethod]] \*afterEditHandler `()`
 204
 205 Called by edit
 206
 207 ## <a name="ObjectMethod &lt;strong&gt;before_SaveHandler"></a> [[ObjectMethod]] \*beforeSaveHandler `()`
 208
 209 Called just before the save action
 210
 211 ## <a name="ObjectMethod &lt;strong&gt;after_SaveHandler*"></a> [[ObjectMethod]] \*afterSaveHandler `()`
 212
 213 Called just after the save action
 214
 215 ## <a name="ObjectMethod &lt;strong&gt;after_RenameHandle"></a> [[ObjectMethod]] \*afterRenameHandler `($oldWeb,$oldTopic,$oldAttachment,$newWeb,$newTopic,$newAttachment)`
 216
 217 Called just after the rename/move/delete action of a web, topic or attachment.
 218
 219 - `$oldWeb` - name of old web
 220 - `$oldTopic` - name of old topic (empty string if web rename)
 221 - `$oldAttachment` - name of old attachment (empty string if web or topic rename)
 222 - `$newWeb` - name of new web
 223 - `$newTopic` - name of new topic (empty string if web rename)
 224 - `$newAttachment` - name of new attachment (empty string if web or topic rename)
 225
 226 ## <a name="ObjectMethod &lt;strong&gt;mergeHandler&lt;/strong&gt; ()"></a> [[ObjectMethod]] **mergeHandler** `()`
 227
 228 Called to handle text merge.
 229
 230 ## <a name="ObjectMethod &lt;strong&gt;before_AttachmentS"></a> [[ObjectMethod]] \*beforeAttachmentSaveHandler `($attrHashRef,$topic,$web)`
 231
 232 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.
 233
 234 - `$attrHashRef` - Hash reference of attachment attributes (keys are indicated below)
 235 - `$topic` - Topic name
 236 - `$web` - Web name
 237
 238 Keys in $attrHashRef:
 239
 240 <table border="1" cellpadding="0" cellspacing="0">
 241   <tr>
 242     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 243     <th bgcolor="#99CCCC"><strong> Value </strong></th>
 244   </tr>
 245   <tr>
 246     <td> attachment </td>
 247     <td> Name of the attachment </td>
 248   </tr>
 249   <tr>
 250     <td> tmpFilename </td>
 251     <td> Name of the local file that stores the upload </td>
 252   </tr>
 253   <tr>
 254     <td> comment </td>
 255     <td> Comment to be associated with the upload </td>
 256   </tr>
 257   <tr>
 258     <td> user </td>
 259     <td> Login name of the person submitting the attachment, e.g. 'jsmith' </td>
 260   </tr>
 261 </table>
 262
 263 Note: All keys should be used read-only, except for comment which can be modified.
 264
 265 Example usage:
 266
 267        my( $attrHashRef, $topic, $web ) = @_;
 268        $$attrHashRef{'comment'} .= " (NOTE: Extracted from blah.tar.gz)";
 269
 270 ## <a name="ObjectMethod &lt;strong&gt;after_AttachmentSa"></a> [[ObjectMethod]] \*afterAttachmentSaveHandler `($attachmentAttrHash,$topic,$web,$error)`
 271
 272 deal with an uploaded attachment between the upload and save-to-store processes. It is invoked as per other plugins.
 273
 274 - `$attrHashRef` - Hash reference of attachment attributes (keys are indicated below)
 275 - `$topic` - Topic name
 276 - `$web` - Web name
 277 - `$error` - Error string of save action, empty if OK
 278
 279 Keys in $attrHashRef:
 280
 281 <table border="1" cellpadding="0" cellspacing="0">
 282   <tr>
 283     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 284     <th bgcolor="#99CCCC"><strong> Value </strong></th>
 285   </tr>
 286   <tr>
 287     <td> attachment </td>
 288     <td> Name of the attachment </td>
 289   </tr>
 290   <tr>
 291     <td> tmpFilename </td>
 292     <td> Name of the local file that stores the upload </td>
 293   </tr>
 294   <tr>
 295     <td> comment </td>
 296     <td> Comment to be associated with the upload </td>
 297   </tr>
 298   <tr>
 299     <td> user </td>
 300     <td> Login name of the person submitting the attachment, e.g. 'jsmith' </td>
 301   </tr>
 302 </table>
 303
 304 Note: The hash is **read-only**
 305
 306 ## <a name="ObjectMethod &lt;strong&gt;write_HeaderHandle"></a> [[ObjectMethod]] \*writeHeaderHandler `() -> $headers`
 307
 308 **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.
 309
 310 ## <a name="ObjectMethod &lt;strong&gt;modify_HeaderHandl"></a> [[ObjectMethod]] \*modifyHeaderHandler `(\@headers,$query)`
 311
 312 ## <a name="ObjectMethod &lt;strong&gt;complete_PageHandl"></a> [[ObjectMethod]] \*completePageHandler `($text,$pageType,$contentType)`
 313
 314 ## <a name="ObjectMethod &lt;strong&gt;redirect_CgiQueryH"></a> [[ObjectMethod]] \*redirectCgiQueryHandler `() -> $result`
 315
 316 Called by TWiki::redirect
 317
 318 ## <a name="ObjectMethod &lt;strong&gt;render_FormFieldFo"></a> [[ObjectMethod]] \*renderFormFieldForEditHandler `($name,$type,$size,$value,$attributes,$possibleValues) -> $html`
 319
 320 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.
 321
 322 - `$name` - name of form field
 323 - `$type` - type of form field
 324 - `$size` - size of form field
 325 - `$value` - value held in the form field
 326 - `$attributes` - attributes of form field
 327 - `$possibleValues` - the values defined as options for form field, if any. May be a scalar (one legal value) or an array (several legal values)
 328
 329 Return HTML text that renders this field. If false, form rendering continues by considering the built-in types.
 330
 331 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.
 332
 333 ## <a name="ObjectMethod &lt;strong&gt;render_WikiWordHan"></a> [[ObjectMethod]] \*renderWikiWordHandler `() -> $result`
 334
 335 Change how a [[WikiWord]] is rendered
 336
 337 Originated from the TWiki:Plugins.SpacedWikiWordPlugin hack