data/TWiki/TWikiPluginsDotPm.txt,v
changeset 0 414e01d06fd5
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiPluginsDotPm.txt,v	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,476 @@
     1.4 +head	1.3;
     1.5 +access;
     1.6 +symbols;
     1.7 +locks; strict;
     1.8 +comment	@# @;
     1.9 +
    1.10 +
    1.11 +1.3
    1.12 +date	2008.01.22.03.21.25;	author TWikiContributor;	state Exp;
    1.13 +branches;
    1.14 +next	1.2;
    1.15 +
    1.16 +1.2
    1.17 +date	2007.01.16.04.11.57;	author TWikiContributor;	state Exp;
    1.18 +branches;
    1.19 +next	1.1;
    1.20 +
    1.21 +1.1
    1.22 +date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    1.23 +branches;
    1.24 +next	;
    1.25 +
    1.26 +
    1.27 +desc
    1.28 +@new-topic
    1.29 +@
    1.30 +
    1.31 +
    1.32 +1.3
    1.33 +log
    1.34 +@buildrelease
    1.35 +@
    1.36 +text
    1.37 +@---+ Package =TWiki::Plugins=
    1.38 +
    1.39 +This module defines the singleton object that handles Plugins
    1.40 +loading, initialization and execution.
    1.41 +
    1.42 +This class uses Chain of Responsibility (GOF) pattern to dispatch
    1.43 +handler calls to registered plugins.
    1.44 +
    1.45 +
    1.46 +%TOC%
    1.47 +
    1.48 +Note that as of version 1.026 of this module, TWiki internal
    1.49 +methods are _no longer available_ to plugins. Any calls to
    1.50 +TWiki internal methods must be replaced by calls via the
    1.51 +=$SESSION= object in this package, or via the Func package.
    1.52 +For example, the call:
    1.53 +
    1.54 +=my $pref = TWiki::getPreferencesValue('URGH');=
    1.55 +
    1.56 +should be replaced with
    1.57 +
    1.58 +=my $pref = TWiki::Func::getPreferencesValue('URGH');=
    1.59 +
    1.60 +and the call
    1.61 +
    1.62 +=my $t = TWiki::writeWarning($message);=
    1.63 +
    1.64 +should be replaced with
    1.65 +
    1.66 +=my $pref = $TWiki::Plugins::SESSION->writeWarning($message);=
    1.67 +
    1.68 +Methods in other modules such as Store must be accessed through
    1.69 +the relevant TWiki sub-object, for example
    1.70 +
    1.71 +=TWiki::Store::saveTopic(...)=
    1.72 +
    1.73 +should be replaced with
    1.74 +
    1.75 +=$TWiki::Plugins::SESSION->{store}->saveTopic(...)=
    1.76 +
    1.77 +Note that calling TWiki internal methods is very very bad practice,
    1.78 +and should be avoided wherever practical.
    1.79 +
    1.80 +The developers of TWiki reserve the right to change internal
    1.81 +methods without warning, unless those methods are clearly
    1.82 +marked as PUBLIC. PUBLIC methods are part of the core specification
    1.83 +of a module and can be trusted.
    1.84 +
    1.85 +
    1.86 +---++ PUBLIC constant $VERSION
    1.87 +
    1.88 +This is the version number of the plugins package. Use it for checking
    1.89 +if you have a recent enough version.
    1.90 +
    1.91 +---++ PUBLIC $SESSION
    1.92 +
    1.93 +This is a reference to the TWiki session object. It can be used in
    1.94 +plugins to get at the methods of the TWiki kernel.
    1.95 +
    1.96 +You are _highly_ recommended to only use the methods in the
    1.97 +[[TWikiFuncDotPm][Func]] interface, unless you have no other choice,
    1.98 +as kernel methods may change between TWiki releases.
    1.99 +
   1.100 +
   1.101 +---++ ClassMethod *new* <tt>($session)</tt>
   1.102 +
   1.103 +Construct new singleton plugins collection object. The object is a
   1.104 +container for a list of plugins and the handlers registered by the plugins.
   1.105 +The plugins and the handlers are carefully ordered.
   1.106 +
   1.107 +
   1.108 +
   1.109 +---++ ObjectMethod *finish* <tt>()</tt>
   1.110 +Break circular references.
   1.111 +
   1.112 +
   1.113 +
   1.114 +---++ ObjectMethod *load* <tt>($allDisabled) -> $loginName</tt>
   1.115 +
   1.116 +Find all active plugins, and invoke the early initialisation.
   1.117 +Has to be done _after_ prefs are read.
   1.118 +
   1.119 +Returns the user returned by the last =initializeUserHandler= to be
   1.120 +called.
   1.121 +
   1.122 +If allDisabled is set, no plugin handlers will be called.
   1.123 +
   1.124 +
   1.125 +
   1.126 +---++ ObjectMethod *settings* <tt>()</tt>
   1.127 +
   1.128 +Push plugin settings onto preference stack
   1.129 +
   1.130 +
   1.131 +
   1.132 +---++ ObjectMethod *enable* <tt>()</tt>
   1.133 +
   1.134 +Initialisation that is done after the user is known.
   1.135 +
   1.136 +
   1.137 +
   1.138 +---++ ObjectMethod *getPluginVersion* <tt>() -> $number</tt>
   1.139 +
   1.140 +Returns the $TWiki::Plugins::VERSION number if no parameter is specified,
   1.141 +else returns the version number of a named Plugin. If the Plugin cannot
   1.142 +be found or is not active, 0 is returned.
   1.143 +
   1.144 +
   1.145 +
   1.146 +---++ ObjectMethod *addListener* <tt>($command,$handler)</tt>
   1.147 +
   1.148 +   * =$command= - name of the event
   1.149 +   * =$handler= - the handler object.
   1.150 +
   1.151 +Add a listener to the end of the list of registered listeners for this event.
   1.152 +The listener must implement =invoke($command,...)=, which will be triggered
   1.153 +when the event is to be processed.
   1.154 +
   1.155 +
   1.156 +
   1.157 +---++ ObjectMethod *haveHandlerFor* <tt>($handlerName) -> $boolean</tt>
   1.158 +
   1.159 +   * =$handlerName= - name of the handler e.g. preRenderingHandler
   1.160 +Return: true if at least one plugin has registered a handler of
   1.161 +this type.
   1.162 +
   1.163 +
   1.164 +
   1.165 +---++ ObjectMethod *registrationHandler* <tt>()</tt>
   1.166 +
   1.167 +Called by the register script
   1.168 +
   1.169 +
   1.170 +
   1.171 +---++ ObjectMethod *beforeCommonTagsHandler* <tt>()</tt>
   1.172 +
   1.173 +Called at the beginning (for cache Plugins only)
   1.174 +
   1.175 +
   1.176 +
   1.177 +---++ ObjectMethod *commonTagsHandler* <tt>()</tt>
   1.178 +
   1.179 +Called after %INCLUDE:"..."%
   1.180 +
   1.181 +
   1.182 +
   1.183 +---++ ObjectMethod *afterCommonTagsHandler* <tt>()</tt>
   1.184 +
   1.185 +Called at the end (for cache Plugins only)
   1.186 +
   1.187 +
   1.188 +
   1.189 +---++ ObjectMethod *preRenderingHandler* <tt>($text,\%map)</tt>
   1.190 +
   1.191 +   * =$text= - the text, with the head, verbatim and pre blocks replaced with placeholders
   1.192 +   * =\%removed= - reference to a hash that maps the placeholders to the removed blocks.
   1.193 +
   1.194 +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.
   1.195 +
   1.196 +Each removed block is represented by the block text and the parameters passed to the tag (usually empty) e.g. for
   1.197 +<verbatim>
   1.198 +<pre class='slobadob'>
   1.199 +XYZ
   1.200 +</pre>
   1.201 +</verbatim>
   1.202 +the map will contain:
   1.203 +<verbatim>
   1.204 +$removed->{'pre1'}{text}:   XYZ
   1.205 +$removed->{'pre1'}{params}: class="slobadob"
   1.206 +</verbatim>
   1.207 +
   1.208 +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:
   1.209 +
   1.210 +<verbatim>
   1.211 +foreach my $placeholder ( keys %$map ) {
   1.212 +    if( $placeholder =~ /^pre/i ) {
   1.213 +       my $n = 1;
   1.214 +       $map->{$placeholder}{text} =~ s/^/$n++/gem;
   1.215 +    }
   1.216 +}
   1.217 +</verbatim>
   1.218 +
   1.219 +
   1.220 +
   1.221 +---++ ObjectMethod *postRenderingHandler* <tt>(\$text)</tt>
   1.222 +
   1.223 +   * =\$text= - a reference to the HTML, with the head, verbatim and pre blocks replaced with placeholders
   1.224 +
   1.225 +
   1.226 +
   1.227 +---++ ObjectMethod *startRenderingHandler* <tt>()</tt>
   1.228 +
   1.229 +Called just before the line loop
   1.230 +
   1.231 +*DEPRECATED* Use preRenderingHandler instead. This handler correctly 
   1.232 +handles verbatim and other TWiki ML block types, and exposes them to 
   1.233 +the plugin.
   1.234 +
   1.235 +
   1.236 +
   1.237 +---++ ObjectMethod *outsidePREHandler* <tt>()</tt>
   1.238 +
   1.239 +Called in line loop outside of &lt;PRE&gt; tag
   1.240 +
   1.241 +*DEPRECATED* Use preRenderingHandler instead. 
   1.242 +This handler correctly handles pre and other 
   1.243 +TWiki ML block types, and is called only once 
   1.244 +instead of line-by-line.
   1.245 +
   1.246 +
   1.247 +
   1.248 +---++ ObjectMethod *insidePREHandler* <tt>()</tt>
   1.249 +
   1.250 +Called in line loop inside of &lt;PRE&gt; tag
   1.251 +
   1.252 +*DEPRECATED* Use preRenderingHandler instead. 
   1.253 +This handler correctly handles pre and other 
   1.254 +TWiki ML block types, and is called only once 
   1.255 +instead of line-by-line.
   1.256 +
   1.257 +
   1.258 +
   1.259 +---++ ObjectMethod *endRenderingHandler* <tt>()</tt>
   1.260 +
   1.261 +Called just after the line loop
   1.262 +
   1.263 +*DEPRECATED* Use postRenderingHandler instead.
   1.264 +
   1.265 +
   1.266 +
   1.267 +---++ ObjectMethod *beforeEditHandler* <tt>()</tt>
   1.268 +
   1.269 +Called by edit
   1.270 +
   1.271 +
   1.272 +
   1.273 +---++ ObjectMethod *afterEditHandler* <tt>()</tt>
   1.274 +
   1.275 +Called by edit
   1.276 +
   1.277 +
   1.278 +
   1.279 +---++ ObjectMethod *beforeSaveHandler* <tt>()</tt>
   1.280 +
   1.281 +Called just before the save action
   1.282 +
   1.283 +
   1.284 +
   1.285 +---++ ObjectMethod *afterSaveHandler* <tt>()</tt>
   1.286 +
   1.287 +Called just after the save action
   1.288 +
   1.289 +
   1.290 +
   1.291 +---++ ObjectMethod *afterRenameHandler* <tt>($oldWeb,$oldTopic,$oldAttachment,$newWeb,$newTopic,$newAttachment)</tt>
   1.292 +
   1.293 +Called just after the rename/move/delete action of a web, topic or attachment.
   1.294 +
   1.295 +   * =$oldWeb= - name of old web
   1.296 +   * =$oldTopic= - name of old topic (empty string if web rename)
   1.297 +   * =$oldAttachment= - name of old attachment (empty string if web or topic rename)
   1.298 +   * =$newWeb= - name of new web
   1.299 +   * =$newTopic= - name of new topic (empty string if web rename)
   1.300 +   * =$newAttachment= - name of new attachment (empty string if web or topic rename)
   1.301 +
   1.302 +
   1.303 +
   1.304 +---++ ObjectMethod *mergeHandler* <tt>()</tt>
   1.305 +
   1.306 +Called to handle text merge.
   1.307 +
   1.308 +
   1.309 +
   1.310 +---++ ObjectMethod *beforeAttachmentSaveHandler* <tt>($attrHashRef,$topic,$web)</tt>
   1.311 +
   1.312 +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.
   1.313 +   * =$attrHashRef= - Hash reference of attachment attributes (keys are indicated below)
   1.314 +   * =$topic= -     Topic name
   1.315 +   * =$web= -       Web name
   1.316 +
   1.317 +Keys in $attrHashRef:
   1.318 +| *Key*       | *Value* |
   1.319 +| attachment  | Name of the attachment |
   1.320 +| tmpFilename | Name of the local file that stores the upload |
   1.321 +| comment     | Comment to be associated with the upload |
   1.322 +| user        | Login name of the person submitting the attachment, e.g. 'jsmith' |
   1.323 +
   1.324 +Note: All keys should be used read-only, except for comment which can be modified.
   1.325 +
   1.326 +Example usage:
   1.327 +
   1.328 +<pre>
   1.329 +   my( $attrHashRef, $topic, $web ) = @@_;
   1.330 +   $$attrHashRef{'comment'} .= " (NOTE: Extracted from blah.tar.gz)";
   1.331 +</pre>
   1.332 +
   1.333 +
   1.334 +
   1.335 +---++ ObjectMethod *afterAttachmentSaveHandler* <tt>($attachmentAttrHash,$topic,$web,$error)</tt>
   1.336 +
   1.337 +deal with an uploaded attachment between the upload and save-to-store processes. It is invoked as per other plugins.
   1.338 +
   1.339 +   * =$attrHashRef= - Hash reference of attachment attributes (keys are indicated below)
   1.340 +   * =$topic= -     Topic name
   1.341 +   * =$web= -       Web name
   1.342 +   * =$error= -     Error string of save action, empty if OK
   1.343 +
   1.344 +Keys in $attrHashRef:
   1.345 +| *Key*       | *Value* |
   1.346 +| attachment  | Name of the attachment |
   1.347 +| tmpFilename | Name of the local file that stores the upload |
   1.348 +| comment     | Comment to be associated with the upload |
   1.349 +| user        | Login name of the person submitting the attachment, e.g. 'jsmith' |
   1.350 +
   1.351 +Note: The hash is *read-only*
   1.352 +
   1.353 +
   1.354 +
   1.355 +---++ ObjectMethod *writeHeaderHandler* <tt>() -> $headers</tt>
   1.356 +
   1.357 +*DEPRECATED* Use modifyHeaderHandler instead. it is a lot 
   1.358 +more flexible, and allows you to modify existing headers 
   1.359 +as well as add new ones. It also works correctly when 
   1.360 +multiple plugins want to modify headers.
   1.361 +
   1.362 +
   1.363 +
   1.364 +---++ ObjectMethod *modifyHeaderHandler* <tt>(\@@headers,$query)</tt>
   1.365 +
   1.366 +
   1.367 +
   1.368 +---++ ObjectMethod *completePageHandler* <tt>($text,$pageType,$contentType)</tt>
   1.369 +
   1.370 +
   1.371 +
   1.372 +---++ ObjectMethod *redirectCgiQueryHandler* <tt>() -> $result</tt>
   1.373 +
   1.374 +Called by TWiki::redirect
   1.375 +
   1.376 +
   1.377 +
   1.378 +---++ ObjectMethod *renderFormFieldForEditHandler* <tt>($name,$type,$size,$value,$attributes,$possibleValues) -> $html</tt>
   1.379 +
   1.380 +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.
   1.381 +   * =$name= - name of form field
   1.382 +   * =$type= - type of form field
   1.383 +   * =$size= - size of form field
   1.384 +   * =$value= - value held in the form field
   1.385 +   * =$attributes= - attributes of form field 
   1.386 +   * =$possibleValues= - the values defined as options for form field, if any. May be a scalar (one legal value) or an array (several legal values)
   1.387 +Return HTML text that renders this field. If false, form rendering continues by considering the built-in types.
   1.388 +
   1.389 +Note that a common application would be to generate formatting of the
   1.390 +field involving generation of javascript. Such usually also requires
   1.391 +the insertion of some common javascript into the page header. Unfortunately,
   1.392 +there is currently no mechanism to pass that script to where the header of
   1.393 +the page is visible. Consequentially, the common javascript may have to
   1.394 +be emitted as part of the field formatting and might be duplicated many
   1.395 +times throughout the page.
   1.396 +
   1.397 +
   1.398 +
   1.399 +---++ ObjectMethod *renderWikiWordHandler* <tt>() -> $result</tt>
   1.400 +
   1.401 +Change how a WikiWord is rendered
   1.402 +
   1.403 +Originated from the TWiki:Plugins.SpacedWikiWordPlugin hack
   1.404 +
   1.405 +
   1.406 +@
   1.407 +
   1.408 +
   1.409 +1.2
   1.410 +log
   1.411 +@buildrelease
   1.412 +@
   1.413 +text
   1.414 +@d73 5
   1.415 +d112 1
   1.416 +a112 1
   1.417 +   * =$command* - name of the event
   1.418 +d165 1
   1.419 +d167 1
   1.420 +a167 1
   1.421 +<pre>
   1.422 +a169 1
   1.423 +</pre>
   1.424 +d174 1
   1.425 +d181 1
   1.426 +d278 2
   1.427 +a279 2
   1.428 +   * =$topic= -     | Topic name
   1.429 +   * =$web= -       | Web name
   1.430 +d304 3
   1.431 +a306 3
   1.432 +   * =$topic= -     | Topic name
   1.433 +   * =$web= -       | Web name
   1.434 +   * =$error= -     | Error string of save action, empty if OK
   1.435 +a320 2
   1.436 +Called by TWiki::writePageHeader. *DEPRECATED* do not use!
   1.437 +
   1.438 +d332 4
   1.439 +@
   1.440 +
   1.441 +
   1.442 +1.1
   1.443 +log
   1.444 +@buildrelease
   1.445 +@
   1.446 +text
   1.447 +@d15 1
   1.448 +a15 1
   1.449 +$SESSION object in this package, or via the Func package.
   1.450 +d18 1
   1.451 +a18 1
   1.452 +my $pref = TWiki::getPreferencesValue('URGH');
   1.453 +d22 1
   1.454 +a22 1
   1.455 +my $pref = TWiki::Func::getPreferencesValue('URGH');
   1.456 +d26 1
   1.457 +a26 1
   1.458 +my $t = TWiki::writeWarning($message);
   1.459 +d30 1
   1.460 +a30 1
   1.461 +my $pref = $TWiki::Plugins::SESSION->writeWarning($message);
   1.462 +d35 1
   1.463 +a35 1
   1.464 +TWiki::Store::saveTopic(...)
   1.465 +d39 1
   1.466 +a39 1
   1.467 +$TWiki::Plugins::SESSION->{store}->saveTopic(...)
   1.468 +d51 1
   1.469 +d56 1
   1.470 +d85 6
   1.471 +d106 1
   1.472 +d117 1
   1.473 +d148 1
   1.474 +a148 1
   1.475 +---++ ObjectMethd preRenderingHandler( $text, \%map )
   1.476 +d165 1
   1.477 +d177 1
   1.478 +d248 13
   1.479 +@