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