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