1 rizwank 1.1 # Plugin for TWiki Collaboration Platform, http://TWiki.org/
  2             #
  3             # Copyright (C) 2000-2003 Andrea Sterbini, a.sterbini@flashnet.it
  4             # Copyright (C) 2001-2004 Peter Thoeny, peter@thoeny.com
  5             #
  6             # This program is free software; you can redistribute it and/or
  7             # modify it under the terms of the GNU General Public License
  8             # as published by the Free Software Foundation; either version 2
  9             # of the License, or (at your option) any later version.
 10             #
 11             # This program is distributed in the hope that it will be useful,
 12             # but WITHOUT ANY WARRANTY; without even the implied warranty of
 13             # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 14             # GNU General Public License for more details, published at 
 15             # http://www.gnu.org/copyleft/gpl.html
 16             #
 17             # =========================
 18             #
 19             # This is an empty TWiki plugin. Use it as a template
 20             # for your own plugins; see TWiki.TWikiPlugins for details.
 21             #
 22 rizwank 1.1 # Each plugin is a package that may contain these functions:        VERSION:
 23             #
 24             #   earlyInitPlugin         ( )                                     1.020
 25             #   initPlugin              ( $topic, $web, $user, $installWeb )    1.000
 26             #   initializeUserHandler   ( $loginName, $url, $pathInfo )         1.010
 27             #   registrationHandler     ( $web, $wikiName, $loginName )         1.010
 28             #   beforeCommonTagsHandler ( $text, $topic, $web )                 1.024
 29             #   commonTagsHandler       ( $text, $topic, $web )                 1.000
 30             #   afterCommonTagsHandler  ( $text, $topic, $web )                 1.024
 31             #   startRenderingHandler   ( $text, $web )                         1.000
 32             #   outsidePREHandler       ( $text )                               1.000
 33             #   insidePREHandler        ( $text )                               1.000
 34             #   endRenderingHandler     ( $text )                               1.000
 35             #   beforeEditHandler       ( $text, $topic, $web )                 1.010
 36             #   afterEditHandler        ( $text, $topic, $web )                 1.010
 37             #   beforeSaveHandler       ( $text, $topic, $web )                 1.010
 38             #   afterSaveHandler        ( $text, $topic, $web, $errors )        1.020
 39             #   writeHeaderHandler      ( $query )                              1.010  Use only in one Plugin
 40             #   redirectCgiQueryHandler ( $query, $url )                        1.010  Use only in one Plugin
 41             #   getSessionValueHandler  ( $key )                                1.010  Use only in one Plugin
 42             #   setSessionValueHandler  ( $key, $value )                        1.010  Use only in one Plugin
 43 rizwank 1.1 #
 44             # initPlugin is required, all other are optional. 
 45             # For increased performance, all handlers except initPlugin are
 46             # disabled. To enable a handler remove the leading DISABLE_ from
 47             # the function name. Remove disabled handlers you do not need.
 48             #
 49             # NOTE: To interact with TWiki use the official TWiki functions 
 50             # in the TWiki::Func module. Do not reference any functions or
 51             # variables elsewhere in TWiki!!
 52             
 53             
 54             # =========================
 55             package TWiki::Plugins::EmptyPlugin;    # change the package name and $pluginName!!!
 56             
 57             # =========================
 58             use vars qw(
 59                     $web $topic $user $installWeb $VERSION $pluginName
 60                     $debug $exampleCfgVar
 61                 );
 62             
 63             $VERSION = '1.021';
 64 rizwank 1.1 $pluginName = 'EmptyPlugin';  # Name of this Plugin
 65             
 66             # =========================
 67             sub initPlugin
 68             {
 69                 ( $topic, $web, $user, $installWeb ) = @_;
 70             
 71                 # check for Plugins.pm versions
 72                 if( $TWiki::Plugins::VERSION < 1.021 ) {
 73                     TWiki::Func::writeWarning( "Version mismatch between $pluginName and Plugins.pm" );
 74                     return 0;
 75                 }
 76             
 77                 # Get plugin debug flag
 78                 $debug = TWiki::Func::getPluginPreferencesFlag( "DEBUG" );
 79             
 80                 # Get plugin preferences, the variable defined by:          * Set EXAMPLE = ...
 81                 $exampleCfgVar = TWiki::Func::getPluginPreferencesValue( "EXAMPLE" ) || "default";
 82             
 83                 # Plugin correctly initialized
 84                 TWiki::Func::writeDebug( "- TWiki::Plugins::${pluginName}::initPlugin( $web.$topic ) is OK" ) if $debug;
 85 rizwank 1.1     return 1;
 86             }
 87             
 88             # =========================
 89             sub DISABLE_earlyInitPlugin
 90             {
 91             ### Remove DISABLE_ for a plugin that requires early initialization, that is expects to have
 92             ### initializeUserHandler called before initPlugin, giving the plugin a chance to set the user
 93             ### See SessionPlugin for an example of this.
 94                 return 1;
 95             }
 96             
 97             
 98             # =========================
 99             sub DISABLE_initializeUserHandler
100             {
101             ### my ( $loginName, $url, $pathInfo ) = @_;   # do not uncomment, use $_[0], $_[1]... instead
102             
103                 TWiki::Func::writeDebug( "- ${pluginName}::initializeUserHandler( $_[0], $_[1] )" ) if $debug;
104             
105                 # Allows a plugin to set the username based on cookies. Called by TWiki::initialize.
106 rizwank 1.1     # Return the user name, or "guest" if not logged in.
107                 # New hook in TWiki::Plugins $VERSION = '1.010'
108             
109             }
110             
111             # =========================
112             sub DISABLE_registrationHandler
113             {
114             ### my ( $web, $wikiName, $loginName ) = @_;   # do not uncomment, use $_[0], $_[1]... instead
115             
116                 TWiki::Func::writeDebug( "- ${pluginName}::registrationHandler( $_[0], $_[1] )" ) if $debug;
117             
118                 # Allows a plugin to set a cookie at time of user registration.
119                 # Called by the register script.
120                 # New hook in TWiki::Plugins $VERSION = '1.010'
121             
122             }
123             
124             # =========================
125             sub DISABLE_beforeCommonTagsHandler
126             {
127 rizwank 1.1 ### my ( $text, $topic, $web ) = @_;   # do not uncomment, use $_[0], $_[1]... instead
128             
129                 TWiki::Func::writeDebug( "- ${pluginName}::beforeCommonTagsHandler( $_[2].$_[1] )" ) if $debug;
130             
131                 # Called at the beginning of TWiki::handleCommonTags (for cache Plugins use only)
132             }
133             
134             # =========================
135             sub DISABLE_commonTagsHandler
136             {
137             ### my ( $text, $topic, $web ) = @_;   # do not uncomment, use $_[0], $_[1]... instead
138             
139                 TWiki::Func::writeDebug( "- ${pluginName}::commonTagsHandler( $_[2].$_[1] )" ) if $debug;
140             
141                 # This is the place to define customized tags and variables
142                 # Called by TWiki::handleCommonTags, after %INCLUDE:"..."%
143             
144                 # do custom extension rule, like for example:
145                 # $_[0] =~ s/%XYZ%/&handleXyz()/ge;
146                 # $_[0] =~ s/%XYZ{(.*?)}%/&handleXyz($1)/ge;
147             }
148 rizwank 1.1 
149             # =========================
150             sub DISABLE_afterCommonTagsHandler
151             {
152             ### my ( $text, $topic, $web ) = @_;   # do not uncomment, use $_[0], $_[1]... instead
153             
154                 TWiki::Func::writeDebug( "- ${pluginName}::afterCommonTagsHandler( $_[2].$_[1] )" ) if $debug;
155             
156                 # Called at the end of TWiki::handleCommonTags (for cache Plugins use only)
157             }
158             
159             # =========================
160             sub DISABLE_startRenderingHandler
161             {
162             ### my ( $text, $web ) = @_;   # do not uncomment, use $_[0], $_[1] instead
163             
164                 TWiki::Func::writeDebug( "- ${pluginName}::startRenderingHandler( $_[1] )" ) if $debug;
165             
166                 # This handler is called by getRenderedVersion just before the line loop
167             
168                 # do custom extension rule, like for example:
169 rizwank 1.1     # $_[0] =~ s/old/new/g;
170             }
171             
172             # =========================
173             sub DISABLE_outsidePREHandler
174             {
175             ### my ( $text ) = @_;   # do not uncomment, use $_[0] instead
176             
177                 ##TWiki::Func::writeDebug( "- ${pluginName}::outsidePREHandler( $renderingWeb.$topic )" ) if $debug;
178             
179                 # This handler is called by getRenderedVersion, once per line, before any changes,
180                 # for lines outside <pre> and <verbatim> tags. 
181                 # Use it to define customized rendering rules.
182                 # Note: This is an expensive function to comment out.
183                 # Consider startRenderingHandler instead
184             
185                 # do custom extension rule, like for example:
186                 # $_[0] =~ s/old/new/g;
187             }
188             
189             # =========================
190 rizwank 1.1 sub DISABLE_insidePREHandler
191             {
192             ### my ( $text ) = @_;   # do not uncomment, use $_[0] instead
193             
194                 ##TWiki::Func::writeDebug( "- ${pluginName}::insidePREHandler( $web.$topic )" ) if $debug;
195             
196                 # This handler is called by getRenderedVersion, once per line, before any changes,
197                 # for lines inside <pre> and <verbatim> tags. 
198                 # Use it to define customized rendering rules.
199                 # Note: This is an expensive function to comment out.
200                 # Consider startRenderingHandler instead
201             
202                 # do custom extension rule, like for example:
203                 # $_[0] =~ s/old/new/g;
204             }
205             
206             # =========================
207             sub DISABLE_endRenderingHandler
208             {
209             ### my ( $text ) = @_;   # do not uncomment, use $_[0] instead
210             
211 rizwank 1.1     TWiki::Func::writeDebug( "- ${pluginName}::endRenderingHandler( $web.$topic )" ) if $debug;
212             
213                 # This handler is called by getRenderedVersion just after the line loop, that is,
214                 # after almost all XHTML rendering of a topic. <nop> tags are removed after this.
215             
216             }
217             
218             # =========================
219             sub DISABLE_beforeEditHandler
220             {
221             ### my ( $text, $topic, $web ) = @_;   # do not uncomment, use $_[0], $_[1]... instead
222             
223                 TWiki::Func::writeDebug( "- ${pluginName}::beforeEditHandler( $_[2].$_[1] )" ) if $debug;
224             
225                 # This handler is called by the edit script just before presenting the edit text
226                 # in the edit box. Use it to process the text before editing.
227                 # New hook in TWiki::Plugins $VERSION = '1.010'
228             
229             }
230             
231             # =========================
232 rizwank 1.1 sub DISABLE_afterEditHandler
233             {
234             ### my ( $text, $topic, $web ) = @_;   # do not uncomment, use $_[0], $_[1]... instead
235             
236                 TWiki::Func::writeDebug( "- ${pluginName}::afterEditHandler( $_[2].$_[1] )" ) if $debug;
237             
238                 # This handler is called by the preview script just before presenting the text.
239                 # New hook in TWiki::Plugins $VERSION = '1.010'
240             
241             }
242             
243             # =========================
244             sub DISABLE_beforeSaveHandler
245             {
246             ### my ( $text, $topic, $web ) = @_;   # do not uncomment, use $_[0], $_[1]... instead
247             
248                 TWiki::Func::writeDebug( "- ${pluginName}::beforeSaveHandler( $_[2].$_[1] )" ) if $debug;
249             
250                 # This handler is called by TWiki::Store::saveTopic just before the save action.
251                 # New hook in TWiki::Plugins $VERSION = '1.010'
252             
253 rizwank 1.1 }
254             
255             # =========================
256             sub DISABLE_afterSaveHandler
257             {
258             ### my ( $text, $topic, $web, $error ) = @_;   # do not uncomment, use $_[0], $_[1]... instead
259             
260                 TWiki::Func::writeDebug( "- ${pluginName}::afterSaveHandler( $_[2].$_[1] )" ) if $debug;
261             
262                 # This handler is called by TWiki::Store::saveTopic just after the save action.
263                 # New hook in TWiki::Plugins $VERSION = '1.020'
264             
265             }
266             
267             # =========================
268             sub DISABLE_writeHeaderHandler
269             {
270             ### my ( $query ) = @_;   # do not uncomment, use $_[0] instead
271             
272                 TWiki::Func::writeDebug( "- ${pluginName}::writeHeaderHandler( query )" ) if $debug;
273             
274 rizwank 1.1     # This handler is called by TWiki::writeHeader, just prior to writing header. 
275                 # Return a single result: A string containing HTTP headers, delimited by CR/LF
276                 # and with no blank lines. Plugin generated headers may be modified by core
277                 # code before they are output, to fix bugs or manage caching. Plugins should no
278                 # longer write headers to standard output.
279                 # Use only in one Plugin.
280                 # New hook in TWiki::Plugins $VERSION = '1.010'
281             
282             }
283             
284             # =========================
285             sub DISABLE_redirectCgiQueryHandler
286             {
287             ### my ( $query, $url ) = @_;   # do not uncomment, use $_[0], $_[1] instead
288             
289                 TWiki::Func::writeDebug( "- ${pluginName}::redirectCgiQueryHandler( query, $_[1] )" ) if $debug;
290             
291                 # This handler is called by TWiki::redirect. Use it to overload TWiki's internal redirect.
292                 # Use only in one Plugin.
293                 # New hook in TWiki::Plugins $VERSION = '1.010'
294             
295 rizwank 1.1 }
296             
297             # =========================
298             sub DISABLE_getSessionValueHandler
299             {
300             ### my ( $key ) = @_;   # do not uncomment, use $_[0] instead
301             
302                 TWiki::Func::writeDebug( "- ${pluginName}::getSessionValueHandler( $_[0] )" ) if $debug;
303             
304                 # This handler is called by TWiki::getSessionValue. Return the value of a key.
305                 # Use only in one Plugin.
306                 # New hook in TWiki::Plugins $VERSION = '1.010'
307             
308             }
309             
310             # =========================
311             sub DISABLE_setSessionValueHandler
312             {
313             ### my ( $key, $value ) = @_;   # do not uncomment, use $_[0], $_[1] instead
314             
315                 TWiki::Func::writeDebug( "- ${pluginName}::setSessionValueHandler( $_[0], $_[1] )" ) if $debug;
316 rizwank 1.1 
317                 # This handler is called by TWiki::setSessionValue. 
318                 # Use only in one Plugin.
319                 # New hook in TWiki::Plugins $VERSION = '1.010'
320             
321             }
322             
323             # =========================
324             
325             1;