lib/TWiki/Plugins/EmptyPlugin.pm
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
# Plugin for TWiki Enterprise Collaboration Platform, http://TWiki.org/
colas@0
     2
#
colas@0
     3
# Copyright (C) 2000-2003 Andrea Sterbini, a.sterbini@flashnet.it
colas@0
     4
# Copyright (C) 2001-2006 Peter Thoeny, peter@thoeny.org
colas@0
     5
# and TWiki Contributors. All Rights Reserved. TWiki Contributors
colas@0
     6
# are listed in the AUTHORS file in the root of this distribution.
colas@0
     7
# NOTE: Please extend that file, not this notice.
colas@0
     8
#
colas@0
     9
# This program is free software; you can redistribute it and/or
colas@0
    10
# modify it under the terms of the GNU General Public License
colas@0
    11
# as published by the Free Software Foundation; either version 2
colas@0
    12
# of the License, or (at your option) any later version. For
colas@0
    13
# more details read LICENSE in the root of this distribution.
colas@0
    14
#
colas@0
    15
# This program is distributed in the hope that it will be useful,
colas@0
    16
# but WITHOUT ANY WARRANTY; without even the implied warranty of
colas@0
    17
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
colas@0
    18
#
colas@0
    19
# For licensing info read LICENSE file in the TWiki root.
colas@0
    20
colas@0
    21
=pod
colas@0
    22
colas@0
    23
---+ package EmptyPlugin
colas@0
    24
colas@0
    25
This is an empty TWiki plugin. It is a fully defined plugin, but is
colas@0
    26
disabled by default in a TWiki installation. Use it as a template
colas@0
    27
for your own plugins; see TWiki.TWikiPlugins for details.
colas@0
    28
colas@0
    29
This version of the !EmptyPlugin documents the handlers supported
colas@0
    30
by revision 1.2 of the Plugins API. See the documentation of =TWiki::Func=
colas@0
    31
for more information about what this revision number means, and how a
colas@0
    32
plugin can check it.
colas@0
    33
colas@0
    34
__NOTE:__ To interact with TWiki use ONLY the official API functions
colas@0
    35
in the TWiki::Func module. Do not reference any functions or
colas@0
    36
variables elsewhere in TWiki, as these are subject to change
colas@0
    37
without prior warning, and your plugin may suddenly stop
colas@0
    38
working.
colas@0
    39
colas@0
    40
For increased performance, all handlers except initPlugin are
colas@0
    41
disabled below. *To enable a handler* remove the leading DISABLE_ from
colas@0
    42
the function name. For efficiency and clarity, you should comment out or
colas@0
    43
delete the whole of handlers you don't use before you release your
colas@0
    44
plugin.
colas@0
    45
colas@0
    46
__NOTE:__ When developing a plugin it is important to remember that
colas@0
    47
TWiki is tolerant of plugins that do not compile. In this case,
colas@0
    48
the failure will be silent but the plugin will not be available.
colas@0
    49
See %TWIKIWEB%.TWikiPlugins#FAILEDPLUGINS for error messages.
colas@0
    50
colas@0
    51
__NOTE:__ Defining deprecated handlers will cause the handlers to be 
colas@0
    52
listed in %TWIKIWEB%.TWikiPlugins#FAILEDPLUGINS. See
colas@0
    53
%TWIKIWEB%.TWikiPlugins#Handlig_deprecated_functions
colas@0
    54
for information on regarding deprecated handlers that are defined for
colas@0
    55
compatibility with older TWiki versions.
colas@0
    56
colas@0
    57
__NOTE:__ When writing handlers, keep in mind that these may be invoked
colas@0
    58
on included topics. For example, if a plugin generates links to the current
colas@0
    59
topic, these need to be generated before the afterCommonTagsHandler is run,
colas@0
    60
as at that point in the rendering loop we have lost the information that we
colas@0
    61
the text had been included from another topic.
colas@0
    62
colas@0
    63
=cut
colas@0
    64
colas@0
    65
# change the package name and $pluginName!!!
colas@0
    66
package TWiki::Plugins::EmptyPlugin;
colas@0
    67
colas@0
    68
# Always use strict to enforce variable scoping
colas@0
    69
use strict;
colas@0
    70
colas@0
    71
require TWiki::Func;    # The plugins API
colas@0
    72
require TWiki::Plugins; # For the API version
colas@0
    73
colas@0
    74
# $VERSION is referred to by TWiki, and is the only global variable that
colas@0
    75
# *must* exist in this package.
colas@0
    76
use vars qw( $VERSION $RELEASE $SHORTDESCRIPTION $debug $pluginName $NO_PREFS_IN_TOPIC );
colas@0
    77
colas@0
    78
# This should always be $Rev: 15942 (22 Jan 2008) $ so that TWiki can determine the checked-in
colas@0
    79
# status of the plugin. It is used by the build automation tools, so
colas@0
    80
# you should leave it alone.
colas@0
    81
$VERSION = '$Rev: 15942 (22 Jan 2008) $';
colas@0
    82
colas@0
    83
# This is a free-form string you can use to "name" your own plugin version.
colas@0
    84
# It is *not* used by the build automation tools, but is reported as part
colas@0
    85
# of the version number in PLUGINDESCRIPTIONS.
colas@0
    86
$RELEASE = 'TWiki-4.2';
colas@0
    87
colas@0
    88
# Short description of this plugin
colas@0
    89
# One line description, is shown in the %TWIKIWEB%.TextFormattingRules topic:
colas@0
    90
$SHORTDESCRIPTION = 'Empty Plugin used as a template for new Plugins';
colas@0
    91
colas@0
    92
# You must set $NO_PREFS_IN_TOPIC to 0 if you want your plugin to use preferences
colas@0
    93
# stored in the plugin topic. This default is required for compatibility with
colas@0
    94
# older plugins, but imposes a significant performance penalty, and
colas@0
    95
# is not recommended. Instead, use $TWiki::cfg entries set in LocalSite.cfg, or
colas@0
    96
# if you want the users to be able to change settings, then use standard TWiki
colas@0
    97
# preferences that can be defined in your Main.TWikiPreferences and overridden
colas@0
    98
# at the web and topic level.
colas@0
    99
$NO_PREFS_IN_TOPIC = 1;
colas@0
   100
colas@0
   101
# Name of this Plugin, only used in this module
colas@0
   102
$pluginName = 'EmptyPlugin';
colas@0
   103
colas@0
   104
=pod
colas@0
   105
colas@0
   106
---++ initPlugin($topic, $web, $user, $installWeb) -> $boolean
colas@0
   107
   * =$topic= - the name of the topic in the current CGI query
colas@0
   108
   * =$web= - the name of the web in the current CGI query
colas@0
   109
   * =$user= - the login name of the user
colas@0
   110
   * =$installWeb= - the name of the web the plugin is installed in
colas@0
   111
colas@0
   112
REQUIRED
colas@0
   113
colas@0
   114
Called to initialise the plugin. If everything is OK, should return
colas@0
   115
a non-zero value. On non-fatal failure, should write a message
colas@0
   116
using TWiki::Func::writeWarning and return 0. In this case
colas@0
   117
%FAILEDPLUGINS% will indicate which plugins failed.
colas@0
   118
colas@0
   119
In the case of a catastrophic failure that will prevent the whole
colas@0
   120
installation from working safely, this handler may use 'die', which
colas@0
   121
will be trapped and reported in the browser.
colas@0
   122
colas@0
   123
You may also call =TWiki::Func::registerTagHandler= here to register
colas@0
   124
a function to handle variables that have standard TWiki syntax - for example,
colas@0
   125
=%MYTAG{"my param" myarg="My Arg"}%. You can also override internal
colas@0
   126
TWiki variable handling functions this way, though this practice is unsupported
colas@0
   127
and highly dangerous!
colas@0
   128
colas@0
   129
__Note:__ Please align variables names with the Plugin name, e.g. if 
colas@0
   130
your Plugin is called FooBarPlugin, name variables FOOBAR and/or 
colas@0
   131
FOOBARSOMETHING. This avoids namespace issues.
colas@0
   132
colas@0
   133
colas@0
   134
=cut
colas@0
   135
colas@0
   136
sub initPlugin {
colas@0
   137
    my( $topic, $web, $user, $installWeb ) = @_;
colas@0
   138
colas@0
   139
    # check for Plugins.pm versions
colas@0
   140
    if( $TWiki::Plugins::VERSION < 1.026 ) {
colas@0
   141
        TWiki::Func::writeWarning( "Version mismatch between $pluginName and Plugins.pm" );
colas@0
   142
        return 0;
colas@0
   143
    }
colas@0
   144
colas@0
   145
    # Example code of how to get a preference value, register a variable handler
colas@0
   146
    # and register a RESTHandler. (remove code you do not need)
colas@0
   147
colas@0
   148
    # Set plugin preferences in LocalSite.cfg, like this:
colas@0
   149
    # $TWiki::cfg{Plugins}{EmptyPlugin}{ExampleSetting} = 1;
colas@0
   150
    # Always provide a default in case the setting is not defined in
colas@0
   151
    # LocalSite.cfg. See TWiki.TWikiPlugins for help in adding your plugin
colas@0
   152
    # configuration to the =configure= interface.
colas@0
   153
    my $setting = $TWiki::cfg{Plugins}{EmptyPlugin}{ExampleSetting} || 0;
colas@0
   154
    $debug = $TWiki::cfg{Plugins}{EmptyPlugin}{Debug} || 0;
colas@0
   155
colas@0
   156
    # register the _EXAMPLETAG function to handle %EXAMPLETAG{...}%
colas@0
   157
    # This will be called whenever %EXAMPLETAG% or %EXAMPLETAG{...}% is
colas@0
   158
    # seen in the topic text.
colas@0
   159
    TWiki::Func::registerTagHandler( 'EXAMPLETAG', \&_EXAMPLETAG );
colas@0
   160
colas@0
   161
    # Allow a sub to be called from the REST interface 
colas@0
   162
    # using the provided alias
colas@0
   163
    TWiki::Func::registerRESTHandler('example', \&restExample);
colas@0
   164
colas@0
   165
    # Plugin correctly initialized
colas@0
   166
    return 1;
colas@0
   167
}
colas@0
   168
colas@0
   169
# The function used to handle the %EXAMPLETAG{...}% variable
colas@0
   170
# You would have one of these for each variable you want to process.
colas@0
   171
sub _EXAMPLETAG {
colas@0
   172
    my($session, $params, $theTopic, $theWeb) = @_;
colas@0
   173
    # $session  - a reference to the TWiki session object (if you don't know
colas@0
   174
    #             what this is, just ignore it)
colas@0
   175
    # $params=  - a reference to a TWiki::Attrs object containing parameters.
colas@0
   176
    #             This can be used as a simple hash that maps parameter names
colas@0
   177
    #             to values, with _DEFAULT being the name for the default
colas@0
   178
    #             parameter.
colas@0
   179
    # $theTopic - name of the topic in the query
colas@0
   180
    # $theWeb   - name of the web in the query
colas@0
   181
    # Return: the result of processing the variable
colas@0
   182
colas@0
   183
    # For example, %EXAMPLETAG{'hamburger' sideorder="onions"}%
colas@0
   184
    # $params->{_DEFAULT} will be 'hamburger'
colas@0
   185
    # $params->{sideorder} will be 'onions'
colas@0
   186
}
colas@0
   187
colas@0
   188
=pod
colas@0
   189
colas@0
   190
---++ earlyInitPlugin()
colas@0
   191
colas@0
   192
This handler is called before any other handler, and before it has been
colas@0
   193
determined if the plugin is enabled or not. Use it with great care!
colas@0
   194
colas@0
   195
If it returns a non-null error string, the plugin will be disabled.
colas@0
   196
colas@0
   197
=cut
colas@0
   198
colas@0
   199
sub DISABLE_earlyInitPlugin {
colas@0
   200
    return undef;
colas@0
   201
}
colas@0
   202
colas@0
   203
=pod
colas@0
   204
colas@0
   205
---++ initializeUserHandler( $loginName, $url, $pathInfo )
colas@0
   206
   * =$loginName= - login name recovered from $ENV{REMOTE_USER}
colas@0
   207
   * =$url= - request url
colas@0
   208
   * =$pathInfo= - pathinfo from the CGI query
colas@0
   209
Allows a plugin to set the username. Normally TWiki gets the username
colas@0
   210
from the login manager. This handler gives you a chance to override the
colas@0
   211
login manager.
colas@0
   212
colas@0
   213
Return the *login* name.
colas@0
   214
colas@0
   215
This handler is called very early, immediately after =earlyInitPlugin=.
colas@0
   216
colas@0
   217
*Since:* TWiki::Plugins::VERSION = '1.010'
colas@0
   218
colas@0
   219
=cut
colas@0
   220
colas@0
   221
sub DISABLE_initializeUserHandler {
colas@0
   222
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   223
    ### my ( $loginName, $url, $pathInfo ) = @_;
colas@0
   224
colas@0
   225
    TWiki::Func::writeDebug( "- ${pluginName}::initializeUserHandler( $_[0], $_[1] )" ) if $debug;
colas@0
   226
}
colas@0
   227
colas@0
   228
=pod
colas@0
   229
colas@0
   230
---++ registrationHandler($web, $wikiName, $loginName )
colas@0
   231
   * =$web= - the name of the web in the current CGI query
colas@0
   232
   * =$wikiName= - users wiki name
colas@0
   233
   * =$loginName= - users login name
colas@0
   234
colas@0
   235
Called when a new user registers with this TWiki.
colas@0
   236
colas@0
   237
*Since:* TWiki::Plugins::VERSION = '1.010'
colas@0
   238
colas@0
   239
=cut
colas@0
   240
colas@0
   241
sub DISABLE_registrationHandler {
colas@0
   242
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   243
    ### my ( $web, $wikiName, $loginName ) = @_;
colas@0
   244
colas@0
   245
    TWiki::Func::writeDebug( "- ${pluginName}::registrationHandler( $_[0], $_[1] )" ) if $debug;
colas@0
   246
}
colas@0
   247
colas@0
   248
=pod
colas@0
   249
colas@0
   250
---++ commonTagsHandler($text, $topic, $web, $included, $meta )
colas@0
   251
   * =$text= - text to be processed
colas@0
   252
   * =$topic= - the name of the topic in the current CGI query
colas@0
   253
   * =$web= - the name of the web in the current CGI query
colas@0
   254
   * =$included= - Boolean flag indicating whether the handler is invoked on an included topic
colas@0
   255
   * =$meta= - meta-data object for the topic MAY BE =undef=
colas@0
   256
This handler is called by the code that expands %<nop>TAGS% syntax in
colas@0
   257
the topic body and in form fields. It may be called many times while
colas@0
   258
a topic is being rendered.
colas@0
   259
colas@0
   260
For variables with trivial syntax it is far more efficient to use
colas@0
   261
=TWiki::Func::registerTagHandler= (see =initPlugin=).
colas@0
   262
colas@0
   263
Plugins that have to parse the entire topic content should implement
colas@0
   264
this function. Internal TWiki
colas@0
   265
variables (and any variables declared using =TWiki::Func::registerTagHandler=)
colas@0
   266
are expanded _before_, and then again _after_, this function is called
colas@0
   267
to ensure all %<nop>TAGS% are expanded.
colas@0
   268
colas@0
   269
__NOTE:__ when this handler is called, &lt;verbatim> blocks have been
colas@0
   270
removed from the text (though all other blocks such as &lt;pre> and
colas@0
   271
&lt;noautolink> are still present).
colas@0
   272
colas@0
   273
__NOTE:__ meta-data is _not_ embedded in the text passed to this
colas@0
   274
handler. Use the =$meta= object.
colas@0
   275
colas@0
   276
*Since:* $TWiki::Plugins::VERSION 1.000
colas@0
   277
colas@0
   278
=cut
colas@0
   279
colas@0
   280
sub DISABLE_commonTagsHandler {
colas@0
   281
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   282
    ### my ( $text, $topic, $web, $meta ) = @_;
colas@0
   283
colas@0
   284
    TWiki::Func::writeDebug( "- ${pluginName}::commonTagsHandler( $_[2].$_[1] )" ) if $debug;
colas@0
   285
colas@0
   286
    # do custom extension rule, like for example:
colas@0
   287
    # $_[0] =~ s/%XYZ%/&handleXyz()/ge;
colas@0
   288
    # $_[0] =~ s/%XYZ{(.*?)}%/&handleXyz($1)/ge;
colas@0
   289
}
colas@0
   290
colas@0
   291
=pod
colas@0
   292
colas@0
   293
---++ beforeCommonTagsHandler($text, $topic, $web, $meta )
colas@0
   294
   * =$text= - text to be processed
colas@0
   295
   * =$topic= - the name of the topic in the current CGI query
colas@0
   296
   * =$web= - the name of the web in the current CGI query
colas@0
   297
   * =$meta= - meta-data object for the topic MAY BE =undef=
colas@0
   298
This handler is called before TWiki does any expansion of it's own
colas@0
   299
internal variables. It is designed for use by cache plugins. Note that
colas@0
   300
when this handler is called, &lt;verbatim> blocks are still present
colas@0
   301
in the text.
colas@0
   302
colas@0
   303
__NOTE__: This handler is called once for each call to
colas@0
   304
=commonTagsHandler= i.e. it may be called many times during the
colas@0
   305
rendering of a topic.
colas@0
   306
colas@0
   307
__NOTE:__ meta-data is _not_ embedded in the text passed to this
colas@0
   308
handler.
colas@0
   309
colas@0
   310
__NOTE:__ This handler is not separately called on included topics.
colas@0
   311
colas@0
   312
=cut
colas@0
   313
colas@0
   314
sub DISABLE_beforeCommonTagsHandler {
colas@0
   315
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   316
    ### my ( $text, $topic, $web, $meta ) = @_;
colas@0
   317
colas@0
   318
    TWiki::Func::writeDebug( "- ${pluginName}::beforeCommonTagsHandler( $_[2].$_[1] )" ) if $debug;
colas@0
   319
}
colas@0
   320
colas@0
   321
=pod
colas@0
   322
colas@0
   323
---++ afterCommonTagsHandler($text, $topic, $web, $meta )
colas@0
   324
   * =$text= - text to be processed
colas@0
   325
   * =$topic= - the name of the topic in the current CGI query
colas@0
   326
   * =$web= - the name of the web in the current CGI query
colas@0
   327
   * =$meta= - meta-data object for the topic MAY BE =undef=
colas@0
   328
This handler is after TWiki has completed expansion of %TAGS%.
colas@0
   329
It is designed for use by cache plugins. Note that when this handler
colas@0
   330
is called, &lt;verbatim> blocks are present in the text.
colas@0
   331
colas@0
   332
__NOTE__: This handler is called once for each call to
colas@0
   333
=commonTagsHandler= i.e. it may be called many times during the
colas@0
   334
rendering of a topic.
colas@0
   335
colas@0
   336
__NOTE:__ meta-data is _not_ embedded in the text passed to this
colas@0
   337
handler.
colas@0
   338
colas@0
   339
=cut
colas@0
   340
colas@0
   341
sub DISABLE_afterCommonTagsHandler {
colas@0
   342
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   343
    ### my ( $text, $topic, $web, $meta ) = @_;
colas@0
   344
colas@0
   345
    TWiki::Func::writeDebug( "- ${pluginName}::afterCommonTagsHandler( $_[2].$_[1] )" ) if $debug;
colas@0
   346
}
colas@0
   347
colas@0
   348
=pod
colas@0
   349
colas@0
   350
---++ preRenderingHandler( $text, \%map )
colas@0
   351
   * =$text= - text, with the head, verbatim and pre blocks replaced with placeholders
colas@0
   352
   * =\%removed= - reference to a hash that maps the placeholders to the removed blocks.
colas@0
   353
colas@0
   354
Handler called immediately before TWiki syntax structures (such as lists) are
colas@0
   355
processed, but after all variables have been expanded. Use this handler to 
colas@0
   356
process special syntax only recognised by your plugin.
colas@0
   357
colas@0
   358
Placeholders are text strings constructed using the tag name and a 
colas@0
   359
sequence number e.g. 'pre1', "verbatim6", "head1" etc. Placeholders are 
colas@0
   360
inserted into the text inside &lt;!--!marker!--&gt; characters so the 
colas@0
   361
text will contain &lt;!--!pre1!--&gt; for placeholder pre1.
colas@0
   362
colas@0
   363
Each removed block is represented by the block text and the parameters 
colas@0
   364
passed to the tag (usually empty) e.g. for
colas@0
   365
<verbatim>
colas@0
   366
<pre class='slobadob'>
colas@0
   367
XYZ
colas@0
   368
</pre>
colas@0
   369
the map will contain:
colas@0
   370
<pre>
colas@0
   371
$removed->{'pre1'}{text}:   XYZ
colas@0
   372
$removed->{'pre1'}{params}: class="slobadob"
colas@0
   373
</pre>
colas@0
   374
Iterating over blocks for a single tag is easy. For example, to prepend a 
colas@0
   375
line number to every line of every pre block you might use this code:
colas@0
   376
<verbatim>
colas@0
   377
foreach my $placeholder ( keys %$map ) {
colas@0
   378
    if( $placeholder =~ /^pre/i ) {
colas@0
   379
       my $n = 1;
colas@0
   380
       $map->{$placeholder}{text} =~ s/^/$n++/gem;
colas@0
   381
    }
colas@0
   382
}
colas@0
   383
</verbatim>
colas@0
   384
colas@0
   385
__NOTE__: This handler is called once for each rendered block of text i.e. 
colas@0
   386
it may be called several times during the rendering of a topic.
colas@0
   387
colas@0
   388
__NOTE:__ meta-data is _not_ embedded in the text passed to this
colas@0
   389
handler.
colas@0
   390
colas@0
   391
Since TWiki::Plugins::VERSION = '1.026'
colas@0
   392
colas@0
   393
=cut
colas@0
   394
colas@0
   395
sub DISABLE_preRenderingHandler {
colas@0
   396
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   397
    #my( $text, $pMap ) = @_;
colas@0
   398
}
colas@0
   399
colas@0
   400
=pod
colas@0
   401
colas@0
   402
---++ postRenderingHandler( $text )
colas@0
   403
   * =$text= - the text that has just been rendered. May be modified in place.
colas@0
   404
colas@0
   405
__NOTE__: This handler is called once for each rendered block of text i.e. 
colas@0
   406
it may be called several times during the rendering of a topic.
colas@0
   407
colas@0
   408
__NOTE:__ meta-data is _not_ embedded in the text passed to this
colas@0
   409
handler.
colas@0
   410
colas@0
   411
Since TWiki::Plugins::VERSION = '1.026'
colas@0
   412
colas@0
   413
=cut
colas@0
   414
colas@0
   415
sub DISABLE_postRenderingHandler {
colas@0
   416
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   417
    #my $text = shift;
colas@0
   418
}
colas@0
   419
colas@0
   420
=pod
colas@0
   421
colas@0
   422
---++ beforeEditHandler($text, $topic, $web )
colas@0
   423
   * =$text= - text that will be edited
colas@0
   424
   * =$topic= - the name of the topic in the current CGI query
colas@0
   425
   * =$web= - the name of the web in the current CGI query
colas@0
   426
This handler is called by the edit script just before presenting the edit text
colas@0
   427
in the edit box. It is called once when the =edit= script is run.
colas@0
   428
colas@0
   429
__NOTE__: meta-data may be embedded in the text passed to this handler 
colas@0
   430
(using %META: tags)
colas@0
   431
colas@0
   432
*Since:* TWiki::Plugins::VERSION = '1.010'
colas@0
   433
colas@0
   434
=cut
colas@0
   435
colas@0
   436
sub DISABLE_beforeEditHandler {
colas@0
   437
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   438
    ### my ( $text, $topic, $web ) = @_;
colas@0
   439
colas@0
   440
    TWiki::Func::writeDebug( "- ${pluginName}::beforeEditHandler( $_[2].$_[1] )" ) if $debug;
colas@0
   441
}
colas@0
   442
colas@0
   443
=pod
colas@0
   444
colas@0
   445
---++ afterEditHandler($text, $topic, $web, $meta )
colas@0
   446
   * =$text= - text that is being previewed
colas@0
   447
   * =$topic= - the name of the topic in the current CGI query
colas@0
   448
   * =$web= - the name of the web in the current CGI query
colas@0
   449
   * =$meta= - meta-data for the topic.
colas@0
   450
This handler is called by the preview script just before presenting the text.
colas@0
   451
It is called once when the =preview= script is run.
colas@0
   452
colas@0
   453
__NOTE:__ this handler is _not_ called unless the text is previewed.
colas@0
   454
colas@0
   455
__NOTE:__ meta-data is _not_ embedded in the text passed to this
colas@0
   456
handler. Use the =$meta= object.
colas@0
   457
colas@0
   458
*Since:* $TWiki::Plugins::VERSION 1.010
colas@0
   459
colas@0
   460
=cut
colas@0
   461
colas@0
   462
sub DISABLE_afterEditHandler {
colas@0
   463
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   464
    ### my ( $text, $topic, $web ) = @_;
colas@0
   465
colas@0
   466
    TWiki::Func::writeDebug( "- ${pluginName}::afterEditHandler( $_[2].$_[1] )" ) if $debug;
colas@0
   467
}
colas@0
   468
colas@0
   469
=pod
colas@0
   470
colas@0
   471
---++ beforeSaveHandler($text, $topic, $web, $meta )
colas@0
   472
   * =$text= - text _with embedded meta-data tags_
colas@0
   473
   * =$topic= - the name of the topic in the current CGI query
colas@0
   474
   * =$web= - the name of the web in the current CGI query
colas@0
   475
   * =$meta= - the metadata of the topic being saved, represented by a TWiki::Meta object.
colas@0
   476
colas@0
   477
This handler is called each time a topic is saved.
colas@0
   478
colas@0
   479
__NOTE:__ meta-data is embedded in =$text= (using %META: tags). If you modify
colas@0
   480
the =$meta= object, then it will override any changes to the meta-data
colas@0
   481
embedded in the text. Modify *either* the META in the text *or* the =$meta=
colas@0
   482
object, never both. You are recommended to modify the =$meta= object rather
colas@0
   483
than the text, as this approach is proof against changes in the embedded
colas@0
   484
text format.
colas@0
   485
colas@0
   486
*Since:* TWiki::Plugins::VERSION = '1.010'
colas@0
   487
colas@0
   488
=cut
colas@0
   489
colas@0
   490
sub DISABLE_beforeSaveHandler {
colas@0
   491
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   492
    ### my ( $text, $topic, $web ) = @_;
colas@0
   493
colas@0
   494
    TWiki::Func::writeDebug( "- ${pluginName}::beforeSaveHandler( $_[2].$_[1] )" ) if $debug;
colas@0
   495
}
colas@0
   496
colas@0
   497
=pod
colas@0
   498
colas@0
   499
---++ afterSaveHandler($text, $topic, $web, $error, $meta )
colas@0
   500
   * =$text= - the text of the topic _excluding meta-data tags_
colas@0
   501
     (see beforeSaveHandler)
colas@0
   502
   * =$topic= - the name of the topic in the current CGI query
colas@0
   503
   * =$web= - the name of the web in the current CGI query
colas@0
   504
   * =$error= - any error string returned by the save.
colas@0
   505
   * =$meta= - the metadata of the saved topic, represented by a TWiki::Meta object 
colas@0
   506
colas@0
   507
This handler is called each time a topic is saved.
colas@0
   508
colas@0
   509
__NOTE:__ meta-data is embedded in $text (using %META: tags)
colas@0
   510
colas@0
   511
*Since:* TWiki::Plugins::VERSION 1.025
colas@0
   512
colas@0
   513
=cut
colas@0
   514
colas@0
   515
sub DISABLE_afterSaveHandler {
colas@0
   516
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   517
    ### my ( $text, $topic, $web, $error, $meta ) = @_;
colas@0
   518
colas@0
   519
    TWiki::Func::writeDebug( "- ${pluginName}::afterSaveHandler( $_[2].$_[1] )" ) if $debug;
colas@0
   520
}
colas@0
   521
colas@0
   522
=pod
colas@0
   523
colas@0
   524
---++ afterRenameHandler( $oldWeb, $oldTopic, $oldAttachment, $newWeb, $newTopic, $newAttachment )
colas@0
   525
colas@0
   526
   * =$oldWeb= - name of old web
colas@0
   527
   * =$oldTopic= - name of old topic (empty string if web rename)
colas@0
   528
   * =$oldAttachment= - name of old attachment (empty string if web or topic rename)
colas@0
   529
   * =$newWeb= - name of new web
colas@0
   530
   * =$newTopic= - name of new topic (empty string if web rename)
colas@0
   531
   * =$newAttachment= - name of new attachment (empty string if web or topic rename)
colas@0
   532
colas@0
   533
This handler is called just after the rename/move/delete action of a web, topic or attachment.
colas@0
   534
colas@0
   535
*Since:* TWiki::Plugins::VERSION = '1.11'
colas@0
   536
colas@0
   537
=cut
colas@0
   538
colas@0
   539
sub DISABLE_afterRenameHandler {
colas@0
   540
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   541
    ### my ( $oldWeb, $oldTopic, $oldAttachment, $newWeb, $newTopic, $newAttachment ) = @_;
colas@0
   542
colas@0
   543
    TWiki::Func::writeDebug( "- ${pluginName}::afterRenameHandler( " .
colas@0
   544
                             "$_[0].$_[1] $_[2] -> $_[3].$_[4] $_[5] )" ) if $debug;
colas@0
   545
}
colas@0
   546
colas@0
   547
=pod
colas@0
   548
colas@0
   549
---++ beforeAttachmentSaveHandler(\%attrHash, $topic, $web )
colas@0
   550
   * =\%attrHash= - reference to hash of attachment attribute values
colas@0
   551
   * =$topic= - the name of the topic in the current CGI query
colas@0
   552
   * =$web= - the name of the web in the current CGI query
colas@0
   553
This handler is called once when an attachment is uploaded. When this
colas@0
   554
handler is called, the attachment has *not* been recorded in the database.
colas@0
   555
colas@0
   556
The attributes hash will include at least the following attributes:
colas@0
   557
   * =attachment= => the attachment name
colas@0
   558
   * =comment= - the comment
colas@0
   559
   * =user= - the user id
colas@0
   560
   * =tmpFilename= - name of a temporary file containing the attachment data
colas@0
   561
colas@0
   562
*Since:* TWiki::Plugins::VERSION = 1.025
colas@0
   563
colas@0
   564
=cut
colas@0
   565
colas@0
   566
sub DISABLE_beforeAttachmentSaveHandler {
colas@0
   567
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   568
    ###   my( $attrHashRef, $topic, $web ) = @_;
colas@0
   569
    TWiki::Func::writeDebug( "- ${pluginName}::beforeAttachmentSaveHandler( $_[2].$_[1] )" ) if $debug;
colas@0
   570
}
colas@0
   571
colas@0
   572
=pod
colas@0
   573
colas@0
   574
---++ afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error )
colas@0
   575
   * =\%attrHash= - reference to hash of attachment attribute values
colas@0
   576
   * =$topic= - the name of the topic in the current CGI query
colas@0
   577
   * =$web= - the name of the web in the current CGI query
colas@0
   578
   * =$error= - any error string generated during the save process
colas@0
   579
This handler is called just after the save action. The attributes hash
colas@0
   580
will include at least the following attributes:
colas@0
   581
   * =attachment= => the attachment name
colas@0
   582
   * =comment= - the comment
colas@0
   583
   * =user= - the user id
colas@0
   584
colas@0
   585
*Since:* TWiki::Plugins::VERSION = 1.025
colas@0
   586
colas@0
   587
=cut
colas@0
   588
colas@0
   589
sub DISABLE_afterAttachmentSaveHandler {
colas@0
   590
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   591
    ###   my( $attrHashRef, $topic, $web ) = @_;
colas@0
   592
    TWiki::Func::writeDebug( "- ${pluginName}::afterAttachmentSaveHandler( $_[2].$_[1] )" ) if $debug;
colas@0
   593
}
colas@0
   594
colas@0
   595
=begin twiki
colas@0
   596
colas@0
   597
---++ beforeMergeHandler( $text, $currRev, $currText, $origRev, $origText, $web, $topic )
colas@0
   598
   * =$text= - the new text of the topic
colas@0
   599
   * =$currRev= - the number of the most recent rev of the topic in the store
colas@0
   600
   * =$currText= - the text of that rev
colas@0
   601
   * =$origRev= - the number of the rev that the edit started on (or undef
colas@0
   602
     if that revision was overwritten by a replace-revision save)
colas@0
   603
   * =$origText= - the text of that revision (or undef)
colas@0
   604
   * =$web= - the name of the web for the topic being saved
colas@0
   605
   * =$topic= - the name of the topic
colas@0
   606
This handler is called immediately before a merge of a topic that was edited
colas@0
   607
simultaneously by two users. It is called once on the topic text from
colas@0
   608
the =save= script. See =mergeHandler= for handling individual changes in the
colas@0
   609
topic text (and in forms).
colas@0
   610
colas@0
   611
=cut
colas@0
   612
colas@0
   613
sub DISABLE_beforeMergeHandler {
colas@0
   614
    # do not uncomment, use $_[0], $_[1]... instead
colas@0
   615
    #my( $text, $currRev, $currText, $origRev, $origText, $web, $topic ) = @_;
colas@0
   616
}
colas@0
   617
colas@0
   618
=pod
colas@0
   619
colas@0
   620
---++ mergeHandler( $diff, $old, $new, \%info ) -> $text
colas@0
   621
Try to resolve a difference encountered during merge. The =differences= 
colas@0
   622
array is an array of hash references, where each hash contains the 
colas@0
   623
following fields:
colas@0
   624
   * =$diff= => one of the characters '+', '-', 'c' or ' '.
colas@0
   625
      * '+' - =new= contains text inserted in the new version
colas@0
   626
      * '-' - =old= contains text deleted from the old version
colas@0
   627
      * 'c' - =old= contains text from the old version, and =new= text
colas@0
   628
        from the version being saved
colas@0
   629
      * ' ' - =new= contains text common to both versions, or the change
colas@0
   630
        only involved whitespace
colas@0
   631
   * =$old= => text from version currently saved
colas@0
   632
   * =$new= => text from version being saved
colas@0
   633
   * =\%info= is a reference to the form field description { name, title,
colas@0
   634
     type, size, value, tooltip, attributes, referenced }. It must _not_
colas@0
   635
     be wrtten to. This parameter will be undef when merging the body
colas@0
   636
     text of the topic.
colas@0
   637
colas@0
   638
Plugins should try to resolve differences and return the merged text. 
colas@0
   639
For example, a radio button field where we have 
colas@0
   640
={ diff=>'c', old=>'Leafy', new=>'Barky' }= might be resolved as 
colas@0
   641
='Treelike'=. If the plugin cannot resolve a difference it should return 
colas@0
   642
undef.
colas@0
   643
colas@0
   644
The merge handler will be called several times during a save; once for 
colas@0
   645
each difference that needs resolution.
colas@0
   646
colas@0
   647
If any merges are left unresolved after all plugins have been given a 
colas@0
   648
chance to intercede, the following algorithm is used to decide how to 
colas@0
   649
merge the data:
colas@0
   650
   1 =new= is taken for all =radio=, =checkbox= and =select= fields to 
colas@0
   651
     resolve 'c' conflicts
colas@0
   652
   1 '+' and '-' text is always included in the the body text and text
colas@0
   653
     fields
colas@0
   654
   1 =&lt;del>conflict&lt;/del> &lt;ins>markers&lt;/ins>= are used to 
colas@0
   655
     mark 'c' merges in text fields
colas@0
   656
colas@0
   657
The merge handler is called whenever a topic is saved, and a merge is 
colas@0
   658
required to resolve concurrent edits on a topic.
colas@0
   659
colas@0
   660
*Since:* TWiki::Plugins::VERSION = 1.1
colas@0
   661
colas@0
   662
=cut
colas@0
   663
colas@0
   664
sub DISABLE_mergeHandler {
colas@0
   665
}
colas@0
   666
colas@0
   667
=pod
colas@0
   668
colas@0
   669
---++ modifyHeaderHandler( \%headers, $query )
colas@0
   670
   * =\%headers= - reference to a hash of existing header values
colas@0
   671
   * =$query= - reference to CGI query object
colas@0
   672
Lets the plugin modify the HTTP headers that will be emitted when a
colas@0
   673
page is written to the browser. \%headers= will contain the headers
colas@0
   674
proposed by the core, plus any modifications made by other plugins that also
colas@0
   675
implement this method that come earlier in the plugins list.
colas@0
   676
<verbatim>
colas@0
   677
$headers->{expires} = '+1h';
colas@0
   678
</verbatim>
colas@0
   679
colas@0
   680
Note that this is the HTTP header which is _not_ the same as the HTML
colas@0
   681
&lt;HEAD&gt; tag. The contents of the &lt;HEAD&gt; tag may be manipulated
colas@0
   682
using the =TWiki::Func::addToHEAD= method.
colas@0
   683
colas@0
   684
*Since:* TWiki::Plugins::VERSION 1.1
colas@0
   685
colas@0
   686
=cut
colas@0
   687
colas@0
   688
sub DISABLE_modifyHeaderHandler {
colas@0
   689
    my ( $headers, $query ) = @_;
colas@0
   690
colas@0
   691
    TWiki::Func::writeDebug( "- ${pluginName}::modifyHeaderHandler()" ) if $debug;
colas@0
   692
}
colas@0
   693
colas@0
   694
=pod
colas@0
   695
colas@0
   696
---++ redirectCgiQueryHandler($query, $url )
colas@0
   697
   * =$query= - the CGI query
colas@0
   698
   * =$url= - the URL to redirect to
colas@0
   699
colas@0
   700
This handler can be used to replace TWiki's internal redirect function.
colas@0
   701
colas@0
   702
If this handler is defined in more than one plugin, only the handler
colas@0
   703
in the earliest plugin in the INSTALLEDPLUGINS list will be called. All
colas@0
   704
the others will be ignored.
colas@0
   705
colas@0
   706
*Since:* TWiki::Plugins::VERSION 1.010
colas@0
   707
colas@0
   708
=cut
colas@0
   709
colas@0
   710
sub DISABLE_redirectCgiQueryHandler {
colas@0
   711
    # do not uncomment, use $_[0], $_[1] instead
colas@0
   712
    ### my ( $query, $url ) = @_;
colas@0
   713
colas@0
   714
    TWiki::Func::writeDebug( "- ${pluginName}::redirectCgiQueryHandler( query, $_[1] )" ) if $debug;
colas@0
   715
}
colas@0
   716
colas@0
   717
=pod
colas@0
   718
colas@0
   719
---++ renderFormFieldForEditHandler($name, $type, $size, $value, $attributes, $possibleValues) -> $html
colas@0
   720
colas@0
   721
This handler is called before built-in types are considered. It generates 
colas@0
   722
the HTML text rendering this form field, or false, if the rendering 
colas@0
   723
should be done by the built-in type handlers.
colas@0
   724
   * =$name= - name of form field
colas@0
   725
   * =$type= - type of form field (checkbox, radio etc)
colas@0
   726
   * =$size= - size of form field
colas@0
   727
   * =$value= - value held in the form field
colas@0
   728
   * =$attributes= - attributes of form field 
colas@0
   729
   * =$possibleValues= - the values defined as options for form field, if
colas@0
   730
     any. May be a scalar (one legal value) or a ref to an array
colas@0
   731
     (several legal values)
colas@0
   732
colas@0
   733
Return HTML text that renders this field. If false, form rendering
colas@0
   734
continues by considering the built-in types.
colas@0
   735
colas@0
   736
*Since:* TWiki::Plugins::VERSION 1.1
colas@0
   737
colas@0
   738
Note that since TWiki-4.2, you can also extend the range of available
colas@0
   739
types by providing a subclass of =TWiki::Form::FieldDefinition= to implement
colas@0
   740
the new type (see =TWiki::Plugins.JSCalendarContrib= and
colas@0
   741
=TWiki::Plugins.RatingContrib= for examples). This is the preferred way to
colas@0
   742
extend the form field types, but does not work for TWiki < 4.2.
colas@0
   743
colas@0
   744
=cut
colas@0
   745
colas@0
   746
sub DISABLE_renderFormFieldForEditHandler {
colas@0
   747
}
colas@0
   748
colas@0
   749
=pod
colas@0
   750
colas@0
   751
---++ renderWikiWordHandler($linkText, $hasExplicitLinkLabel, $web, $topic) -> $linkText
colas@0
   752
   * =$linkText= - the text for the link i.e. for =[<nop>[Link][blah blah]]=
colas@0
   753
     it's =blah blah=, for =BlahBlah= it's =BlahBlah=, and for [[Blah Blah]] it's =Blah Blah=.
colas@0
   754
   * =$hasExplicitLinkLabel= - true if the link is of the form =[<nop>[Link][blah blah]]= (false if it's ==<nop>[Blah]] or =BlahBlah=)
colas@0
   755
   * =$web=, =$topic= - specify the topic being rendered (only since TWiki 4.2)
colas@0
   756
colas@0
   757
Called during rendering, this handler allows the plugin a chance to change
colas@0
   758
the rendering of labels used for links.
colas@0
   759
colas@0
   760
Return the new link text.
colas@0
   761
colas@0
   762
*Since:* TWiki::Plugins::VERSION 1.1
colas@0
   763
colas@0
   764
=cut
colas@0
   765
colas@0
   766
sub DISABLE_renderWikiWordHandler {
colas@0
   767
    my( $linkText, $hasExplicitLinkLabel, $web, $topic ) = @_;
colas@0
   768
    return $linkText;
colas@0
   769
}
colas@0
   770
colas@0
   771
=pod
colas@0
   772
colas@0
   773
---++ completePageHandler($html, $httpHeaders)
colas@0
   774
colas@0
   775
This handler is called on the ingredients of every page that is
colas@0
   776
output by the standard TWiki scripts. It is designed primarily for use by
colas@0
   777
cache and security plugins.
colas@0
   778
   * =$html= - the body of the page (normally &lt;html>..$lt;/html>)
colas@0
   779
   * =$httpHeaders= - the HTTP headers. Note that the headers do not contain
colas@0
   780
     a =Content-length=. That will be computed and added immediately before
colas@0
   781
     the page is actually written. This is a string, which must end in \n\n.
colas@0
   782
colas@0
   783
*Since:* TWiki::Plugins::VERSION 1.2
colas@0
   784
colas@0
   785
=cut
colas@0
   786
colas@0
   787
sub DISABLE_completePageHandler {
colas@0
   788
    #my($html, $httpHeaders) = @_;
colas@0
   789
    # modify $_[0] or $_[1] if you must change the HTML or headers
colas@0
   790
}
colas@0
   791
colas@0
   792
=pod
colas@0
   793
colas@0
   794
---++ restExample($session) -> $text
colas@0
   795
colas@0
   796
This is an example of a sub to be called by the =rest= script. The parameter is:
colas@0
   797
   * =$session= - The TWiki object associated to this session.
colas@0
   798
colas@0
   799
Additional parameters can be recovered via de query object in the $session.
colas@0
   800
colas@0
   801
For more information, check TWiki:TWiki.TWikiScripts#rest
colas@0
   802
colas@0
   803
*Since:* TWiki::Plugins::VERSION 1.1
colas@0
   804
colas@0
   805
=cut
colas@0
   806
colas@0
   807
sub restExample {
colas@0
   808
   #my ($session) = @_;
colas@0
   809
   return "This is an example of a REST invocation\n\n";
colas@0
   810
}
colas@0
   811
colas@0
   812
1;