data/TWiki/TWikiPluginsDotPm.txt,v
changeset 0 414e01d06fd5
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     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 @