1 # <a name="Package <code>TWiki::Plugins="></a> Package =TWiki::Plugins
3 This module defines the singleton object that handles Plugins loading, initialization and execution.
5 This class uses Chain of Responsibility (GOF) pattern to dispatch handler calls to registered plugins.
9 <li><a href="#Package =TWiki::Plugins="> Package TWiki::Plugins</a><ul>
10 <li><a href="#PUBLIC constant $VERSION"> PUBLIC constant $VERSION</a></li>
11 <li><a href="#PUBLIC $SESSION"> PUBLIC $SESSION</a></li>
12 <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
13 <li><a href="#ObjectMethod <strong>load</strong> ($allDisable"> ObjectMethod load <tt>($allDisabled) -> $loginName</tt></a></li>
14 <li><a href="#ObjectMethod <strong>enable</strong> ()"> ObjectMethod enable <tt>()</tt></a></li>
15 <li><a href="#ObjectMethod *get_PluginVersion*"> ObjectMethod getPluginVersion <tt>() -> $number</tt></a></li>
16 <li><a href="#ObjectMethod <strong>addListener</strong> ($com"> ObjectMethod addListener <tt>($command,$handler)</tt></a></li>
17 <li><a href="#ObjectMethod <strong>have_HandlerFor</strong> ("> ObjectMethod haveHandlerFor <tt>($handlerName) -> $boolean</tt></a></li>
18 <li><a href="#ObjectMethod *registrationHandle"> ObjectMethod registrationHandler <tt>()</tt></a></li>
19 <li><a href="#ObjectMethod *before_CommonTagsH"> ObjectMethod beforeCommonTagsHandler <tt>()</tt></a></li>
20 <li><a href="#ObjectMethod *common_TagsHandler"> ObjectMethod commonTagsHandler <tt>()</tt></a></li>
21 <li><a href="#ObjectMethod *after_CommonTagsHa"> ObjectMethod afterCommonTagsHandler <tt>()</tt></a></li>
22 <li><a href="#ObjectMethd pre_RenderingHandler"> ObjectMethd preRenderingHandler( $text, \%map )</a></li>
28 Note that as of version 1.026 of this module, TWiki internal methods are _no longer available_ to plugins. Any calls to TWiki internal methods must be replaced by calls via the $SESSION object in this package, or via the Func package. For example, the call:
30 my $pref = TWiki::getPreferencesValue('URGH');
32 should be replaced with
34 my $pref = TWiki::Func::getPreferencesValue('URGH');
38 my $t = TWiki::writeWarning($message);
40 should be replaced with
42 my $pref = $TWiki::Plugins::SESSION->writeWarning($message);
44 Methods in other modules such as Store must be accessed through the relevant TWiki sub-object, for example
46 TWiki::Store::saveTopic(...)
48 should be replaced with
50 $TWiki::Plugins::SESSION->\{store\}->saveTopic(...)
52 Note that calling TWiki internal methods is very very bad practice, and should be avoided wherever practical.
54 The developers of TWiki reserve the right to change internal methods without warning, unless those methods are clearly marked as PUBLIC. PUBLIC methods are part of the core specification of a module and can be trusted.
56 ## <a name="PUBLIC constant $VERSION"></a> PUBLIC constant $VERSION
58 This is the version number of the plugins package. Use it for checking if you have a recent enough version.
60 ## <a name="PUBLIC $SESSION"></a> PUBLIC $SESSION
62 This is a reference to the TWiki session object. It can be used in plugins to get at the methods of the TWiki kernel.
64 You are _highly_ recommended to only use the methods in the [[Func|Main/TWikiFuncDotPm]] interface, unless you have no other choice, as kernel methods may change between TWiki releases.
66 ## <a name="ClassMethod <strong>new</strong> ($session)"></a> [[ClassMethod]] **new** `($session)`
68 Construct new singleton plugins collection object. The object is a container for a list of plugins and the handlers registered by the plugins. The plugins and the handlers are carefully ordered.
70 ## <a name="ObjectMethod <strong>load</strong> ($allDisable"></a> [[ObjectMethod]] **load** `($allDisabled) -> $loginName`
72 Find all active plugins, and invoke the early initialisation. Has to be done _after_ prefs are read.
74 Returns the user returned by the last `initializeUserHandler` to be called.
76 If allDisabled is set, no plugin handlers will be called.
78 ## <a name="ObjectMethod <strong>enable</strong> ()"></a> [[ObjectMethod]] **enable** `()`
80 Initialisation that is done after the user is known.
82 ## <a name="ObjectMethod <strong>get_PluginVersion*"></a> [[ObjectMethod]] \*getPluginVersion `() -> $number`
84 Returns the $TWiki::Plugins::VERSION number if no parameter is specified, else returns the version number of a named Plugin. If the Plugin cannot be found or is not active, 0 is returned.
86 ## <a name="ObjectMethod <strong>addListener</strong> ($com"></a> [[ObjectMethod]] **addListener** `($command,$handler)`
88 - =$command\* - name of the event
89 - `$handler` - the handler object.
91 Add a listener to the end of the list of registered listeners for this event. The listener must implement `invoke($command,...)`, which will be triggered when the event is to be processed.
93 ## <a name="ObjectMethod <strong>have_HandlerFor</strong> ("></a> [[ObjectMethod]] **haveHandlerFor** `($handlerName) -> $boolean`
95 - `$handlerName` - name of the handler e.g. preRenderingHandler
97 Return: true if at least one plugin has registered a handler of this type.
99 ## <a name="ObjectMethod <strong>registrationHandle"></a> [[ObjectMethod]] \*registrationHandler `()`
101 Called by the register script
103 ## <a name="ObjectMethod <strong>before_CommonTagsH"></a> [[ObjectMethod]] \*beforeCommonTagsHandler `()`
105 Called at the beginning (for cache Plugins only)
107 ## <a name="ObjectMethod <strong>common_TagsHandler"></a> [[ObjectMethod]] \*commonTagsHandler `()`
109 Called after %INCLUDE:"..."%
111 ## <a name="ObjectMethod <strong>after_CommonTagsHa"></a> [[ObjectMethod]] \*afterCommonTagsHandler `()`
113 Called at the end (for cache Plugins only)
115 ## <a name="ObjectMethd pre_RenderingHandler"></a> [[ObjectMethd]] preRenderingHandler( $text, \\%map )
117 - `$text` - the text, with the head, verbatim and pre blocks replaced with placeholders
118 - `\%removed` - reference to a hash that maps the placeholders to the removed blocks.
120 Placeholders are text strings constructed using the tag name and a sequence number e.g. 'pre1', "verbatim6", "head1" etc. Placeholders are inserted into the text inside \\1 characters so the text will contain \\1\_pre1\\1 for placeholder pre1.
122 Each removed block is represented by the block text and the parameters passed to the tag (usually empty) e.g. for
124 <pre class='slobadob'>
127 the map will contain:
129 $removed->{'pre1'}{text}: XYZ
130 $removed->{'pre1'}{params}: class="slobadob"
133 Iterating over blocks for a single tag is easy. For example, to prepend a line number to every line of a pre block you might use this code:
135 foreach my $placeholder ( keys %$map ) {
136 if( $placeholder =~ /^pre/i ) {
138 $map->{$placeholder}{text} =~ s/^/$n++/gem;
142 ---++ ObjectMethod *postRenderingHandler* <tt>(\$text)</tt>
144 * =\$text= - a reference to the HTML, with the head, verbatim and pre blocks replaced with placeholders
146 ---++ ObjectMethod *startRenderingHandler* <tt>()</tt>
148 Called just before the line loop
150 *DEPRECATED* Use preRenderingHandler instead. This handler correctly
151 handles verbatim and other TWiki ML block types, and exposes them to
154 ---++ ObjectMethod *outsidePREHandler* <tt>()</tt>
156 Called in line loop outside of <PRE> tag
158 *DEPRECATED* Use preRenderingHandler instead.
159 This handler correctly handles pre and other
160 TWiki ML block types, and is called only once
161 instead of line-by-line.
163 ---++ ObjectMethod *insidePREHandler* <tt>()</tt>
165 Called in line loop inside of <PRE> tag
167 *DEPRECATED* Use preRenderingHandler instead.
168 This handler correctly handles pre and other
169 TWiki ML block types, and is called only once
170 instead of line-by-line.
172 ---++ ObjectMethod *endRenderingHandler* <tt>()</tt>
174 Called just after the line loop
176 *DEPRECATED* Use postRenderingHandler instead.
178 ---++ ObjectMethod *beforeEditHandler* <tt>()</tt>
182 ---++ ObjectMethod *afterEditHandler* <tt>()</tt>
186 ---++ ObjectMethod *beforeSaveHandler* <tt>()</tt>
188 Called just before the save action
190 ---++ ObjectMethod *afterSaveHandler* <tt>()</tt>
192 Called just after the save action
194 ---++ ObjectMethod *mergeHandler* <tt>()</tt>
196 Called to handle text merge.
198 ---++ ObjectMethod *beforeAttachmentSaveHandler* <tt>($attrHashRef,$topic,$web)</tt>
200 This code provides Plugins with the opportunity to alter an uploaded attachment between the upload and save-to-store processes. It is invoked as per other Plugins.
201 * =$attrHashRef= - Hash reference of attachment attributes (keys are indicated below)
202 * =$topic= - | Topic name
203 * =$web= - | Web name
205 Keys in $attrHashRef:
207 | attachment | Name of the attachment |
208 | tmpFilename | Name of the local file that stores the upload |
209 | comment | Comment to be associated with the upload |
210 | user | Login name of the person submitting the attachment, e.g. 'jsmith' |
212 Note: All keys should be used read-only, except for comment which can be modified.
217 my( $attrHashRef, $topic, $web ) = @_;
218 $$attrHashRef{'comment'} .= " (NOTE: Extracted from blah.tar.gz)";
221 ---++ ObjectMethod *afterAttachmentSaveHandler* <tt>($attachmentAttrHash,$topic,$web,$error)</tt>
223 deal with an uploaded attachment between the upload and save-to-store processes. It is invoked as per other plugins.
225 * =$attrHashRef= - Hash reference of attachment attributes (keys are indicated below)
226 * =$topic= - | Topic name
227 * =$web= - | Web name
228 * =$error= - | Error string of save action, empty if OK
230 Keys in $attrHashRef:
232 | attachment | Name of the attachment |
233 | tmpFilename | Name of the local file that stores the upload |
234 | comment | Comment to be associated with the upload |
235 | user | Login name of the person submitting the attachment, e.g. 'jsmith' |
237 Note: The hash is *read-only*
239 ---++ ObjectMethod *writeHeaderHandler* <tt>() -> $headers</tt>
241 Called by TWiki::writePageHeader. *DEPRECATED* do not use!
243 *DEPRECATED* Use modifyHeaderHandler instead. it is a lot
244 more flexible, and allows you to modify existing headers
245 as well as add new ones. It also works correctly when
246 multiple plugins want to modify headers.
248 ---++ ObjectMethod *modifyHeaderHandler* <tt>(\@headers,$query)</tt>
250 ---++ ObjectMethod *redirectCgiQueryHandler* <tt>() -> $result</tt>
252 Called by TWiki::redirect
254 ---++ ObjectMethod *renderFormFieldForEditHandler* <tt>($name,$type,$size,$value,$attributes,$possibleValues) -> $html</tt>
256 This handler is called before built-in types are considered. It generates the HTML text rendering this form field, or false, if the rendering should be done by the built-in type handlers.
257 * =$name= - name of form field
258 * =$type= - type of form field
259 * =$size= - size of form field
260 * =$value= - value held in the form field
261 * =$attributes= - attributes of form field
262 * =$possibleValues= - the values defined as options for form field, if any. May be a scalar (one legal value) or an array (several legal values)
263 Return HTML text that renders this field. If false, form rendering continues by considering the built-in types.
265 Note that a common application would be to generate formatting of the
266 field involving generation of javascript. Such usually also requires
267 the insertion of some common javascript into the page header. Unfortunately,
268 there is currently no mechanism to pass that script to where the header of
269 the page is visible. Consequentially, the common javascript may have to
270 be emitted as part of the field formatting and might be duplicated many
271 times throughout the page.
273 ---++ ObjectMethod *renderWikiWordHandler* <tt>() -> $result</tt>
275 Change how a WikiWord is rendered
277 Originated from the TWiki:Plugins.SpacedWikiWordPlugin hack