data/TWiki/TWikiPluginsDotPm.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
     1 head	1.3;
     2 access;
     3 symbols;
     4 locks; strict;
     5 comment	@# @;
     6 
     7 
     8 1.3
     9 date	2008.01.22.03.21.25;	author TWikiContributor;	state Exp;
    10 branches;
    11 next	1.2;
    12 
    13 1.2
    14 date	2007.01.16.04.11.57;	author TWikiContributor;	state Exp;
    15 branches;
    16 next	1.1;
    17 
    18 1.1
    19 date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    20 branches;
    21 next	;
    22 
    23 
    24 desc
    25 @new-topic
    26 @
    27 
    28 
    29 1.3
    30 log
    31 @buildrelease
    32 @
    33 text
    34 @---+ Package =TWiki::Plugins=
    35 
    36 This module defines the singleton object that handles Plugins
    37 loading, initialization and execution.
    38 
    39 This class uses Chain of Responsibility (GOF) pattern to dispatch
    40 handler calls to registered plugins.
    41 
    42 
    43 %TOC%
    44 
    45 Note that as of version 1.026 of this module, TWiki internal
    46 methods are _no longer available_ to plugins. Any calls to
    47 TWiki internal methods must be replaced by calls via the
    48 =$SESSION= object in this package, or via the Func package.
    49 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
    66 the relevant TWiki sub-object, for example
    67 
    68 =TWiki::Store::saveTopic(...)=
    69 
    70 should be replaced with
    71 
    72 =$TWiki::Plugins::SESSION->{store}->saveTopic(...)=
    73 
    74 Note that calling TWiki internal methods is very very bad practice,
    75 and should be avoided wherever practical.
    76 
    77 The developers of TWiki reserve the right to change internal
    78 methods without warning, unless those methods are clearly
    79 marked as PUBLIC. PUBLIC methods are part of the core specification
    80 of a module and can be trusted.
    81 
    82 
    83 ---++ PUBLIC constant $VERSION
    84 
    85 This is the version number of the plugins package. Use it for checking
    86 if you have a recent enough version.
    87 
    88 ---++ PUBLIC $SESSION
    89 
    90 This is a reference to the TWiki session object. It can be used in
    91 plugins to get at the methods of the TWiki kernel.
    92 
    93 You are _highly_ recommended to only use the methods in the
    94 [[TWikiFuncDotPm][Func]] interface, unless you have no other choice,
    95 as kernel methods may change between TWiki releases.
    96 
    97 
    98 ---++ ClassMethod *new* <tt>($session)</tt>
    99 
   100 Construct new singleton plugins collection object. The object is a
   101 container for a list of plugins and the handlers registered by the plugins.
   102 The plugins and the handlers are carefully ordered.
   103 
   104 
   105 
   106 ---++ ObjectMethod *finish* <tt>()</tt>
   107 Break circular references.
   108 
   109 
   110 
   111 ---++ ObjectMethod *load* <tt>($allDisabled) -> $loginName</tt>
   112 
   113 Find all active plugins, and invoke the early initialisation.
   114 Has to be done _after_ prefs are read.
   115 
   116 Returns the user returned by the last =initializeUserHandler= to be
   117 called.
   118 
   119 If allDisabled is set, no plugin handlers will be called.
   120 
   121 
   122 
   123 ---++ ObjectMethod *settings* <tt>()</tt>
   124 
   125 Push plugin settings onto preference stack
   126 
   127 
   128 
   129 ---++ ObjectMethod *enable* <tt>()</tt>
   130 
   131 Initialisation that is done after the user is known.
   132 
   133 
   134 
   135 ---++ ObjectMethod *getPluginVersion* <tt>() -> $number</tt>
   136 
   137 Returns the $TWiki::Plugins::VERSION number if no parameter is specified,
   138 else returns the version number of a named Plugin. If the Plugin cannot
   139 be found or is not active, 0 is returned.
   140 
   141 
   142 
   143 ---++ ObjectMethod *addListener* <tt>($command,$handler)</tt>
   144 
   145    * =$command= - name of the event
   146    * =$handler= - the handler object.
   147 
   148 Add a listener to the end of the list of registered listeners for this event.
   149 The listener must implement =invoke($command,...)=, which will be triggered
   150 when the event is to be processed.
   151 
   152 
   153 
   154 ---++ ObjectMethod *haveHandlerFor* <tt>($handlerName) -> $boolean</tt>
   155 
   156    * =$handlerName= - name of the handler e.g. preRenderingHandler
   157 Return: true if at least one plugin has registered a handler of
   158 this type.
   159 
   160 
   161 
   162 ---++ ObjectMethod *registrationHandler* <tt>()</tt>
   163 
   164 Called by the register script
   165 
   166 
   167 
   168 ---++ ObjectMethod *beforeCommonTagsHandler* <tt>()</tt>
   169 
   170 Called at the beginning (for cache Plugins only)
   171 
   172 
   173 
   174 ---++ ObjectMethod *commonTagsHandler* <tt>()</tt>
   175 
   176 Called after %INCLUDE:"..."%
   177 
   178 
   179 
   180 ---++ ObjectMethod *afterCommonTagsHandler* <tt>()</tt>
   181 
   182 Called at the end (for cache Plugins only)
   183 
   184 
   185 
   186 ---++ ObjectMethod *preRenderingHandler* <tt>($text,\%map)</tt>
   187 
   188    * =$text= - the text, with the head, verbatim and pre blocks replaced with placeholders
   189    * =\%removed= - reference to a hash that maps the placeholders to the removed blocks.
   190 
   191 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.
   192 
   193 Each removed block is represented by the block text and the parameters passed to the tag (usually empty) e.g. for
   194 <verbatim>
   195 <pre class='slobadob'>
   196 XYZ
   197 </pre>
   198 </verbatim>
   199 the map will contain:
   200 <verbatim>
   201 $removed->{'pre1'}{text}:   XYZ
   202 $removed->{'pre1'}{params}: class="slobadob"
   203 </verbatim>
   204 
   205 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:
   206 
   207 <verbatim>
   208 foreach my $placeholder ( keys %$map ) {
   209     if( $placeholder =~ /^pre/i ) {
   210        my $n = 1;
   211        $map->{$placeholder}{text} =~ s/^/$n++/gem;
   212     }
   213 }
   214 </verbatim>
   215 
   216 
   217 
   218 ---++ ObjectMethod *postRenderingHandler* <tt>(\$text)</tt>
   219 
   220    * =\$text= - a reference to the HTML, with the head, verbatim and pre blocks replaced with placeholders
   221 
   222 
   223 
   224 ---++ ObjectMethod *startRenderingHandler* <tt>()</tt>
   225 
   226 Called just before the line loop
   227 
   228 *DEPRECATED* Use preRenderingHandler instead. This handler correctly 
   229 handles verbatim and other TWiki ML block types, and exposes them to 
   230 the plugin.
   231 
   232 
   233 
   234 ---++ ObjectMethod *outsidePREHandler* <tt>()</tt>
   235 
   236 Called in line loop outside of &lt;PRE&gt; tag
   237 
   238 *DEPRECATED* Use preRenderingHandler instead. 
   239 This handler correctly handles pre and other 
   240 TWiki ML block types, and is called only once 
   241 instead of line-by-line.
   242 
   243 
   244 
   245 ---++ ObjectMethod *insidePREHandler* <tt>()</tt>
   246 
   247 Called in line loop inside of &lt;PRE&gt; tag
   248 
   249 *DEPRECATED* Use preRenderingHandler instead. 
   250 This handler correctly handles pre and other 
   251 TWiki ML block types, and is called only once 
   252 instead of line-by-line.
   253 
   254 
   255 
   256 ---++ ObjectMethod *endRenderingHandler* <tt>()</tt>
   257 
   258 Called just after the line loop
   259 
   260 *DEPRECATED* Use postRenderingHandler instead.
   261 
   262 
   263 
   264 ---++ ObjectMethod *beforeEditHandler* <tt>()</tt>
   265 
   266 Called by edit
   267 
   268 
   269 
   270 ---++ ObjectMethod *afterEditHandler* <tt>()</tt>
   271 
   272 Called by edit
   273 
   274 
   275 
   276 ---++ ObjectMethod *beforeSaveHandler* <tt>()</tt>
   277 
   278 Called just before the save action
   279 
   280 
   281 
   282 ---++ ObjectMethod *afterSaveHandler* <tt>()</tt>
   283 
   284 Called just after the save action
   285 
   286 
   287 
   288 ---++ ObjectMethod *afterRenameHandler* <tt>($oldWeb,$oldTopic,$oldAttachment,$newWeb,$newTopic,$newAttachment)</tt>
   289 
   290 Called just after the rename/move/delete action of a web, topic or attachment.
   291 
   292    * =$oldWeb= - name of old web
   293    * =$oldTopic= - name of old topic (empty string if web rename)
   294    * =$oldAttachment= - name of old attachment (empty string if web or topic rename)
   295    * =$newWeb= - name of new web
   296    * =$newTopic= - name of new topic (empty string if web rename)
   297    * =$newAttachment= - name of new attachment (empty string if web or topic rename)
   298 
   299 
   300 
   301 ---++ ObjectMethod *mergeHandler* <tt>()</tt>
   302 
   303 Called to handle text merge.
   304 
   305 
   306 
   307 ---++ ObjectMethod *beforeAttachmentSaveHandler* <tt>($attrHashRef,$topic,$web)</tt>
   308 
   309 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.
   310    * =$attrHashRef= - Hash reference of attachment attributes (keys are indicated below)
   311    * =$topic= -     Topic name
   312    * =$web= -       Web name
   313 
   314 Keys in $attrHashRef:
   315 | *Key*       | *Value* |
   316 | attachment  | Name of the attachment |
   317 | tmpFilename | Name of the local file that stores the upload |
   318 | comment     | Comment to be associated with the upload |
   319 | user        | Login name of the person submitting the attachment, e.g. 'jsmith' |
   320 
   321 Note: All keys should be used read-only, except for comment which can be modified.
   322 
   323 Example usage:
   324 
   325 <pre>
   326    my( $attrHashRef, $topic, $web ) = @@_;
   327    $$attrHashRef{'comment'} .= " (NOTE: Extracted from blah.tar.gz)";
   328 </pre>
   329 
   330 
   331 
   332 ---++ ObjectMethod *afterAttachmentSaveHandler* <tt>($attachmentAttrHash,$topic,$web,$error)</tt>
   333 
   334 deal with an uploaded attachment between the upload and save-to-store processes. It is invoked as per other plugins.
   335 
   336    * =$attrHashRef= - Hash reference of attachment attributes (keys are indicated below)
   337    * =$topic= -     Topic name
   338    * =$web= -       Web name
   339    * =$error= -     Error string of save action, empty if OK
   340 
   341 Keys in $attrHashRef:
   342 | *Key*       | *Value* |
   343 | attachment  | Name of the attachment |
   344 | tmpFilename | Name of the local file that stores the upload |
   345 | comment     | Comment to be associated with the upload |
   346 | user        | Login name of the person submitting the attachment, e.g. 'jsmith' |
   347 
   348 Note: The hash is *read-only*
   349 
   350 
   351 
   352 ---++ ObjectMethod *writeHeaderHandler* <tt>() -> $headers</tt>
   353 
   354 *DEPRECATED* Use modifyHeaderHandler instead. it is a lot 
   355 more flexible, and allows you to modify existing headers 
   356 as well as add new ones. It also works correctly when 
   357 multiple plugins want to modify headers.
   358 
   359 
   360 
   361 ---++ ObjectMethod *modifyHeaderHandler* <tt>(\@@headers,$query)</tt>
   362 
   363 
   364 
   365 ---++ ObjectMethod *completePageHandler* <tt>($text,$pageType,$contentType)</tt>
   366 
   367 
   368 
   369 ---++ ObjectMethod *redirectCgiQueryHandler* <tt>() -> $result</tt>
   370 
   371 Called by TWiki::redirect
   372 
   373 
   374 
   375 ---++ ObjectMethod *renderFormFieldForEditHandler* <tt>($name,$type,$size,$value,$attributes,$possibleValues) -> $html</tt>
   376 
   377 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.
   378    * =$name= - name of form field
   379    * =$type= - type of form field
   380    * =$size= - size of form field
   381    * =$value= - value held in the form field
   382    * =$attributes= - attributes of form field 
   383    * =$possibleValues= - the values defined as options for form field, if any. May be a scalar (one legal value) or an array (several legal values)
   384 Return HTML text that renders this field. If false, form rendering continues by considering the built-in types.
   385 
   386 Note that a common application would be to generate formatting of the
   387 field involving generation of javascript. Such usually also requires
   388 the insertion of some common javascript into the page header. Unfortunately,
   389 there is currently no mechanism to pass that script to where the header of
   390 the page is visible. Consequentially, the common javascript may have to
   391 be emitted as part of the field formatting and might be duplicated many
   392 times throughout the page.
   393 
   394 
   395 
   396 ---++ ObjectMethod *renderWikiWordHandler* <tt>() -> $result</tt>
   397 
   398 Change how a WikiWord is rendered
   399 
   400 Originated from the TWiki:Plugins.SpacedWikiWordPlugin hack
   401 
   402 
   403 @
   404 
   405 
   406 1.2
   407 log
   408 @buildrelease
   409 @
   410 text
   411 @d73 5
   412 d112 1
   413 a112 1
   414    * =$command* - name of the event
   415 d165 1
   416 d167 1
   417 a167 1
   418 <pre>
   419 a169 1
   420 </pre>
   421 d174 1
   422 d181 1
   423 d278 2
   424 a279 2
   425    * =$topic= -     | Topic name
   426    * =$web= -       | Web name
   427 d304 3
   428 a306 3
   429    * =$topic= -     | Topic name
   430    * =$web= -       | Web name
   431    * =$error= -     | Error string of save action, empty if OK
   432 a320 2
   433 Called by TWiki::writePageHeader. *DEPRECATED* do not use!
   434 
   435 d332 4
   436 @
   437 
   438 
   439 1.1
   440 log
   441 @buildrelease
   442 @
   443 text
   444 @d15 1
   445 a15 1
   446 $SESSION object in this package, or via the Func package.
   447 d18 1
   448 a18 1
   449 my $pref = TWiki::getPreferencesValue('URGH');
   450 d22 1
   451 a22 1
   452 my $pref = TWiki::Func::getPreferencesValue('URGH');
   453 d26 1
   454 a26 1
   455 my $t = TWiki::writeWarning($message);
   456 d30 1
   457 a30 1
   458 my $pref = $TWiki::Plugins::SESSION->writeWarning($message);
   459 d35 1
   460 a35 1
   461 TWiki::Store::saveTopic(...)
   462 d39 1
   463 a39 1
   464 $TWiki::Plugins::SESSION->{store}->saveTopic(...)
   465 d51 1
   466 d56 1
   467 d85 6
   468 d106 1
   469 d117 1
   470 d148 1
   471 a148 1
   472 ---++ ObjectMethd preRenderingHandler( $text, \%map )
   473 d165 1
   474 d177 1
   475 d248 13
   476 @