lib/TWiki/Plugins/EmptyPlugin.pm
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/lib/TWiki/Plugins/EmptyPlugin.pm	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,812 @@
     1.4 +# Plugin for TWiki Enterprise Collaboration Platform, http://TWiki.org/
     1.5 +#
     1.6 +# Copyright (C) 2000-2003 Andrea Sterbini, a.sterbini@flashnet.it
     1.7 +# Copyright (C) 2001-2006 Peter Thoeny, peter@thoeny.org
     1.8 +# and TWiki Contributors. All Rights Reserved. TWiki Contributors
     1.9 +# are listed in the AUTHORS file in the root of this distribution.
    1.10 +# NOTE: Please extend that file, not this notice.
    1.11 +#
    1.12 +# This program is free software; you can redistribute it and/or
    1.13 +# modify it under the terms of the GNU General Public License
    1.14 +# as published by the Free Software Foundation; either version 2
    1.15 +# of the License, or (at your option) any later version. For
    1.16 +# more details read LICENSE in the root of this distribution.
    1.17 +#
    1.18 +# This program is distributed in the hope that it will be useful,
    1.19 +# but WITHOUT ANY WARRANTY; without even the implied warranty of
    1.20 +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    1.21 +#
    1.22 +# For licensing info read LICENSE file in the TWiki root.
    1.23 +
    1.24 +=pod
    1.25 +
    1.26 +---+ package EmptyPlugin
    1.27 +
    1.28 +This is an empty TWiki plugin. It is a fully defined plugin, but is
    1.29 +disabled by default in a TWiki installation. Use it as a template
    1.30 +for your own plugins; see TWiki.TWikiPlugins for details.
    1.31 +
    1.32 +This version of the !EmptyPlugin documents the handlers supported
    1.33 +by revision 1.2 of the Plugins API. See the documentation of =TWiki::Func=
    1.34 +for more information about what this revision number means, and how a
    1.35 +plugin can check it.
    1.36 +
    1.37 +__NOTE:__ To interact with TWiki use ONLY the official API functions
    1.38 +in the TWiki::Func module. Do not reference any functions or
    1.39 +variables elsewhere in TWiki, as these are subject to change
    1.40 +without prior warning, and your plugin may suddenly stop
    1.41 +working.
    1.42 +
    1.43 +For increased performance, all handlers except initPlugin are
    1.44 +disabled below. *To enable a handler* remove the leading DISABLE_ from
    1.45 +the function name. For efficiency and clarity, you should comment out or
    1.46 +delete the whole of handlers you don't use before you release your
    1.47 +plugin.
    1.48 +
    1.49 +__NOTE:__ When developing a plugin it is important to remember that
    1.50 +TWiki is tolerant of plugins that do not compile. In this case,
    1.51 +the failure will be silent but the plugin will not be available.
    1.52 +See %TWIKIWEB%.TWikiPlugins#FAILEDPLUGINS for error messages.
    1.53 +
    1.54 +__NOTE:__ Defining deprecated handlers will cause the handlers to be 
    1.55 +listed in %TWIKIWEB%.TWikiPlugins#FAILEDPLUGINS. See
    1.56 +%TWIKIWEB%.TWikiPlugins#Handlig_deprecated_functions
    1.57 +for information on regarding deprecated handlers that are defined for
    1.58 +compatibility with older TWiki versions.
    1.59 +
    1.60 +__NOTE:__ When writing handlers, keep in mind that these may be invoked
    1.61 +on included topics. For example, if a plugin generates links to the current
    1.62 +topic, these need to be generated before the afterCommonTagsHandler is run,
    1.63 +as at that point in the rendering loop we have lost the information that we
    1.64 +the text had been included from another topic.
    1.65 +
    1.66 +=cut
    1.67 +
    1.68 +# change the package name and $pluginName!!!
    1.69 +package TWiki::Plugins::EmptyPlugin;
    1.70 +
    1.71 +# Always use strict to enforce variable scoping
    1.72 +use strict;
    1.73 +
    1.74 +require TWiki::Func;    # The plugins API
    1.75 +require TWiki::Plugins; # For the API version
    1.76 +
    1.77 +# $VERSION is referred to by TWiki, and is the only global variable that
    1.78 +# *must* exist in this package.
    1.79 +use vars qw( $VERSION $RELEASE $SHORTDESCRIPTION $debug $pluginName $NO_PREFS_IN_TOPIC );
    1.80 +
    1.81 +# This should always be $Rev: 15942 (22 Jan 2008) $ so that TWiki can determine the checked-in
    1.82 +# status of the plugin. It is used by the build automation tools, so
    1.83 +# you should leave it alone.
    1.84 +$VERSION = '$Rev: 15942 (22 Jan 2008) $';
    1.85 +
    1.86 +# This is a free-form string you can use to "name" your own plugin version.
    1.87 +# It is *not* used by the build automation tools, but is reported as part
    1.88 +# of the version number in PLUGINDESCRIPTIONS.
    1.89 +$RELEASE = 'TWiki-4.2';
    1.90 +
    1.91 +# Short description of this plugin
    1.92 +# One line description, is shown in the %TWIKIWEB%.TextFormattingRules topic:
    1.93 +$SHORTDESCRIPTION = 'Empty Plugin used as a template for new Plugins';
    1.94 +
    1.95 +# You must set $NO_PREFS_IN_TOPIC to 0 if you want your plugin to use preferences
    1.96 +# stored in the plugin topic. This default is required for compatibility with
    1.97 +# older plugins, but imposes a significant performance penalty, and
    1.98 +# is not recommended. Instead, use $TWiki::cfg entries set in LocalSite.cfg, or
    1.99 +# if you want the users to be able to change settings, then use standard TWiki
   1.100 +# preferences that can be defined in your Main.TWikiPreferences and overridden
   1.101 +# at the web and topic level.
   1.102 +$NO_PREFS_IN_TOPIC = 1;
   1.103 +
   1.104 +# Name of this Plugin, only used in this module
   1.105 +$pluginName = 'EmptyPlugin';
   1.106 +
   1.107 +=pod
   1.108 +
   1.109 +---++ initPlugin($topic, $web, $user, $installWeb) -> $boolean
   1.110 +   * =$topic= - the name of the topic in the current CGI query
   1.111 +   * =$web= - the name of the web in the current CGI query
   1.112 +   * =$user= - the login name of the user
   1.113 +   * =$installWeb= - the name of the web the plugin is installed in
   1.114 +
   1.115 +REQUIRED
   1.116 +
   1.117 +Called to initialise the plugin. If everything is OK, should return
   1.118 +a non-zero value. On non-fatal failure, should write a message
   1.119 +using TWiki::Func::writeWarning and return 0. In this case
   1.120 +%FAILEDPLUGINS% will indicate which plugins failed.
   1.121 +
   1.122 +In the case of a catastrophic failure that will prevent the whole
   1.123 +installation from working safely, this handler may use 'die', which
   1.124 +will be trapped and reported in the browser.
   1.125 +
   1.126 +You may also call =TWiki::Func::registerTagHandler= here to register
   1.127 +a function to handle variables that have standard TWiki syntax - for example,
   1.128 +=%MYTAG{"my param" myarg="My Arg"}%. You can also override internal
   1.129 +TWiki variable handling functions this way, though this practice is unsupported
   1.130 +and highly dangerous!
   1.131 +
   1.132 +__Note:__ Please align variables names with the Plugin name, e.g. if 
   1.133 +your Plugin is called FooBarPlugin, name variables FOOBAR and/or 
   1.134 +FOOBARSOMETHING. This avoids namespace issues.
   1.135 +
   1.136 +
   1.137 +=cut
   1.138 +
   1.139 +sub initPlugin {
   1.140 +    my( $topic, $web, $user, $installWeb ) = @_;
   1.141 +
   1.142 +    # check for Plugins.pm versions
   1.143 +    if( $TWiki::Plugins::VERSION < 1.026 ) {
   1.144 +        TWiki::Func::writeWarning( "Version mismatch between $pluginName and Plugins.pm" );
   1.145 +        return 0;
   1.146 +    }
   1.147 +
   1.148 +    # Example code of how to get a preference value, register a variable handler
   1.149 +    # and register a RESTHandler. (remove code you do not need)
   1.150 +
   1.151 +    # Set plugin preferences in LocalSite.cfg, like this:
   1.152 +    # $TWiki::cfg{Plugins}{EmptyPlugin}{ExampleSetting} = 1;
   1.153 +    # Always provide a default in case the setting is not defined in
   1.154 +    # LocalSite.cfg. See TWiki.TWikiPlugins for help in adding your plugin
   1.155 +    # configuration to the =configure= interface.
   1.156 +    my $setting = $TWiki::cfg{Plugins}{EmptyPlugin}{ExampleSetting} || 0;
   1.157 +    $debug = $TWiki::cfg{Plugins}{EmptyPlugin}{Debug} || 0;
   1.158 +
   1.159 +    # register the _EXAMPLETAG function to handle %EXAMPLETAG{...}%
   1.160 +    # This will be called whenever %EXAMPLETAG% or %EXAMPLETAG{...}% is
   1.161 +    # seen in the topic text.
   1.162 +    TWiki::Func::registerTagHandler( 'EXAMPLETAG', \&_EXAMPLETAG );
   1.163 +
   1.164 +    # Allow a sub to be called from the REST interface 
   1.165 +    # using the provided alias
   1.166 +    TWiki::Func::registerRESTHandler('example', \&restExample);
   1.167 +
   1.168 +    # Plugin correctly initialized
   1.169 +    return 1;
   1.170 +}
   1.171 +
   1.172 +# The function used to handle the %EXAMPLETAG{...}% variable
   1.173 +# You would have one of these for each variable you want to process.
   1.174 +sub _EXAMPLETAG {
   1.175 +    my($session, $params, $theTopic, $theWeb) = @_;
   1.176 +    # $session  - a reference to the TWiki session object (if you don't know
   1.177 +    #             what this is, just ignore it)
   1.178 +    # $params=  - a reference to a TWiki::Attrs object containing parameters.
   1.179 +    #             This can be used as a simple hash that maps parameter names
   1.180 +    #             to values, with _DEFAULT being the name for the default
   1.181 +    #             parameter.
   1.182 +    # $theTopic - name of the topic in the query
   1.183 +    # $theWeb   - name of the web in the query
   1.184 +    # Return: the result of processing the variable
   1.185 +
   1.186 +    # For example, %EXAMPLETAG{'hamburger' sideorder="onions"}%
   1.187 +    # $params->{_DEFAULT} will be 'hamburger'
   1.188 +    # $params->{sideorder} will be 'onions'
   1.189 +}
   1.190 +
   1.191 +=pod
   1.192 +
   1.193 +---++ earlyInitPlugin()
   1.194 +
   1.195 +This handler is called before any other handler, and before it has been
   1.196 +determined if the plugin is enabled or not. Use it with great care!
   1.197 +
   1.198 +If it returns a non-null error string, the plugin will be disabled.
   1.199 +
   1.200 +=cut
   1.201 +
   1.202 +sub DISABLE_earlyInitPlugin {
   1.203 +    return undef;
   1.204 +}
   1.205 +
   1.206 +=pod
   1.207 +
   1.208 +---++ initializeUserHandler( $loginName, $url, $pathInfo )
   1.209 +   * =$loginName= - login name recovered from $ENV{REMOTE_USER}
   1.210 +   * =$url= - request url
   1.211 +   * =$pathInfo= - pathinfo from the CGI query
   1.212 +Allows a plugin to set the username. Normally TWiki gets the username
   1.213 +from the login manager. This handler gives you a chance to override the
   1.214 +login manager.
   1.215 +
   1.216 +Return the *login* name.
   1.217 +
   1.218 +This handler is called very early, immediately after =earlyInitPlugin=.
   1.219 +
   1.220 +*Since:* TWiki::Plugins::VERSION = '1.010'
   1.221 +
   1.222 +=cut
   1.223 +
   1.224 +sub DISABLE_initializeUserHandler {
   1.225 +    # do not uncomment, use $_[0], $_[1]... instead
   1.226 +    ### my ( $loginName, $url, $pathInfo ) = @_;
   1.227 +
   1.228 +    TWiki::Func::writeDebug( "- ${pluginName}::initializeUserHandler( $_[0], $_[1] )" ) if $debug;
   1.229 +}
   1.230 +
   1.231 +=pod
   1.232 +
   1.233 +---++ registrationHandler($web, $wikiName, $loginName )
   1.234 +   * =$web= - the name of the web in the current CGI query
   1.235 +   * =$wikiName= - users wiki name
   1.236 +   * =$loginName= - users login name
   1.237 +
   1.238 +Called when a new user registers with this TWiki.
   1.239 +
   1.240 +*Since:* TWiki::Plugins::VERSION = '1.010'
   1.241 +
   1.242 +=cut
   1.243 +
   1.244 +sub DISABLE_registrationHandler {
   1.245 +    # do not uncomment, use $_[0], $_[1]... instead
   1.246 +    ### my ( $web, $wikiName, $loginName ) = @_;
   1.247 +
   1.248 +    TWiki::Func::writeDebug( "- ${pluginName}::registrationHandler( $_[0], $_[1] )" ) if $debug;
   1.249 +}
   1.250 +
   1.251 +=pod
   1.252 +
   1.253 +---++ commonTagsHandler($text, $topic, $web, $included, $meta )
   1.254 +   * =$text= - text to be processed
   1.255 +   * =$topic= - the name of the topic in the current CGI query
   1.256 +   * =$web= - the name of the web in the current CGI query
   1.257 +   * =$included= - Boolean flag indicating whether the handler is invoked on an included topic
   1.258 +   * =$meta= - meta-data object for the topic MAY BE =undef=
   1.259 +This handler is called by the code that expands %<nop>TAGS% syntax in
   1.260 +the topic body and in form fields. It may be called many times while
   1.261 +a topic is being rendered.
   1.262 +
   1.263 +For variables with trivial syntax it is far more efficient to use
   1.264 +=TWiki::Func::registerTagHandler= (see =initPlugin=).
   1.265 +
   1.266 +Plugins that have to parse the entire topic content should implement
   1.267 +this function. Internal TWiki
   1.268 +variables (and any variables declared using =TWiki::Func::registerTagHandler=)
   1.269 +are expanded _before_, and then again _after_, this function is called
   1.270 +to ensure all %<nop>TAGS% are expanded.
   1.271 +
   1.272 +__NOTE:__ when this handler is called, &lt;verbatim> blocks have been
   1.273 +removed from the text (though all other blocks such as &lt;pre> and
   1.274 +&lt;noautolink> are still present).
   1.275 +
   1.276 +__NOTE:__ meta-data is _not_ embedded in the text passed to this
   1.277 +handler. Use the =$meta= object.
   1.278 +
   1.279 +*Since:* $TWiki::Plugins::VERSION 1.000
   1.280 +
   1.281 +=cut
   1.282 +
   1.283 +sub DISABLE_commonTagsHandler {
   1.284 +    # do not uncomment, use $_[0], $_[1]... instead
   1.285 +    ### my ( $text, $topic, $web, $meta ) = @_;
   1.286 +
   1.287 +    TWiki::Func::writeDebug( "- ${pluginName}::commonTagsHandler( $_[2].$_[1] )" ) if $debug;
   1.288 +
   1.289 +    # do custom extension rule, like for example:
   1.290 +    # $_[0] =~ s/%XYZ%/&handleXyz()/ge;
   1.291 +    # $_[0] =~ s/%XYZ{(.*?)}%/&handleXyz($1)/ge;
   1.292 +}
   1.293 +
   1.294 +=pod
   1.295 +
   1.296 +---++ beforeCommonTagsHandler($text, $topic, $web, $meta )
   1.297 +   * =$text= - text to be processed
   1.298 +   * =$topic= - the name of the topic in the current CGI query
   1.299 +   * =$web= - the name of the web in the current CGI query
   1.300 +   * =$meta= - meta-data object for the topic MAY BE =undef=
   1.301 +This handler is called before TWiki does any expansion of it's own
   1.302 +internal variables. It is designed for use by cache plugins. Note that
   1.303 +when this handler is called, &lt;verbatim> blocks are still present
   1.304 +in the text.
   1.305 +
   1.306 +__NOTE__: This handler is called once for each call to
   1.307 +=commonTagsHandler= i.e. it may be called many times during the
   1.308 +rendering of a topic.
   1.309 +
   1.310 +__NOTE:__ meta-data is _not_ embedded in the text passed to this
   1.311 +handler.
   1.312 +
   1.313 +__NOTE:__ This handler is not separately called on included topics.
   1.314 +
   1.315 +=cut
   1.316 +
   1.317 +sub DISABLE_beforeCommonTagsHandler {
   1.318 +    # do not uncomment, use $_[0], $_[1]... instead
   1.319 +    ### my ( $text, $topic, $web, $meta ) = @_;
   1.320 +
   1.321 +    TWiki::Func::writeDebug( "- ${pluginName}::beforeCommonTagsHandler( $_[2].$_[1] )" ) if $debug;
   1.322 +}
   1.323 +
   1.324 +=pod
   1.325 +
   1.326 +---++ afterCommonTagsHandler($text, $topic, $web, $meta )
   1.327 +   * =$text= - text to be processed
   1.328 +   * =$topic= - the name of the topic in the current CGI query
   1.329 +   * =$web= - the name of the web in the current CGI query
   1.330 +   * =$meta= - meta-data object for the topic MAY BE =undef=
   1.331 +This handler is after TWiki has completed expansion of %TAGS%.
   1.332 +It is designed for use by cache plugins. Note that when this handler
   1.333 +is called, &lt;verbatim> blocks are present in the text.
   1.334 +
   1.335 +__NOTE__: This handler is called once for each call to
   1.336 +=commonTagsHandler= i.e. it may be called many times during the
   1.337 +rendering of a topic.
   1.338 +
   1.339 +__NOTE:__ meta-data is _not_ embedded in the text passed to this
   1.340 +handler.
   1.341 +
   1.342 +=cut
   1.343 +
   1.344 +sub DISABLE_afterCommonTagsHandler {
   1.345 +    # do not uncomment, use $_[0], $_[1]... instead
   1.346 +    ### my ( $text, $topic, $web, $meta ) = @_;
   1.347 +
   1.348 +    TWiki::Func::writeDebug( "- ${pluginName}::afterCommonTagsHandler( $_[2].$_[1] )" ) if $debug;
   1.349 +}
   1.350 +
   1.351 +=pod
   1.352 +
   1.353 +---++ preRenderingHandler( $text, \%map )
   1.354 +   * =$text= - text, with the head, verbatim and pre blocks replaced with placeholders
   1.355 +   * =\%removed= - reference to a hash that maps the placeholders to the removed blocks.
   1.356 +
   1.357 +Handler called immediately before TWiki syntax structures (such as lists) are
   1.358 +processed, but after all variables have been expanded. Use this handler to 
   1.359 +process special syntax only recognised by your plugin.
   1.360 +
   1.361 +Placeholders are text strings constructed using the tag name and a 
   1.362 +sequence number e.g. 'pre1', "verbatim6", "head1" etc. Placeholders are 
   1.363 +inserted into the text inside &lt;!--!marker!--&gt; characters so the 
   1.364 +text will contain &lt;!--!pre1!--&gt; for placeholder pre1.
   1.365 +
   1.366 +Each removed block is represented by the block text and the parameters 
   1.367 +passed to the tag (usually empty) e.g. for
   1.368 +<verbatim>
   1.369 +<pre class='slobadob'>
   1.370 +XYZ
   1.371 +</pre>
   1.372 +the map will contain:
   1.373 +<pre>
   1.374 +$removed->{'pre1'}{text}:   XYZ
   1.375 +$removed->{'pre1'}{params}: class="slobadob"
   1.376 +</pre>
   1.377 +Iterating over blocks for a single tag is easy. For example, to prepend a 
   1.378 +line number to every line of every pre block you might use this code:
   1.379 +<verbatim>
   1.380 +foreach my $placeholder ( keys %$map ) {
   1.381 +    if( $placeholder =~ /^pre/i ) {
   1.382 +       my $n = 1;
   1.383 +       $map->{$placeholder}{text} =~ s/^/$n++/gem;
   1.384 +    }
   1.385 +}
   1.386 +</verbatim>
   1.387 +
   1.388 +__NOTE__: This handler is called once for each rendered block of text i.e. 
   1.389 +it may be called several times during the rendering of a topic.
   1.390 +
   1.391 +__NOTE:__ meta-data is _not_ embedded in the text passed to this
   1.392 +handler.
   1.393 +
   1.394 +Since TWiki::Plugins::VERSION = '1.026'
   1.395 +
   1.396 +=cut
   1.397 +
   1.398 +sub DISABLE_preRenderingHandler {
   1.399 +    # do not uncomment, use $_[0], $_[1]... instead
   1.400 +    #my( $text, $pMap ) = @_;
   1.401 +}
   1.402 +
   1.403 +=pod
   1.404 +
   1.405 +---++ postRenderingHandler( $text )
   1.406 +   * =$text= - the text that has just been rendered. May be modified in place.
   1.407 +
   1.408 +__NOTE__: This handler is called once for each rendered block of text i.e. 
   1.409 +it may be called several times during the rendering of a topic.
   1.410 +
   1.411 +__NOTE:__ meta-data is _not_ embedded in the text passed to this
   1.412 +handler.
   1.413 +
   1.414 +Since TWiki::Plugins::VERSION = '1.026'
   1.415 +
   1.416 +=cut
   1.417 +
   1.418 +sub DISABLE_postRenderingHandler {
   1.419 +    # do not uncomment, use $_[0], $_[1]... instead
   1.420 +    #my $text = shift;
   1.421 +}
   1.422 +
   1.423 +=pod
   1.424 +
   1.425 +---++ beforeEditHandler($text, $topic, $web )
   1.426 +   * =$text= - text that will be edited
   1.427 +   * =$topic= - the name of the topic in the current CGI query
   1.428 +   * =$web= - the name of the web in the current CGI query
   1.429 +This handler is called by the edit script just before presenting the edit text
   1.430 +in the edit box. It is called once when the =edit= script is run.
   1.431 +
   1.432 +__NOTE__: meta-data may be embedded in the text passed to this handler 
   1.433 +(using %META: tags)
   1.434 +
   1.435 +*Since:* TWiki::Plugins::VERSION = '1.010'
   1.436 +
   1.437 +=cut
   1.438 +
   1.439 +sub DISABLE_beforeEditHandler {
   1.440 +    # do not uncomment, use $_[0], $_[1]... instead
   1.441 +    ### my ( $text, $topic, $web ) = @_;
   1.442 +
   1.443 +    TWiki::Func::writeDebug( "- ${pluginName}::beforeEditHandler( $_[2].$_[1] )" ) if $debug;
   1.444 +}
   1.445 +
   1.446 +=pod
   1.447 +
   1.448 +---++ afterEditHandler($text, $topic, $web, $meta )
   1.449 +   * =$text= - text that is being previewed
   1.450 +   * =$topic= - the name of the topic in the current CGI query
   1.451 +   * =$web= - the name of the web in the current CGI query
   1.452 +   * =$meta= - meta-data for the topic.
   1.453 +This handler is called by the preview script just before presenting the text.
   1.454 +It is called once when the =preview= script is run.
   1.455 +
   1.456 +__NOTE:__ this handler is _not_ called unless the text is previewed.
   1.457 +
   1.458 +__NOTE:__ meta-data is _not_ embedded in the text passed to this
   1.459 +handler. Use the =$meta= object.
   1.460 +
   1.461 +*Since:* $TWiki::Plugins::VERSION 1.010
   1.462 +
   1.463 +=cut
   1.464 +
   1.465 +sub DISABLE_afterEditHandler {
   1.466 +    # do not uncomment, use $_[0], $_[1]... instead
   1.467 +    ### my ( $text, $topic, $web ) = @_;
   1.468 +
   1.469 +    TWiki::Func::writeDebug( "- ${pluginName}::afterEditHandler( $_[2].$_[1] )" ) if $debug;
   1.470 +}
   1.471 +
   1.472 +=pod
   1.473 +
   1.474 +---++ beforeSaveHandler($text, $topic, $web, $meta )
   1.475 +   * =$text= - text _with embedded meta-data tags_
   1.476 +   * =$topic= - the name of the topic in the current CGI query
   1.477 +   * =$web= - the name of the web in the current CGI query
   1.478 +   * =$meta= - the metadata of the topic being saved, represented by a TWiki::Meta object.
   1.479 +
   1.480 +This handler is called each time a topic is saved.
   1.481 +
   1.482 +__NOTE:__ meta-data is embedded in =$text= (using %META: tags). If you modify
   1.483 +the =$meta= object, then it will override any changes to the meta-data
   1.484 +embedded in the text. Modify *either* the META in the text *or* the =$meta=
   1.485 +object, never both. You are recommended to modify the =$meta= object rather
   1.486 +than the text, as this approach is proof against changes in the embedded
   1.487 +text format.
   1.488 +
   1.489 +*Since:* TWiki::Plugins::VERSION = '1.010'
   1.490 +
   1.491 +=cut
   1.492 +
   1.493 +sub DISABLE_beforeSaveHandler {
   1.494 +    # do not uncomment, use $_[0], $_[1]... instead
   1.495 +    ### my ( $text, $topic, $web ) = @_;
   1.496 +
   1.497 +    TWiki::Func::writeDebug( "- ${pluginName}::beforeSaveHandler( $_[2].$_[1] )" ) if $debug;
   1.498 +}
   1.499 +
   1.500 +=pod
   1.501 +
   1.502 +---++ afterSaveHandler($text, $topic, $web, $error, $meta )
   1.503 +   * =$text= - the text of the topic _excluding meta-data tags_
   1.504 +     (see beforeSaveHandler)
   1.505 +   * =$topic= - the name of the topic in the current CGI query
   1.506 +   * =$web= - the name of the web in the current CGI query
   1.507 +   * =$error= - any error string returned by the save.
   1.508 +   * =$meta= - the metadata of the saved topic, represented by a TWiki::Meta object 
   1.509 +
   1.510 +This handler is called each time a topic is saved.
   1.511 +
   1.512 +__NOTE:__ meta-data is embedded in $text (using %META: tags)
   1.513 +
   1.514 +*Since:* TWiki::Plugins::VERSION 1.025
   1.515 +
   1.516 +=cut
   1.517 +
   1.518 +sub DISABLE_afterSaveHandler {
   1.519 +    # do not uncomment, use $_[0], $_[1]... instead
   1.520 +    ### my ( $text, $topic, $web, $error, $meta ) = @_;
   1.521 +
   1.522 +    TWiki::Func::writeDebug( "- ${pluginName}::afterSaveHandler( $_[2].$_[1] )" ) if $debug;
   1.523 +}
   1.524 +
   1.525 +=pod
   1.526 +
   1.527 +---++ afterRenameHandler( $oldWeb, $oldTopic, $oldAttachment, $newWeb, $newTopic, $newAttachment )
   1.528 +
   1.529 +   * =$oldWeb= - name of old web
   1.530 +   * =$oldTopic= - name of old topic (empty string if web rename)
   1.531 +   * =$oldAttachment= - name of old attachment (empty string if web or topic rename)
   1.532 +   * =$newWeb= - name of new web
   1.533 +   * =$newTopic= - name of new topic (empty string if web rename)
   1.534 +   * =$newAttachment= - name of new attachment (empty string if web or topic rename)
   1.535 +
   1.536 +This handler is called just after the rename/move/delete action of a web, topic or attachment.
   1.537 +
   1.538 +*Since:* TWiki::Plugins::VERSION = '1.11'
   1.539 +
   1.540 +=cut
   1.541 +
   1.542 +sub DISABLE_afterRenameHandler {
   1.543 +    # do not uncomment, use $_[0], $_[1]... instead
   1.544 +    ### my ( $oldWeb, $oldTopic, $oldAttachment, $newWeb, $newTopic, $newAttachment ) = @_;
   1.545 +
   1.546 +    TWiki::Func::writeDebug( "- ${pluginName}::afterRenameHandler( " .
   1.547 +                             "$_[0].$_[1] $_[2] -> $_[3].$_[4] $_[5] )" ) if $debug;
   1.548 +}
   1.549 +
   1.550 +=pod
   1.551 +
   1.552 +---++ beforeAttachmentSaveHandler(\%attrHash, $topic, $web )
   1.553 +   * =\%attrHash= - reference to hash of attachment attribute values
   1.554 +   * =$topic= - the name of the topic in the current CGI query
   1.555 +   * =$web= - the name of the web in the current CGI query
   1.556 +This handler is called once when an attachment is uploaded. When this
   1.557 +handler is called, the attachment has *not* been recorded in the database.
   1.558 +
   1.559 +The attributes hash will include at least the following attributes:
   1.560 +   * =attachment= => the attachment name
   1.561 +   * =comment= - the comment
   1.562 +   * =user= - the user id
   1.563 +   * =tmpFilename= - name of a temporary file containing the attachment data
   1.564 +
   1.565 +*Since:* TWiki::Plugins::VERSION = 1.025
   1.566 +
   1.567 +=cut
   1.568 +
   1.569 +sub DISABLE_beforeAttachmentSaveHandler {
   1.570 +    # do not uncomment, use $_[0], $_[1]... instead
   1.571 +    ###   my( $attrHashRef, $topic, $web ) = @_;
   1.572 +    TWiki::Func::writeDebug( "- ${pluginName}::beforeAttachmentSaveHandler( $_[2].$_[1] )" ) if $debug;
   1.573 +}
   1.574 +
   1.575 +=pod
   1.576 +
   1.577 +---++ afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error )
   1.578 +   * =\%attrHash= - reference to hash of attachment attribute values
   1.579 +   * =$topic= - the name of the topic in the current CGI query
   1.580 +   * =$web= - the name of the web in the current CGI query
   1.581 +   * =$error= - any error string generated during the save process
   1.582 +This handler is called just after the save action. The attributes hash
   1.583 +will include at least the following attributes:
   1.584 +   * =attachment= => the attachment name
   1.585 +   * =comment= - the comment
   1.586 +   * =user= - the user id
   1.587 +
   1.588 +*Since:* TWiki::Plugins::VERSION = 1.025
   1.589 +
   1.590 +=cut
   1.591 +
   1.592 +sub DISABLE_afterAttachmentSaveHandler {
   1.593 +    # do not uncomment, use $_[0], $_[1]... instead
   1.594 +    ###   my( $attrHashRef, $topic, $web ) = @_;
   1.595 +    TWiki::Func::writeDebug( "- ${pluginName}::afterAttachmentSaveHandler( $_[2].$_[1] )" ) if $debug;
   1.596 +}
   1.597 +
   1.598 +=begin twiki
   1.599 +
   1.600 +---++ beforeMergeHandler( $text, $currRev, $currText, $origRev, $origText, $web, $topic )
   1.601 +   * =$text= - the new text of the topic
   1.602 +   * =$currRev= - the number of the most recent rev of the topic in the store
   1.603 +   * =$currText= - the text of that rev
   1.604 +   * =$origRev= - the number of the rev that the edit started on (or undef
   1.605 +     if that revision was overwritten by a replace-revision save)
   1.606 +   * =$origText= - the text of that revision (or undef)
   1.607 +   * =$web= - the name of the web for the topic being saved
   1.608 +   * =$topic= - the name of the topic
   1.609 +This handler is called immediately before a merge of a topic that was edited
   1.610 +simultaneously by two users. It is called once on the topic text from
   1.611 +the =save= script. See =mergeHandler= for handling individual changes in the
   1.612 +topic text (and in forms).
   1.613 +
   1.614 +=cut
   1.615 +
   1.616 +sub DISABLE_beforeMergeHandler {
   1.617 +    # do not uncomment, use $_[0], $_[1]... instead
   1.618 +    #my( $text, $currRev, $currText, $origRev, $origText, $web, $topic ) = @_;
   1.619 +}
   1.620 +
   1.621 +=pod
   1.622 +
   1.623 +---++ mergeHandler( $diff, $old, $new, \%info ) -> $text
   1.624 +Try to resolve a difference encountered during merge. The =differences= 
   1.625 +array is an array of hash references, where each hash contains the 
   1.626 +following fields:
   1.627 +   * =$diff= => one of the characters '+', '-', 'c' or ' '.
   1.628 +      * '+' - =new= contains text inserted in the new version
   1.629 +      * '-' - =old= contains text deleted from the old version
   1.630 +      * 'c' - =old= contains text from the old version, and =new= text
   1.631 +        from the version being saved
   1.632 +      * ' ' - =new= contains text common to both versions, or the change
   1.633 +        only involved whitespace
   1.634 +   * =$old= => text from version currently saved
   1.635 +   * =$new= => text from version being saved
   1.636 +   * =\%info= is a reference to the form field description { name, title,
   1.637 +     type, size, value, tooltip, attributes, referenced }. It must _not_
   1.638 +     be wrtten to. This parameter will be undef when merging the body
   1.639 +     text of the topic.
   1.640 +
   1.641 +Plugins should try to resolve differences and return the merged text. 
   1.642 +For example, a radio button field where we have 
   1.643 +={ diff=>'c', old=>'Leafy', new=>'Barky' }= might be resolved as 
   1.644 +='Treelike'=. If the plugin cannot resolve a difference it should return 
   1.645 +undef.
   1.646 +
   1.647 +The merge handler will be called several times during a save; once for 
   1.648 +each difference that needs resolution.
   1.649 +
   1.650 +If any merges are left unresolved after all plugins have been given a 
   1.651 +chance to intercede, the following algorithm is used to decide how to 
   1.652 +merge the data:
   1.653 +   1 =new= is taken for all =radio=, =checkbox= and =select= fields to 
   1.654 +     resolve 'c' conflicts
   1.655 +   1 '+' and '-' text is always included in the the body text and text
   1.656 +     fields
   1.657 +   1 =&lt;del>conflict&lt;/del> &lt;ins>markers&lt;/ins>= are used to 
   1.658 +     mark 'c' merges in text fields
   1.659 +
   1.660 +The merge handler is called whenever a topic is saved, and a merge is 
   1.661 +required to resolve concurrent edits on a topic.
   1.662 +
   1.663 +*Since:* TWiki::Plugins::VERSION = 1.1
   1.664 +
   1.665 +=cut
   1.666 +
   1.667 +sub DISABLE_mergeHandler {
   1.668 +}
   1.669 +
   1.670 +=pod
   1.671 +
   1.672 +---++ modifyHeaderHandler( \%headers, $query )
   1.673 +   * =\%headers= - reference to a hash of existing header values
   1.674 +   * =$query= - reference to CGI query object
   1.675 +Lets the plugin modify the HTTP headers that will be emitted when a
   1.676 +page is written to the browser. \%headers= will contain the headers
   1.677 +proposed by the core, plus any modifications made by other plugins that also
   1.678 +implement this method that come earlier in the plugins list.
   1.679 +<verbatim>
   1.680 +$headers->{expires} = '+1h';
   1.681 +</verbatim>
   1.682 +
   1.683 +Note that this is the HTTP header which is _not_ the same as the HTML
   1.684 +&lt;HEAD&gt; tag. The contents of the &lt;HEAD&gt; tag may be manipulated
   1.685 +using the =TWiki::Func::addToHEAD= method.
   1.686 +
   1.687 +*Since:* TWiki::Plugins::VERSION 1.1
   1.688 +
   1.689 +=cut
   1.690 +
   1.691 +sub DISABLE_modifyHeaderHandler {
   1.692 +    my ( $headers, $query ) = @_;
   1.693 +
   1.694 +    TWiki::Func::writeDebug( "- ${pluginName}::modifyHeaderHandler()" ) if $debug;
   1.695 +}
   1.696 +
   1.697 +=pod
   1.698 +
   1.699 +---++ redirectCgiQueryHandler($query, $url )
   1.700 +   * =$query= - the CGI query
   1.701 +   * =$url= - the URL to redirect to
   1.702 +
   1.703 +This handler can be used to replace TWiki's internal redirect function.
   1.704 +
   1.705 +If this handler is defined in more than one plugin, only the handler
   1.706 +in the earliest plugin in the INSTALLEDPLUGINS list will be called. All
   1.707 +the others will be ignored.
   1.708 +
   1.709 +*Since:* TWiki::Plugins::VERSION 1.010
   1.710 +
   1.711 +=cut
   1.712 +
   1.713 +sub DISABLE_redirectCgiQueryHandler {
   1.714 +    # do not uncomment, use $_[0], $_[1] instead
   1.715 +    ### my ( $query, $url ) = @_;
   1.716 +
   1.717 +    TWiki::Func::writeDebug( "- ${pluginName}::redirectCgiQueryHandler( query, $_[1] )" ) if $debug;
   1.718 +}
   1.719 +
   1.720 +=pod
   1.721 +
   1.722 +---++ renderFormFieldForEditHandler($name, $type, $size, $value, $attributes, $possibleValues) -> $html
   1.723 +
   1.724 +This handler is called before built-in types are considered. It generates 
   1.725 +the HTML text rendering this form field, or false, if the rendering 
   1.726 +should be done by the built-in type handlers.
   1.727 +   * =$name= - name of form field
   1.728 +   * =$type= - type of form field (checkbox, radio etc)
   1.729 +   * =$size= - size of form field
   1.730 +   * =$value= - value held in the form field
   1.731 +   * =$attributes= - attributes of form field 
   1.732 +   * =$possibleValues= - the values defined as options for form field, if
   1.733 +     any. May be a scalar (one legal value) or a ref to an array
   1.734 +     (several legal values)
   1.735 +
   1.736 +Return HTML text that renders this field. If false, form rendering
   1.737 +continues by considering the built-in types.
   1.738 +
   1.739 +*Since:* TWiki::Plugins::VERSION 1.1
   1.740 +
   1.741 +Note that since TWiki-4.2, you can also extend the range of available
   1.742 +types by providing a subclass of =TWiki::Form::FieldDefinition= to implement
   1.743 +the new type (see =TWiki::Plugins.JSCalendarContrib= and
   1.744 +=TWiki::Plugins.RatingContrib= for examples). This is the preferred way to
   1.745 +extend the form field types, but does not work for TWiki < 4.2.
   1.746 +
   1.747 +=cut
   1.748 +
   1.749 +sub DISABLE_renderFormFieldForEditHandler {
   1.750 +}
   1.751 +
   1.752 +=pod
   1.753 +
   1.754 +---++ renderWikiWordHandler($linkText, $hasExplicitLinkLabel, $web, $topic) -> $linkText
   1.755 +   * =$linkText= - the text for the link i.e. for =[<nop>[Link][blah blah]]=
   1.756 +     it's =blah blah=, for =BlahBlah= it's =BlahBlah=, and for [[Blah Blah]] it's =Blah Blah=.
   1.757 +   * =$hasExplicitLinkLabel= - true if the link is of the form =[<nop>[Link][blah blah]]= (false if it's ==<nop>[Blah]] or =BlahBlah=)
   1.758 +   * =$web=, =$topic= - specify the topic being rendered (only since TWiki 4.2)
   1.759 +
   1.760 +Called during rendering, this handler allows the plugin a chance to change
   1.761 +the rendering of labels used for links.
   1.762 +
   1.763 +Return the new link text.
   1.764 +
   1.765 +*Since:* TWiki::Plugins::VERSION 1.1
   1.766 +
   1.767 +=cut
   1.768 +
   1.769 +sub DISABLE_renderWikiWordHandler {
   1.770 +    my( $linkText, $hasExplicitLinkLabel, $web, $topic ) = @_;
   1.771 +    return $linkText;
   1.772 +}
   1.773 +
   1.774 +=pod
   1.775 +
   1.776 +---++ completePageHandler($html, $httpHeaders)
   1.777 +
   1.778 +This handler is called on the ingredients of every page that is
   1.779 +output by the standard TWiki scripts. It is designed primarily for use by
   1.780 +cache and security plugins.
   1.781 +   * =$html= - the body of the page (normally &lt;html>..$lt;/html>)
   1.782 +   * =$httpHeaders= - the HTTP headers. Note that the headers do not contain
   1.783 +     a =Content-length=. That will be computed and added immediately before
   1.784 +     the page is actually written. This is a string, which must end in \n\n.
   1.785 +
   1.786 +*Since:* TWiki::Plugins::VERSION 1.2
   1.787 +
   1.788 +=cut
   1.789 +
   1.790 +sub DISABLE_completePageHandler {
   1.791 +    #my($html, $httpHeaders) = @_;
   1.792 +    # modify $_[0] or $_[1] if you must change the HTML or headers
   1.793 +}
   1.794 +
   1.795 +=pod
   1.796 +
   1.797 +---++ restExample($session) -> $text
   1.798 +
   1.799 +This is an example of a sub to be called by the =rest= script. The parameter is:
   1.800 +   * =$session= - The TWiki object associated to this session.
   1.801 +
   1.802 +Additional parameters can be recovered via de query object in the $session.
   1.803 +
   1.804 +For more information, check TWiki:TWiki.TWikiScripts#rest
   1.805 +
   1.806 +*Since:* TWiki::Plugins::VERSION 1.1
   1.807 +
   1.808 +=cut
   1.809 +
   1.810 +sub restExample {
   1.811 +   #my ($session) = @_;
   1.812 +   return "This is an example of a REST invocation\n\n";
   1.813 +}
   1.814 +
   1.815 +1;