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