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