lib/TWiki/Plugins/EmptyPlugin.pm
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     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;