1 # <a name="Package <code>TWiki::Func="></a> Package =TWiki::Func
3 _Official list of stable TWiki functions for Plugin developers_
5 This module defines official functions that [[Plugins|SYSTEMWEB/TWikiPlugins]] can use to interact with the TWiki engine and content.
7 Refer to [[EmptyPlugin]] and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.
9 Plugins should **only** use functions published in this module. If you use functions in other TWiki libraries you might create a security hole and you will probably need to change your Plugin when you upgrade TWiki.
11 Deprecated functions will still work in older code, though they should _not_ be called in new Plugins and should be replaced in older Plugins as soon as possible.
13 The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.11. This can be shown by the `%PLUGINVERSION%` TWiki variable, and accessed in code using `$TWiki::Plugins::VERSION`. The 'Since' field in the function documentation refers to `$TWiki::Plugins::VERSION`.
15 Notes on use of `$TWiki::Plugins::VERSION` (from 1.2 forwards):
17 - If the **major** version (e.g. `1.`) is the same then any plugin coded to use any **earlier** revision of the `1.` API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to **require** plugins to be recoded.
18 - If the **minor** version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, **deprecation** of functions in the interface trigger a minor version increment. Note that deprecated functions are not _removed_, they are merely frozen, and plugin authors are recommended to stop using them.
19 - Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.
20 - `TWiki::Plugins::VERSION` also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of `TWiki::Plugins::VERSION` it relates to.
22 A full history of the changes to this API can be found at the end of this topic.
26 <li><a href="#Package =TWiki::Func="> Package TWiki::Func</a><ul>
27 <li><a href="#Environment"> Environment</a><ul>
28 <li><a href="#getSkin( ) -> $skin"> getSkin( ) -> $skin</a></li>
29 <li><a href="#get_UrlHost( ) -> $host"> getUrlHost( ) -> $host</a></li>
30 <li><a href="#get_ScriptUrl( $web, $topic, $sc"> getScriptUrl( $web, $topic, $script, ... ) -> $url</a></li>
31 <li><a href="#get_ViewUrl( $web, $topic ) -> $"> getViewUrl( $web, $topic ) -> $url</a></li>
32 <li><a href="#get_PubUrlPath( ) -> $path"> getPubUrlPath( ) -> $path</a></li>
33 <li><a href="#get_ExternalResource( $url ) ->"> getExternalResource( $url ) -> $response</a></li>
34 <li><a href="#get_CgiQuery( ) -> $query"> getCgiQuery( ) -> $query</a></li>
35 <li><a href="#get_SessionKeys() -> @keys"> getSessionKeys() -> @keys</a></li>
36 <li><a href="#get_SessionValue( $key ) -> $val"> getSessionValue( $key ) -> $value</a></li>
37 <li><a href="#set_SessionValue( $key, $value )"> setSessionValue( $key, $value ) -> $boolean</a></li>
38 <li><a href="#clear_SessionValue( $key ) -> $b"> clearSessionValue( $key ) -> $boolean</a></li>
39 <li><a href="#getContext() -> \%hash"> getContext() -> \%hash</a></li>
40 <li><a href="#push_TopicContext($web, $topic)"> pushTopicContext($web, $topic)</a></li>
41 <li><a href="#pop_TopicContext()"> popTopicContext()</a></li>
44 <li><a href="#Preferences"> Preferences</a><ul>
45 <li><a href="#get_PreferencesValue( $key, $web"> getPreferencesValue( $key, $web ) -> $value</a></li>
46 <li><a href="#get_PluginPreferencesValue( $key"> getPluginPreferencesValue( $key ) -> $value</a></li>
47 <li><a href="#get_PreferencesFlag( $key, $web"> getPreferencesFlag( $key, $web ) -> $value</a></li>
48 <li><a href="#get_PluginPreferencesFlag( $key"> getPluginPreferencesFlag( $key ) -> $boolean</a></li>
49 <li><a href="#set_PreferencesValue($name, $val"> setPreferencesValue($name, $val)</a></li>
50 <li><a href="#get_WikiToolName( ) -> $name"> getWikiToolName( ) -> $name</a></li>
51 <li><a href="#get_MainWebname( ) -> $name"> getMainWebname( ) -> $name</a></li>
52 <li><a href="#get_TwikiWebname( ) -> $name"> getTwikiWebname( ) -> $name</a></li>
55 <li><a href="#User Handling and Access Control"> User Handling and Access Control</a><ul>
56 <li><a href="#get_DefaultUserName( ) -> $login"> getDefaultUserName( ) -> $loginName</a></li>
57 <li><a href="#get_CanonicalUserID( $user ) ->"> getCanonicalUserID( $user ) -> $cUID</a></li>
58 <li><a href="#get_WikiName( $user ) -> $wikiNa"> getWikiName( $user ) -> $wikiName</a></li>
59 <li><a href="#get_WikiUserName( $user ) -> $wi"> getWikiUserName( $user ) -> $wikiName</a></li>
60 <li><a href="#wiki_ToUserName( $id ) -> $login"> wikiToUserName( $id ) -> $loginName</a></li>
61 <li><a href="#user_ToWikiName( $loginName, $do"> userToWikiName( $loginName, $dontAddWeb ) -> $wikiName</a></li>
62 <li><a href="#email_ToWikiNames( $email, $dont"> emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames</a></li>
63 <li><a href="#wikiname_ToEmails( $user ) -> @e"> wikinameToEmails( $user ) -> @emails</a></li>
64 <li><a href="#isGuest( ) -> $boolean"> isGuest( ) -> $boolean</a></li>
65 <li><a href="#is_AnAdmin( $id ) -> $boolean"> isAnAdmin( $id ) -> $boolean</a></li>
66 <li><a href="#is_GroupMember( $group, $id ) ->"> isGroupMember( $group, $id ) -> $boolean</a></li>
67 <li><a href="#eachUser() -> $iterator"> eachUser() -> $iterator</a></li>
68 <li><a href="#eachMembership($id) -> $iterator"> eachMembership($id) -> $iterator</a></li>
69 <li><a href="#eachGroup() -> $iterator"> eachGroup() -> $iterator</a></li>
70 <li><a href="#isGroup( $group ) -> $boolean"> isGroup( $group ) -> $boolean</a></li>
71 <li><a href="#each_GroupMember($group) -> $ite"> eachGroupMember($group) -> $iterator</a></li>
72 <li><a href="#check_AccessPermission( $type, $"> checkAccessPermission( $type, $id, $text, $topic, $web, $meta ) -> $boolean</a></li>
75 <li><a href="#Webs, Topics and Attachments"> Webs, Topics and Attachments</a><ul>
76 <li><a href="#get_ListOfWebs( $filter ) -> @we"> getListOfWebs( $filter ) -> @webs</a></li>
77 <li><a href="#webExists( $web ) -> $boolean"> webExists( $web ) -> $boolean</a></li>
78 <li><a href="#createWeb( $newWeb, $baseWeb, $o"> createWeb( $newWeb, $baseWeb, $opts )</a></li>
79 <li><a href="#moveWeb( $oldName, $newName )"> moveWeb( $oldName, $newName )</a></li>
80 <li><a href="#each_ChangeSince($web, $time) ->"> eachChangeSince($web, $time) -> $iterator</a></li>
81 <li><a href="#get_TopicList( $web ) -> @topics"> getTopicList( $web ) -> @topics</a></li>
82 <li><a href="#topicExists( $web, $topic ) -> $"> topicExists( $web, $topic ) -> $boolean</a></li>
83 <li><a href="#check_TopicEditLock( $web, $topi"> checkTopicEditLock( $web, $topic, $script ) -> ( $oopsUrl, $loginName, $unlockTime )</a></li>
84 <li><a href="#set_TopicEditLock( $web, $topic,"> setTopicEditLock( $web, $topic, $lock )</a></li>
85 <li><a href="#saveTopic( $web, $topic, $meta,"> saveTopic( $web, $topic, $meta, $text, $options ) -> $error</a></li>
86 <li><a href="#save_TopicText( $web, $topic, $t"> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $oopsUrl</a></li>
87 <li><a href="#moveTopic( $web, $topic, $newWeb"> moveTopic( $web, $topic, $newWeb, $newTopic )</a></li>
88 <li><a href="#get_RevisionInfo($web, $topic, $"> getRevisionInfo($web, $topic, $rev, $attachment ) -> ( $date, $user, $rev, $comment ) </a></li>
89 <li><a href="#get_RevisionAtTime( $web, $topic"> getRevisionAtTime( $web, $topic, $time ) -> $rev</a></li>
90 <li><a href="#readTopic( $web, $topic, $rev )"> readTopic( $web, $topic, $rev ) -> ( $meta, $text )</a></li>
91 <li><a href="#read_TopicText( $web, $topic, $r"> readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $text</a></li>
92 <li><a href="#attachmentExists( $web, $topic,"> attachmentExists( $web, $topic, $attachment ) -> $boolean</a></li>
93 <li><a href="#readAttachment( $web, $topic, $n"> readAttachment( $web, $topic, $name, $rev ) -> $data</a></li>
94 <li><a href="#saveAttachment( $web, $topic, $a"> saveAttachment( $web, $topic, $attachment, $opts )</a></li>
95 <li><a href="#moveAttachment( $web, $topic, $a"> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )</a></li>
98 <li><a href="#Assembling Pages"> Assembling Pages</a><ul>
99 <li><a href="#readTemplate( $name, $skin ) ->"> readTemplate( $name, $skin ) -> $text</a></li>
100 <li><a href="#loadTemplate ( $name, $skin, $we"> loadTemplate ( $name, $skin, $web ) -> $text</a></li>
101 <li><a href="#expandTemplate( $def ) -> $stri"> expandTemplate( $def ) -> $string</a></li>
102 <li><a href="#writeHeader( $query, $contentLen"> writeHeader( $query, $contentLength )</a></li>
103 <li><a href="#redirect_CgiQuery( $query, $url,"> redirectCgiQuery( $query, $url, $passthru )</a></li>
104 <li><a href="#add_ToHEAD( $id, $header )"> addToHEAD( $id, $header )</a></li>
105 <li><a href="#expand_CommonVariables( $text, $"> expandCommonVariables( $text, $topic, $web, $meta ) -> $text</a></li>
106 <li><a href="#renderText( $text, $web ) -> $te"> renderText( $text, $web ) -> $text</a></li>
107 <li><a href="#internalLink( $pre, $web, $topic"> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text</a></li>
110 <li><a href="#E-mail"> E-mail</a><ul>
111 <li><a href="#sendEmail ( $text, $retries ) ->"> sendEmail ( $text, $retries ) -> $error</a></li>
112 <li><a href="#wiki_ToEmail( $wikiName ) -> $em"> wikiToEmail( $wikiName ) -> $email</a></li>
115 <li><a href="#Creating New Topics"> Creating New Topics</a><ul>
116 <li><a href="#expand_VariablesOnTopicCreation"> expandVariablesOnTopicCreation ( $text ) -> $text</a></li>
119 <li><a href="#Special handlers"> Special handlers</a><ul>
120 <li><a href="#register_TagHandler( $var, \fn,"> registerTagHandler( $var, \&fn, $syntax )</a></li>
121 <li><a href="#registerRESTHandler( $alias, \fn"> registerRESTHandler( $alias, \&fn, )</a></li>
122 <li><a href="#decode_FormatTokens($str) -> $un"> decodeFormatTokens($str) -> $unencodedString</a></li>
125 <li><a href="#Searching"> Searching</a><ul>
126 <li><a href="#search_InWebContent($searchStrin"> searchInWebContent($searchString, $web, \@topics, \%options ) -> \%map</a></li>
129 <li><a href="#Plugin-specific file handling"> Plugin-specific file handling</a><ul>
130 <li><a href="#get_WorkArea( $pluginName ) -> $"> getWorkArea( $pluginName ) -> $directorypath</a></li>
131 <li><a href="#readFile( $filename ) -> $text"> readFile( $filename ) -> $text</a></li>
132 <li><a href="#saveFile( $filename, $text )"> saveFile( $filename, $text )</a></li>
135 <li><a href="#General Utilities"> General Utilities</a><ul>
136 <li><a href="#get_RegularExpression( $name ) -"> getRegularExpression( $name ) -> $expr</a></li>
137 <li><a href="#normalize_WebTopicName($web, $to"> normalizeWebTopicName($web, $topic) -> ($web, $topic)</a></li>
140 <li><a href="#StaticMethod *sanitize_Attachmen"> StaticMethod sanitizeAttachmentName <tt>($fname) -> ($fileName,$origName)</tt></a><ul>
141 <li><a href="#space_OutWikiWord( $word, $sep )"> spaceOutWikiWord( $word, $sep ) -> $text</a></li>
142 <li><a href="#writeWarning( $text )"> writeWarning( $text )</a></li>
143 <li><a href="#writeDebug( $text )"> writeDebug( $text )</a></li>
144 <li><a href="#formatTime( $time, $format, $tim"> formatTime( $time, $format, $timezone ) -> $text</a></li>
145 <li><a href="#isTrue( $value, $default ) -> $b"> isTrue( $value, $default ) -> $boolean</a></li>
146 <li><a href="#is_ValidWikiWord ( $text ) -> $b"> isValidWikiWord ( $text ) -> $boolean</a></li>
147 <li><a href="#extractParameters($attr ) -> %pa"> extractParameters($attr ) -> %params</a></li>
148 <li><a href="#extract_NameValuePair( $attr, $n"> extractNameValuePair( $attr, $name ) -> $value</a></li>
151 <li><a href="#Deprecated functions"> Deprecated functions</a><ul>
152 <li><a href="#get_ScriptUrlPath( ) -> $path"> getScriptUrlPath( ) -> $path</a></li>
153 <li><a href="#get_OopsUrl( $web, $topic, $temp"> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url</a></li>
154 <li><a href="#permissionsSet( $web ) -> $boole"> permissionsSet( $web ) -> $boolean</a></li>
155 <li><a href="#get_PublicWebList( ) -> @webs"> getPublicWebList( ) -> @webs</a></li>
156 <li><a href="#format_GmTime( $time, $format )"> formatGmTime( $time, $format ) -> $text</a></li>
157 <li><a href="#get_DataDir( ) -> $dir"> getDataDir( ) -> $dir</a></li>
158 <li><a href="#get_PubDir( ) -> $dir"> getPubDir( ) -> $dir</a></li>
159 <li><a href="#checkDependencies( $moduleName,"> checkDependencies( $moduleName, $dependenciesRef ) -> $error</a></li>
167 ## <a name="Environment"></a> Environment
169 ### <a name="getSkin( ) - $skin"></a> getSkin( ) -> $skin
171 Get the skin path, set by the `SKIN` and `COVER` preferences variables or the `skin` and `cover` CGI parameters
173 Return: `$skin` Comma-separated list of skins, e.g. `'gnu,tartan'`. Empty string if none.
175 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
177 ### <a name="get_UrlHost( ) - $host"></a> getUrlHost( ) -> $host
179 Get protocol, domain and optional port of script URL
181 Return: `$host` URL host, e.g. `"http://example.com:80"`
183 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
185 ### <a name="get_ScriptUrl( $web, $topic, $sc"></a> getScriptUrl( $web, $topic, $script, ... ) -> $url
187 Compose fully qualified URL
189 - `$web` - Web name, e.g. `'Main'`
190 - `$topic` - Topic name, e.g. `'WebNotify'`
191 - `$script` - Script name, e.g. `'view'`
192 - `...` - an arbitrary number of name=>value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. `getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2)` will give `.../view/x/y?a=1&b=2#XXX`
194 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
196 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
198 ### <a name="get_ViewUrl( $web, $topic ) - $u"></a> getViewUrl( $web, $topic ) -> $url
200 Compose fully qualified view URL
202 - `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
203 - `$topic` - Topic name, e.g. `'WebNotify'`
205 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
207 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
209 ### <a name="get_PubUrlPath( ) - $path"></a> getPubUrlPath( ) -> $path
213 Return: `$path` URL path of pub directory, e.g. `"/pub"`
215 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
217 ### <a name="get_ExternalResource( $url ) - $"></a> getExternalResource( $url ) -> $response
219 Get whatever is at the other end of a URL (using an HTTP GET request). Will only work for encrypted protocols such as `https` if the `LWP` CPAN module is installed.
221 Note that the `$url` may have an optional user and password, as specified by the relevant RFC. Any proxy set in `configure` is honoured.
223 The `$response` is an object that is known to implement the following subset of the methods of `LWP::Response`. It may in fact be an `LWP::Response` object, but it may also not be if `LWP` is not available, so callers may only assume the following subset of methods is available:
225 <table border="1" cellpadding="0" cellspacing="0">
227 <td><code>code()</code></td>
230 <td><code>message()</code></td>
233 <td><code>header($field)</code></td>
236 <td><code>content()</code></td>
239 <td><code>is_error()</code></td>
242 <td><code>is_redirect()</code></td>
246 Note that if LWP is **not** available, this function:
248 1. can only really be trusted for HTTP/1.0 urls. If HTTP/1.1 or another protocol is required, you are **strongly** recommended to `require LWP`.
249 2. Will not parse multipart content
251 In the event of the server returning an error, then `is_error()` will return true, `code()` will return a valid HTTP status code as specified in RFC 2616 and RFC 2518, and `message()` will return the message that was received from the server. In the event of a client-side error (e.g. an unparseable URL) then `is_error()` will return true and `message()` will return an explanatory message. `code()` will return 400 (BAD REQUEST).
253 Note: Callers can easily check the availability of other HTTP::Response methods as follows:
255 my $response = TWiki::Func::getExternalResource($url);
256 if (!$response->is_error() && $response->isa('HTTP::Response')) {
257 ... other methods of HTTP::Response may be called
259 ... only the methods listed above may be called
262 **Since:** TWiki::Plugins::VERSION 1.2
264 ### <a name="get_CgiQuery( ) - $query"></a> getCgiQuery( ) -> $query
266 Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set
268 Return: `$query` CGI query object; or 0 if script is called as a shell script
270 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
272 ### <a name="get_SessionKeys() - @keys"></a> getSessionKeys() -> @keys
274 Get a list of all the names of session variables. The list is unsorted.
276 Session keys are stored and retrieved using `setSessionValue` and `getSessionValue`.
278 **Since:** TWiki::Plugins::VERSION 1.2
280 ### <a name="get_SessionValue( $key ) - $valu"></a> getSessionValue( $key ) -> $value
282 Get a session value from the client session module
284 - `$key` - Session key
286 Return: `$value` Value associated with key; empty string if not set
288 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 200)
290 ### <a name="set_SessionValue( $key, $value )"></a> setSessionValue( $key, $value ) -> $boolean
294 - `$key` - Session key
295 - `$value` - Value associated with key
297 Return: true if function succeeded
299 **Since:** TWiki::Plugins::VERSION 1.000 (17 Aug 2001)
301 ### <a name="clear_SessionValue( $key ) - $bo"></a> clearSessionValue( $key ) -> $boolean
303 Clear a session value that was set using `setSessionValue`.
305 - `$key` - name of value stored in session to be cleared. Note that you **cannot** clear `AUTHUSER`.
307 Return: true if the session value was cleared
309 **Since:** TWiki::Plugins::VERSION 1.1
311 ### <a name="getContext() - \%hash"></a> getContext() -> \\%hash
313 Get a hash of context identifiers representing the currently active context.
315 The context is a set of identifiers that are set during specific phases of TWiki processing. For example, each of the standard scripts in the 'bin' directory each has a context identifier - the view script has 'view', the edit script has 'edit' etc. So you can easily tell what 'type' of script your Plugin is being called within. The core context identifiers are listed in the %SYSTEMWEB%.IfStatements topic. Please be careful not to overwrite any of these identifiers!
317 Context identifiers can be used to communicate between Plugins, and between Plugins and templates. For example, in [[FirstPlugin]].pm, you might write:
320 TWiki::Func::getContext()->{'MyID'} = 1;
323 This can be used in SecondPlugin.pm like this:
326 if( TWiki::Func::getContext()->{'MyID'} ) {
331 or in a template, like this:
333 %TMPL:DEF{"ON"}% Not off %TMPL:END%
334 %TMPL:DEF{"OFF"}% Not on %TMPL:END%
335 %TMPL:P{context="MyID" then="ON" else="OFF"}%
339 %IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%
341 **_Note_**: **all** plugins have an **automatically generated** context identifier if they are installed and initialised. For example, if the [[FirstPlugin]] is working, the context ID 'FirstPlugin' will be set.
343 **Since:** TWiki::Plugins::VERSION 1.1
345 ### <a name="push_TopicContext($web, $topic)"></a> pushTopicContext($web, $topic)
348 - `$topic` - new topic
350 Change the TWiki context so it behaves as if it was processing `$web.$topic` from now on. All the preferences will be reset to those of the new topic. Note that if the new topic is not readable by the logged in user due to access control considerations, there will **not** be an exception. It is the duty of the caller to check access permissions before changing the topic.
352 It is the duty of the caller to restore the original context by calling `popTopicContext`.
354 Note that this call does **not** re-initialise plugins, so if you have used global variables to remember the web and topic in `initPlugin`, then those values will be unchanged.
356 **Since:** TWiki::Plugins::VERSION 1.2
358 ### <a name="pop_TopicContext()"></a> popTopicContext()
360 Returns the TWiki context to the state it was in before the `pushTopicContext` was called.
362 **Since:** TWiki::Plugins::VERSION 1.2
364 ## <a name="Preferences"></a> Preferences
366 ### <a name="get_PreferencesValue( $key, $web"></a> getPreferencesValue( $key, $web ) -> $value
368 Get a preferences value from TWiki or from a Plugin
370 - `$key` - Preferences key
371 - `$web` - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
373 Return: `$value` Preferences value; empty string if not set
375 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
377 - Example for Plugin setting:
378 - [[MyPlugin]] topic has: `* Set COLOR = red`
379 - Use `"MYPLUGIN_COLOR"` for `$key`
380 - `my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );`
382 - Example for preferences setting:
383 - [[WebPreferences]] topic has: `* Set WEBBGCOLOR = #FFFFC0`
384 - `my $webColor = TWiki::Func::getPreferencesValue( 'WEBBGCOLOR', 'Sandbox' );`
386 **NOTE:** As of TWiki4.1, if `$NO_PREFS_IN_TOPIC` is enabled in the plugin, then preferences set in the plugin topic will be ignored.
388 ### <a name="get_PluginPreferencesValue( $key"></a> getPluginPreferencesValue( $key ) -> $value
390 Get a preferences value from your Plugin
392 - `$key` - Plugin Preferences key w/o PLUGINNAME\_ prefix.
394 Return: `$value` Preferences value; empty string if not set
396 **_Note_**: This function will will **only** work when called from the Plugin.pm file itself. it **will not work** if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)
398 **Since:** TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
400 **NOTE:** As of TWiki4.1, if `$NO_PREFS_IN_TOPIC` is enabled in the plugin, then preferences set in the plugin topic will be ignored.
402 ### <a name="get_PreferencesFlag( $key, $web"></a><a name="get_PreferencesFlag( $key, $web "></a> getPreferencesFlag( $key, $web ) -> $value
404 Get a preferences flag from TWiki or from a Plugin
406 - `$key` - Preferences key
407 - `$web` - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
409 Return: `$value` Preferences flag `'1'` (if set), or `"0"` (for preferences values `"off"`, `"no"` and `"0"`)
411 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
413 - Example for Plugin setting:
414 - [[MyPlugin]] topic has: `* Set SHOWHELP = off`
415 - Use `"MYPLUGIN_SHOWHELP"` for `$key`
416 - `my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );`
418 **NOTE:** As of TWiki4.1, if `$NO_PREFS_IN_TOPIC` is enabled in the plugin, then preferences set in the plugin topic will be ignored.
420 ### <a name="get_PluginPreferencesFlag( $key"></a><a name="get_PluginPreferencesFlag( $key "></a> getPluginPreferencesFlag( $key ) -> $boolean
422 Get a preferences flag from your Plugin
424 - `$key` - Plugin Preferences key w/o PLUGINNAME\_ prefix.
426 Return: false for preferences values `"off"`, `"no"` and `"0"`, or values not set at all. True otherwise.
428 **_Note_**: This function will will **only** work when called from the Plugin.pm file itself. it **will not work** if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)
430 **Since:** TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
432 **NOTE:** As of TWiki4.1, if `$NO_PREFS_IN_TOPIC` is enabled in the plugin, then preferences set in the plugin topic will be ignored.
434 ### <a name="set_PreferencesValue($name, $val"></a> setPreferencesValue($name, $val)
436 Set the preferences value so that future calls to getPreferencesValue will return this value, and `%$name%` will expand to the preference when used in future variable expansions.
438 The preference only persists for the rest of this request. Finalised preferences cannot be redefined using this function.
440 Returns 1 if the preference was defined, and 0 otherwise.
442 ### <a name="get_WikiToolName( ) - $name"></a> getWikiToolName( ) -> $name
444 Get toolname as defined in TWiki.cfg
446 Return: `$name` Name of tool, e.g. `'TWiki'`
448 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
450 ### <a name="get_MainWebname( ) - $name"></a> getMainWebname( ) -> $name
452 Get name of Main web as defined in TWiki.cfg
454 Return: `$name` Name, e.g. `'Main'`
456 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
458 ### <a name="get_TwikiWebname( ) - $name"></a> getTwikiWebname( ) -> $name
460 Get name of TWiki documentation web as defined in TWiki.cfg
462 Return: `$name` Name, e.g. `'TWiki'`
464 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
466 ## <a name="User Handling and Access Control"></a> User Handling and Access Control
468 ### <a name="get_DefaultUserName( ) - $loginN"></a> getDefaultUserName( ) -> $loginName
470 Get default user name as defined in the configuration as `DefaultUserLogin`
472 Return: `$loginName` Default user name, e.g. `'guest'`
474 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
476 ### <a name="get_CanonicalUserID( $user ) - $"></a> getCanonicalUserID( $user ) -> $cUID
478 - `$user` can be a login, wikiname or web.wikiname
480 Return the cUID of the specified user. A cUID is a unique identifier which is assigned by TWiki for each user. BEWARE: While the default [[TWikiUserMapping]] uses a cUID that looks like a user's [[LoginName]], some characters are modified to make them compatible with rcs. Other usermappings may use other conventions - the JoomlaUserMapping for example, has cUIDs like 'JoomlaeUserMapping\_1234'.
482 If $user is undefined, it assumes the currently logged-in user.
484 Return: `$cUID`, an internal unique and portable escaped identifier for registered users. This may be autogenerated for an authenticated but unregistered user.
486 **Since:** TWiki::Plugins::VERSION 1.2
488 ### <a name="get_WikiName( $user ) - $wikiNam"></a> getWikiName( $user ) -> $wikiName
490 return the [[WikiName]] of the specified user if $user is undefined Get Wiki name of logged in user
492 - $user can be a cUID, login, wikiname or web.wikiname
494 Return: `$wikiName` Wiki Name, e.g. `'JohnDoe'`
496 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
498 ### <a name="get_WikiUserName( $user ) - $wik"></a> getWikiUserName( $user ) -> $wikiName
500 return the userWeb.WikiName of the specified user if $user is undefined Get Wiki name of logged in user
502 - $user can be a cUID, login, wikiname or web.wikiname
504 Return: `$wikiName` Wiki Name, e.g. `"Main.JohnDoe"`
506 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
508 ### <a name="wiki_ToUserName( $id ) - $loginN"></a> wikiToUserName( $id ) -> $loginName
510 Translate a Wiki name to a login name.
512 - `$id` - Wiki name, e.g. `'Main.JohnDoe'` or `'JohnDoe'`. Since TWiki 4.2.1, $id may also be a login name. This will normally be transparent, but should be borne in mind if you have login names that are also legal wiki names.
514 Return: `$loginName` Login name of user, e.g. `'jdoe'`, or undef if not matched.
516 Note that it is possible for several login names to map to the same wikiname. This function will only return the **first** login name that maps to the wikiname.
518 returns undef if the [[WikiName]] is not found.
520 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
522 ### <a name="user_ToWikiName( $loginName, $do"></a> userToWikiName( $loginName, $dontAddWeb ) -> $wikiName
524 Translate a login name to a Wiki name
526 - `$loginName` - Login name, e.g. `'jdoe'`. Since TWiki 4.2.1 this may also be a wiki name. This will normally be transparent, but may be relevant if you have login names that are also valid wiki names.
527 - `$dontAddWeb` - Do not add web prefix if `"1"`
529 Return: `$wikiName` Wiki name of user, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
531 userToWikiName will always return a name. If the user does not exist in the mapping, the $loginName parameter is returned. (backward compatibility)
533 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
535 ### <a name="email_ToWikiNames( $email, $dont"></a> emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames
537 - `$email` - email address to look up
538 - `$dontAddWeb` - Do not add web prefix if `"1"`
540 Find the wikinames of all users who have the given email address as their registered address. Since several users could register with the same email address, this returns a list of wikinames rather than a single wikiname.
542 **Since:** TWiki::Plugins::VERSION 1.2
544 ### <a name="wikiname_ToEmails( $user ) - @em"></a> wikinameToEmails( $user ) -> @emails
546 - `$user` - wikiname of user to look up
548 Returns the registered email addresses of the named user. If $user is undef, returns the registered email addresses for the logged-in user.
550 Since TWiki 4.2.1, $user may also be a login name, or the name of a group.
552 **Since:** TWiki::Plugins::VERSION 1.2
554 ### <a name="isGuest( ) - $boolean"></a> isGuest( ) -> $boolean
556 Test if logged in user is a guest ([[TWikiGuest]])
558 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
560 ### <a name="is_AnAdmin( $id ) - $boolean"></a> isAnAdmin( $id ) -> $boolean
562 Find out if the user is an admin or not. If the user is not given, the currently logged-in user is assumed.
564 - $id can be either a login name or a [[WikiName]]
566 **Since:** TWiki::Plugins::VERSION 1.2
568 ### <a name="is_GroupMember( $group, $id ) -"></a><a name="is_GroupMember( $group, $id ) - "></a> isGroupMember( $group, $id ) -> $boolean
570 Find out if $id is in the named group. e.g.
572 if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) {
576 If `$user` is `undef`, it defaults to the currently logged-in user.
578 - $id can be a login name or a [[WikiName]]
580 **Since:** TWiki::Plugins::VERSION 1.2
582 ### <a name="eachUser() - $iterator"></a> eachUser() -> $iterator
584 Get an iterator over the list of all the registered users **not** including groups. The iterator will return each wiki name in turn (e.g. 'FredBloggs').
588 my $iterator = TWiki::Func::eachUser();
589 while ($it->hasNext()) {
590 my $user = $it->next();
591 # $user is a wikiname
594 **WARNING** on large sites, this could be a long list!
596 **Since:** TWiki::Plugins::VERSION 1.2
598 ### <a name="eachMembership($id) - $iterator"></a> eachMembership($id) -> $iterator
600 - `$id` - [[WikiName]] or login name of the user. If `$id` is `undef`, defaults to the currently logged-in user.
602 Get an iterator over the names of all groups that the user is a member of.
604 **Since:** TWiki::Plugins::VERSION 1.2
606 ### <a name="eachGroup() - $iterator"></a> eachGroup() -> $iterator
608 Get an iterator over all groups.
612 my $iterator = TWiki::Func::eachGroup();
613 while ($it->hasNext()) {
614 my $group = $it->next();
615 # $group is a group name e.g. TWikiAdminGroup
618 **WARNING** on large sites, this could be a long list!
620 **Since:** TWiki::Plugins::VERSION 1.2
622 ### <a name="isGroup( $group ) - $boolean"></a> isGroup( $group ) -> $boolean
624 Checks if `$group` is the name of a group known to TWiki.
626 ### <a name="each_GroupMember($group) - $iter"></a> eachGroupMember($group) -> $iterator
628 Get an iterator over all the members of the named group. Returns undef if $group is not a valid group.
632 my $iterator = TWiki::Func::eachGroupMember('RadioheadGroup');
633 while ($it->hasNext()) {
634 my $user = $it->next();
635 # $user is a wiki name e.g. 'TomYorke', 'PhilSelway'
638 **WARNING** on large sites, this could be a long list!
640 **Since:** TWiki::Plugins::VERSION 1.2
642 ### <a name="check_AccessPermission( $type, $"></a> checkAccessPermission( $type, $id, $text, $topic, $web, $meta ) -> $boolean
644 Check access permission for a topic based on the [[%SYSTEMWEB%.TWikiAccessControl|SYSTEMWEB/TWikiAccessControl]] rules
646 - `$type` - Access type, required, e.g. `'VIEW'`, `'CHANGE'`.
647 - `$id` - [[WikiName]] of remote user, required, e.g. `"PeterThoeny"`. From TWiki 4.2.1, $id may also be a login name. If `$id` is '', 0 or `undef` then access is **always permitted**.
648 - `$text` - Topic text, optional. If 'perl false' (undef, 0 or ''), topic `$web.$topic` is consulted. `$text` may optionally contain embedded `%META:PREFERENCE` tags. Provide this parameter if:
649 1. You are setting different access controls in the text to those defined in the stored topic,
650 2. You already have the topic text in hand, and want to help TWiki avoid having to read it again,
651 3. You are providing a `$meta` parameter.
652 - `$topic` - Topic name, required, e.g. `'PrivateStuff'`
653 - `$web` - Web name, required, e.g. `'Sandbox'`
654 - `$meta` - Meta-data object, as returned by `readTopic`. Optional. If `undef`, but `$text` is defined, then access controls will be parsed from `$text`. If defined, then metadata embedded in `$text` will be ignored. This parameter is always ignored if `$text` is undefined. Settings in `$meta` override `Set` settings in $text.
656 A perl true result indicates that access is permitted.
658 **Note** the weird parameter order is due to compatibility constraints with earlier TWiki releases.
660 **Tip** if you want, you can use this method to check your own access control types. For example, if you:
662 - Set ALLOWTOPICSPIN = [[IncyWincy]]
664 in `ThatWeb.ThisTopic`, then a call to `checkAccessPermissions('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)` will return `true`.
666 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
668 ## <a name="Webs, Topics and Attachments"></a> Webs, Topics and Attachments
670 ### <a name="get_ListOfWebs( $filter ) - @web"></a> getListOfWebs( $filter ) -> @webs
672 - `$filter` - spec of web types to recover
674 Gets a list of webs, filtered according to the spec in the $filter, which may include one of:
676 1. 'user' (for only user webs)
677 2. 'template' (for only template webs i.e. those starting with "\_")
679 `$filter` may also contain the word 'public' which will further filter out webs that have NOSEARCHALL set on them. 'allowed' filters out webs the current user can't read.
681 For example, the deprecated getPublicWebList function can be duplicated as follows:
683 my @webs = TWiki::Func::getListOfWebs( "user,public" );
685 **Since:** TWiki::Plugins::VERSION 1.1
687 ### <a name="webExists( $web ) - $boolean"></a> webExists( $web ) -> $boolean
691 - `$web` - Web name, required, e.g. `'Sandbox'`
693 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
695 ### <a name="createWeb( $newWeb, $baseWeb, $o"></a> createWeb( $newWeb, $baseWeb, $opts )
697 - `$newWeb` is the name of the new web.
698 - `$baseWeb` is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.
699 - `$opts` is a ref to a hash that contains settings to be modified in
701 the web preferences topic in the new web.
703 use Error qw( :try );
704 use TWiki::AccessControlException;
707 TWiki::Func::createWeb( "Newweb" );
708 } catch Error::Simple with {
710 # see documentation on Error::Simple
711 } catch TWiki::AccessControlException with {
713 # see documentation on TWiki::AccessControlException
718 **Since:** TWiki::Plugins::VERSION 1.1
720 ### <a name="moveWeb( $oldName, $newName )"></a> moveWeb( $oldName, $newName )
724 use Error qw( :try );
725 use TWiki::AccessControlException;
728 TWiki::Func::moveWeb( "Oldweb", "Newweb" );
729 } catch Error::Simple with {
731 # see documentation on Error::Simple
732 } catch TWiki::AccessControlException with {
734 # see documentation on TWiki::AccessControlException
739 To delete a web, move it to a subweb of `Trash`
741 TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );
743 **Since:** TWiki::Plugins::VERSION 1.1
745 ### <a name="each_ChangeSince($web, $time) -"></a><a name="each_ChangeSince($web, $time) - "></a> eachChangeSince($web, $time) -> $iterator
747 Get an iterator over the list of all the changes in the given web between `$time` and now. $time is a time in seconds since 1st Jan 1970, and is not guaranteed to return any changes that occurred before (now - \{Store\}\{RememberChangesFor\}). \{Store\}\{RememberChangesFor\}) is a setting in `configure`. Changes are returned in **most-recent-first** order.
751 my $iterator = TWiki::Func::eachChangeSince(
752 $web, time() - 7 * 24 * 60 * 60); # the last 7 days
753 while ($iterator->hasNext()) {
754 my $change = $iterator->next();
755 # $change is a perl hash that contains the following fields:
756 # topic => topic name
757 # user => wikiname - wikiname of user who made the change
758 # time => time of the change
759 # revision => revision number *after* the change
760 # more => more info about the change (e.g. 'minor')
763 ### <a name="get_TopicList( $web ) - @topics"></a> getTopicList( $web ) -> @topics
765 Get list of all topics in a web
767 - `$web` - Web name, required, e.g. `'Sandbox'`
769 Return: `@topics` Topic list, e.g. `( 'WebChanges', 'WebHome', 'WebIndex', 'WebNotify' )`
771 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
773 ### <a name="topicExists( $web, $topic ) - $b"></a> topicExists( $web, $topic ) -> $boolean
777 - `$web` - Web name, optional, e.g. `'Main'`.
778 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`, or `"Main.TokyoOffice"`
780 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`. Specifically, the %USERSWEB% is used if $web is not specified and $topic has no web specifier. To get an expected behaviour it is recommened to specify the current web for $web; don't leave it empty.
782 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
784 ### <a name="check_TopicEditLock( $web, $topi"></a> checkTopicEditLock( $web, $topic, $script ) -> ( $oopsUrl, $loginName, $unlockTime )
786 Check if a lease has been taken by some other user.
788 - `$web` Web name, e.g. `"Main"`, or empty
789 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
791 Return: `( $oopsUrl, $loginName, $unlockTime )` - The `$oopsUrl` for calling redirectCgiQuery(), user's `$loginName`, and estimated `$unlockTime` in minutes, or ( '', '', 0 ) if no lease exists.
793 - `$script` The script to invoke when continuing with the edit
795 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
797 ### <a name="set_TopicEditLock( $web, $topic,"></a> setTopicEditLock( $web, $topic, $lock )
799 - `$web` Web name, e.g. `"Main"`, or empty
800 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
801 - `$lock` 1 to lease the topic, 0 to clear an existing lease
803 Takes out a "lease" on the topic. The lease doesn't prevent anyone from editing and changing the topic, but it does redirect them to a warning screen, so this provides some protection. The `edit` script always takes out a lease.
805 It is **impossible** to fully lock a topic. Concurrent changes will be merged.
807 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
809 ### <a name="saveTopic( $web, $topic, $meta,"></a><a name="saveTopic( $web, $topic, $meta, "></a> saveTopic( $web, $topic, $meta, $text, $options ) -> $error
811 - `$web` - web for the topic
812 - `$topic` - topic name
813 - `$meta` - reference to TWiki::Meta object
814 - `$text` - text of the topic (without embedded meta-data!!!
815 - `\%options` - ref to hash of save options `\%options` may include: <table border="1" cellpadding="0" cellspacing="0">
817 <td><code>dontlog</code></td>
818 <td> don't log this change in twiki log </td>
821 <td><code>forcenewrevision</code></td>
822 <td> force the save to increment the revision counter </td>
825 <td><code>minor</code></td>
826 <td> True if this is a minor change, and is not to be notified </td>
830 Return: error message or undef.
832 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
836 my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic )
837 $text =~ s/APPLE/ORANGE/g;
838 TWiki::Func::saveTopic( $web, $topic, $meta, $text, { forcenewrevision => 1 } );
840 **_Note:_** Plugins handlers ( e.g. `beforeSaveHandler` ) will be called as appropriate.
842 ### <a name="save_TopicText( $web, $topic, $t"></a> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $oopsUrl
844 Save topic text, typically obtained by readTopicText(). Topic data usually includes meta data; the file attachment meta data is replaced by the meta data from the topic file if it exists.
846 - `$web` - Web name, e.g. `'Main'`, or empty
847 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
848 - `$text` - Topic text to save, assumed to include meta data
849 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK
850 - `$dontNotify` - Set to `"1"` if not to notify users of the change
852 Return: `$oopsUrl` Empty string if OK; the `$oopsUrl` for calling redirectCgiQuery() in case of error
854 This method is a lot less efficient and much more dangerous than `saveTopic`.
856 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
858 my $text = TWiki::Func::readTopicText( $web, $topic );
860 # check for oops URL in case of error:
861 if( $text =~ /^http.*?\/oops/ ) {
862 TWiki::Func::redirectCgiQuery( $query, $text );
865 # do topic text manipulation like:
866 $text =~ s/old/new/g;
867 # do meta data manipulation like:
868 $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
869 $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
871 ### <a name="moveTopic( $web, $topic, $newWeb"></a> moveTopic( $web, $topic, $newWeb, $newTopic )
873 - `$web` source web - required
874 - `$topic` source topic - required
876 - `$newTopic` dest topic
878 Renames the topic. Throws an exception if something went wrong. If $newWeb is undef, it defaults to $web. If $newTopic is undef, it defaults to $topic.
880 The destination topic must not already exist.
882 Rename a topic to the $TWiki::cfg\{TrashWebName\} to delete it.
884 **Since:** TWiki::Plugins::VERSION 1.1
886 use Error qw( :try );
889 moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
890 } catch Error::Simple with {
892 # see documentation on Error::Simple
893 } catch TWiki::AccessControlException with {
895 # see documentation on TWiki::AccessControlException
900 ### <a name="get_RevisionInfo($web, $topic, $"></a> getRevisionInfo($web, $topic, $rev, $attachment ) -> ( $date, $user, $rev, $comment )
902 Get revision info of a topic or attachment
904 - `$web` - Web name, optional, e.g. `'Main'`
905 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
906 - `$rev` - revsion number, or tag name (can be in the format 1.2, or just the minor number)
907 - `$attachment` -attachment filename
909 Return: `( $date, $user, $rev, $comment )` List with: ( last update date, login name of last user, minor part of top revision number ), e.g. `( 1234561, 'phoeny', "5" )`
911 <table border="1" cellpadding="0" cellspacing="0">
914 <td> in epochSec </td>
918 <td> Wiki name of the author (<strong>not</strong> login name) </td>
922 <td> actual rev number </td>
926 <td> WHAT COMMENT? </td>
930 NOTE: if you are trying to get revision info for a topic, use `$meta->getRevisionInfo` instead if you can - it is significantly more efficient.
932 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
934 ### <a name="get_RevisionAtTime( $web, $topic"></a> getRevisionAtTime( $web, $topic, $time ) -> $rev
936 Get the revision number of a topic at a specific time.
938 - `$web` - web for topic
940 - `$time` - time (in epoch secs) for the rev
942 Return: Single-digit revision number, or undef if it couldn't be determined (either because the topic isn't that old, or there was a problem)
944 **Since:** TWiki::Plugins::VERSION 1.1
946 ### <a name="readTopic( $web, $topic, $rev )"></a><a name="readTopic( $web, $topic, $rev ) "></a> readTopic( $web, $topic, $rev ) -> ( $meta, $text )
948 Read topic text and meta data, regardless of access permissions.
950 - `$web` - Web name, required, e.g. `'Main'`
951 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
952 - `$rev` - revision to read (default latest)
954 Return: `( $meta, $text )` Meta data object and topic text
956 `$meta` is a perl 'object' of class `TWiki::Meta`. This class is fully documented in the source code documentation shipped with the release, or can be inspected in the `lib/TWiki/Meta.pm` file.
958 This method **ignores** topic access permissions. You should be careful to use `checkAccessPermissions` to ensure the current user has read access to the topic.
960 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
962 ### <a name="read_TopicText( $web, $topic, $r"></a> readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $text
964 Read topic text, including meta data
966 - `$web` - Web name, e.g. `'Main'`, or empty
967 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
968 - `$rev` - Topic revision to read, optional. Specify the minor part of the revision, e.g. `"5"`, not `"1.5"`; the top revision is returned if omitted or empty.
969 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
971 Return: `$text` Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
973 This method is more efficient than `readTopic`, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer.
975 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
977 ### <a name="attachmentExists( $web, $topic,"></a><a name="attachmentExists( $web, $topic, "></a> attachmentExists( $web, $topic, $attachment ) -> $boolean
979 Test if attachment exists
981 - `$web` - Web name, optional, e.g. `Main`.
982 - `$topic` - Topic name, required, e.g. `TokyoOffice`, or `Main.TokyoOffice`
983 - `$attachment` - attachment name, e.g.=logo.gif=
985 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
987 **Since:** TWiki::Plugins::VERSION 1.1
989 ### <a name="readAttachment( $web, $topic, $n"></a> readAttachment( $web, $topic, $name, $rev ) -> $data
991 - `$web` - web for topic
993 - `$name` - attachment name
994 - `$rev` - revision to read (default latest)
996 Read an attachment from the store for a topic, and return it as a string. The names of attachments on a topic can be recovered from the meta-data returned by `readTopic`. If the attachment does not exist, or cannot be read, undef will be returned. If the revision is not specified, the latest version will be returned.
998 View permission on the topic is required for the read to be successful. Access control violations are flagged by a TWiki::AccessControlException. Permissions are checked for the current user.
1000 my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic );
1001 my @attachments = $meta->find( 'FILEATTACHMENT' );
1002 foreach my $a ( @attachments ) {
1004 my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} );
1006 } catch TWiki::AccessControlException with {
1010 **Since:** TWiki::Plugins::VERSION 1.1
1012 ### <a name="saveAttachment( $web, $topic, $a"></a> saveAttachment( $web, $topic, $attachment, $opts )
1014 - `$web` - web for topic
1015 - `$topic` - topic to atach to
1016 - `$attachment` - name of the attachment
1017 - `$opts` - Ref to hash of options
1019 `$opts` may include:
1021 <table border="1" cellpadding="0" cellspacing="0">
1023 <td><code>dontlog</code></td>
1024 <td> don't log this change in twiki log </td>
1027 <td><code>comment</code></td>
1028 <td> comment for save </td>
1031 <td><code>hide</code></td>
1032 <td> if the attachment is to be hidden in normal topic view </td>
1035 <td><code>stream</code></td>
1036 <td> Stream of file to upload </td>
1039 <td><code>file</code></td>
1040 <td> Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. </td>
1043 <td><code>filepath</code></td>
1044 <td> Client path to file </td>
1047 <td><code>filesize</code></td>
1048 <td> Size of uploaded data </td>
1051 <td><code>filedate</code></td>
1056 Save an attachment to the store for a topic. On success, returns undef. If there is an error, an exception will be thrown.
1059 TWiki::Func::saveAttachment( $web, $topic, 'image.gif',
1060 { file => 'image.gif',
1061 comment => 'Picture of Health',
1063 } catch Error::Simple with {
1064 # see documentation on Error
1069 **Since:** TWiki::Plugins::VERSION 1.1
1071 ### <a name="moveAttachment( $web, $topic, $a"></a> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )
1073 - `$web` source web - required
1074 - `$topic` source topic - required
1075 - `$attachment` source attachment - required
1076 - `$newWeb` dest web
1077 - `$newTopic` dest topic
1078 - `$newAttachment` dest attachment
1080 Renames the topic. Throws an exception on error or access violation. If $newWeb is undef, it defaults to $web. If $newTopic is undef, it defaults to $topic. If $newAttachment is undef, it defaults to $attachment. If all of $newWeb, $newTopic and $newAttachment are undef, it is an error.
1082 The destination topic must already exist, but the destination attachment must **not** exist.
1084 Rename an attachment to $TWiki::cfg\{TrashWebName\}.TrashAttament to delete it.
1086 use Error qw( :try );
1089 # move attachment between topics
1090 moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat",
1091 "Countries", "France" );
1092 # Note destination attachment name is defaulted to the same as source
1093 } catch TWiki::AccessControlException with {
1095 # see documentation on TWiki::AccessControlException
1096 } catch Error::Simple with {
1098 # see documentation on Error::Simple
1101 **Since:** TWiki::Plugins::VERSION 1.1
1103 ## <a name="Assembling Pages"></a> Assembling Pages
1105 ### <a name="readTemplate( $name, $skin ) - $"></a> readTemplate( $name, $skin ) -> $text
1107 Read a template or skin. Embedded [[template directives|SYSTEMWEB/TWikiTemplates]] get expanded
1109 - `$name` - Template name, e.g. `'view'`
1110 - `$skin` - Comma-separated list of skin names, optional, e.g. `'print'`
1112 Return: `$text` Template text
1114 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1116 ### <a name="loadTemplate ( $name, $skin, $we"></a> loadTemplate ( $name, $skin, $web ) -> $text
1118 - `$name` - template file name
1119 - `$skin` - comma-separated list of skins to use (default: current skin)
1120 - `$web` - the web to look in for topics that contain templates (default: current web)
1122 Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)
1124 **Since:** TWiki::Plugins::VERSION 1.1
1126 Reads a template and extracts template definitions, adding them to the list of loaded templates, overwriting any previous definition.
1128 How TWiki searches for templates is described in [[TWikiTemplates]].
1130 If template text is found, extracts include statements and fully expands them.
1132 ### <a name="expandTemplate( $def ) - $strin"></a> expandTemplate( $def ) -> $string
1134 Do a , only expanding the template (not expanding any variables other than %TMPL)
1136 - `$def` - template name
1138 Return: the text of the expanded template
1140 **Since:** TWiki::Plugins::VERSION 1.1
1142 A template is defined using a %TMPL:DEF% statement in a template file. See the documentation on TWiki templates for more information.
1144 ### <a name="writeHeader( $query, $contentLen"></a> writeHeader( $query, $contentLength )
1146 Prints a basic content-type HTML header for text/html to standard out
1148 - `$query` - CGI query object. If not given, the default CGI query will be used (optional, in most cases you should _not_ pass this parameter)
1149 - `$contentLength` - Length of content (optional, in most cases you should _not_ pass this parameter)
1153 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1155 ### <a name="redirect_CgiQuery( $query, $url,"></a> redirectCgiQuery( $query, $url, $passthru )
1159 - `$query` - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
1160 - `$url` - URL to redirect to
1161 - `$passthru` - enable passthrough.
1165 Print output to STDOUT that will cause a 302 redirect to a new URL. Nothing more should be printed to STDOUT after this method has been called.
1167 The `$passthru` parameter allows you to pass the parameters that were passed to the current query on to the target URL, as long as it is another URL on the same TWiki installation. If `$passthru` is set to a true value, then TWiki will save the current URL parameters, and then try to restore them on the other side of the redirect. Parameters are stored on the server in a cache file.
1169 Note that if `$passthru` is set, then any parameters in `$url` will be lost when the old parameters are restored. if you want to change any parameter values, you will need to do that in the current CGI query before redirecting e.g.
1171 my $query = TWiki::Func::getCgiQuery();
1172 $query->param(-name => 'text', -value => 'Different text');
1173 TWiki::Func::redirectCgiQuery(
1174 undef, TWiki::Func::getScriptUrl($web, $topic, 'edit'), 1);
1176 `$passthru` does nothing if `$url` does not point to a script in the current TWiki installation.
1178 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1180 ### <a name="add_ToHEAD( $id, $header )"></a> addToHEAD( $id, $header )
1182 Adds `$header` to the HTML header (the
1184 tag). This is useful for Plugins that want to include some javascript custom css.
1186 - `$id` - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN\_JSCALENDAR)
1187 - `$header` - the HTML to be added to the
1189 section. The HTML must be valid in a HEAD tag - no checks are performed.
1191 All TWiki variables present in `$header` will be expanded before being inserted into the ``
1195 Note that this is _not_ the same as the HTTP header, which is modified through the Plugins `modifyHeaderHandler`.
1197 **Since:** TWiki::Plugins::VERSION 1.1
1201 TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')
1203 ### <a name="expand_CommonVariables( $text, $"></a> expandCommonVariables( $text, $topic, $web, $meta ) -> $text
1205 Expand all common `%VARIABLES%`
1207 - `$text` - Text with variables to expand, e.g. `'Current user is %WIKIUSER%'`
1208 - `$topic` - Current topic name, e.g. `'WebNotify'`
1209 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
1210 - `$meta` - topic meta-data to use while expanding (Since TWiki::Plugins::VERSION 1.2)
1212 Return: `$text` Expanded text, e.g. `'Current user is TWikiGuest'`
1214 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1216 See also: expandVariablesOnTopicCreation
1218 ### <a name="renderText( $text, $web ) - $tex"></a> renderText( $text, $web ) -> $text
1220 Render text from TWiki markup into XHTML as defined in [[%SYSTEMWEB%.TextFormattingRules|SYSTEMWEB/TextFormattingRules]]
1222 - `$text` - Text to render, e.g. `'*bold* text and =fixed font='`
1223 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
1225 Return: `$text` XHTML text, e.g. `'<b>bold</b> and <code>fixed font</code>'`
1227 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1229 ### <a name="internalLink( $pre, $web, $topic"></a> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text
1231 Render topic name and link label into an XHTML link. Normally you do not need to call this funtion, it is called internally by `renderText()`
1233 - `$pre` - Text occuring before the TWiki link syntax, optional
1234 - `$web` - Web name, required, e.g. `'Main'`
1235 - `$topic` - Topic name to link to, required, e.g. `'WebNotify'`
1236 - `$label` - Link label, required. Usually the same as `$topic`, e.g. `'notify'`
1237 - `$anchor` - Anchor, optional, e.g. `'#Jump'`
1238 - `$createLink` - Set to `'1'` to add question linked mark after topic name if topic does not exist;<br /> set to `'0'` to suppress link for non-existing topics
1240 Return: `$text` XHTML anchor, e.g. `'<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'`
1242 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1244 ## <a name="E-mail"></a> E-mail
1246 ### <a name="sendEmail ( $text, $retries ) -"></a><a name="sendEmail ( $text, $retries ) - "></a> sendEmail ( $text, $retries ) -> $error
1248 - `$text` - text of the mail, including MIME headers
1249 - `$retries` - number of times to retry the send (default 1)
1251 Send an e-mail specified as MIME format content. To specify MIME format mails, you create a string that contains a set of header lines that contain field definitions and a message body such as:
1253 To: liz@windsor.gov.uk
1254 From: serf@hovel.net
1255 CC: george@whitehouse.gov
1260 Please abolish the monarchy (with King George's permission, of course)
1266 Leave a blank line between the last header field and the message body.
1268 **Since:** TWiki::Plugins::VERSION 1.1
1270 ### <a name="wiki_ToEmail( $wikiName ) - $ema"></a> wikiToEmail( $wikiName ) -> $email
1272 - `$wikiname` - wiki name of the user
1274 Get the e-mail address(es) of the named user. If the user has multiple e-mail addresses (for example, the user is a group), then the list will be comma-separated.
1276 **Since:** TWiki::Plugins::VERSION 1.1
1278 **Deprecated** in favour of wikinameToEmails, because this function only returns a single email address, where a user may in fact have several.
1280 Since TWiki 4.2.1, $wikiName may also be a login name.
1282 ## <a name="Creating New Topics"></a> Creating New Topics
1284 ### <a name="expand_VariablesOnTopicCreation"></a><a name="expand_VariablesOnTopicCreation "></a> expandVariablesOnTopicCreation ( $text ) -> $text
1286 Expand the limited set of variables that are always expanded during topic creation
1288 - `$text` - the text to process
1290 Return: text with variables expanded
1292 **Since:** TWiki::Plugins::VERSION 1.1
1294 Expands only the variables expected in templates that must be statically expanded in new content.
1296 The expanded variables are:
1298 - `%DATE%` Signature-format date
1299 - `%SERVERTIME%` See [[TWikiVariables]]
1300 - `%GMTIME%` See [[TWikiVariables]]
1301 - `%USERNAME%` Base login name
1302 - `%WIKINAME%` Wiki name
1303 - `%WIKIUSERNAME%` Wiki name with prepended web
1304 - `%URLPARAM{...}%` - Parameters to the current CGI query
1307 See also: expandVariables
1309 ## <a name="Special handlers"></a> Special handlers
1311 Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.
1313 ### <a name="register_TagHandler( $var, \fn,"></a><a name="register_TagHandler( $var, \fn, "></a> registerTagHandler( $var, \\&fn, $syntax )
1315 Should only be called from initPlugin.
1317 Register a function to handle a simple variable. Handles both %VAR% and %VAR\{...\}%. Registered variables are treated the same as TWiki internal variables, and are expanded at the same time. This is a _lot_ more efficient than using the `commonTagsHandler`.
1319 - `$var` - The name of the variable, i.e. the 'MYVAR' part of %MYVAR%. The variable name **must** match /^[A-Z]\[A-Z0-9\_]\*$/ or it won't work.
1320 - `\&fn` - Reference to the handler function.
1321 - `$syntax` can be 'classic' (the default) or 'context-free'. 'classic' syntax is appropriate where you want the variable to support classic TWiki syntax i.e. to accept the standard `%MYVAR{ "unnamed" param1="value1" param2="value2" }%` syntax, as well as an unquoted default parameter, such as `%MYVAR{unquoted parameter}%`. If your variable will only use named parameters, you can use 'context-free' syntax, which supports a more relaxed syntax. For example, %MYVAR\{param1=value1, value 2, param3="value 3", param4='value 5"\}%
1323 **Since:** TWiki::Plugins::VERSION 1.1
1325 The variable handler function must be of the form:
1327 sub handler(\%session, \%params, $topic, $web)
1331 - `\%session` - a reference to the TWiki session object (may be ignored)
1332 - `\%params` - a reference to a TWiki::Attrs object containing parameters. This can be used as a simple hash that maps parameter names to values, with \_DEFAULT being the name for the default parameter.
1333 - `$topic` - name of the topic in the query
1334 - `$web` - name of the web in the query
1336 for example, to execute an arbitrary command on the server, you might do this:
1339 TWiki::Func::registerTagHandler('EXEC', \&boo);
1343 my( $session, $params, $topic, $web ) = @_;
1344 my $cmd = $params->{_DEFAULT};
1346 return "NO COMMAND SPECIFIED" unless $cmd;
1348 my $result = `$cmd 2>&1`;
1349 return $params->{silent} ? '' : $result;
1353 would let you do this: `%EXEC{"ps -Af" silent="on"}%`
1355 Registered tags differ from tags implemented using the old TWiki approach (text substitution in `commonTagsHandler`) in the following ways:
1357 - registered tags are evaluated at the same time as system tags, such as %SERVERTIME. `commonTagsHandler` is only called later, when all system tags have already been expanded (though they are expanded _again_ after `commonTagsHandler` returns).
1358 - registered tag names can only contain alphanumerics and \_ (underscore)
1359 - registering a tag `FRED` defines both `%FRED{...}%` **and also** `%FRED%`.
1360 - registered tag handlers **cannot** return another tag as their only result (e.g. `return '%SERVERTIME%';`). It won't work.
1362 ### <a name="registerRESTHandler( $alias, \fn"></a> registerRESTHandler( $alias, \\&fn, )
1364 Should only be called from initPlugin.
1366 Adds a function to the dispatch table of the REST interface
1368 - `$alias` - The name .
1369 - `\&fn` - Reference to the function.
1371 **Since:** TWiki::Plugins::VERSION 1.1
1373 The handler function must be of the form:
1375 sub handler(\%session)
1379 - `\%session` - a reference to the TWiki session object (may be ignored)
1381 From the REST interface, the name of the plugin must be used as the subject of the invokation.
1387 The [[EmptyPlugin]] has the following call in the initPlugin handler:
1389 TWiki::Func::registerRESTHandler('example', \&restExample);
1391 This adds the `restExample` function to the REST dispatch table for the [[EmptyPlugin]] under the 'example' alias, and allows it to be invoked using the URL
1393 `http://server:port/bin/rest/EmptyPlugin/example`
1397 `http://server:port/bin/rest/EmptyPlugin/restExample`
1399 (ie, with the name of the function instead of the alias) will not work.
1401 ### <a name="decode_FormatTokens($str) - $une"></a> decodeFormatTokens($str) -> $unencodedString
1403 TWiki has an informal standard set of tokens used in `format` parameters that are used to block evaluation of paramater strings. For example, if you were to write
1405 `%MYTAG{format="%WURBLE%"}%`
1407 then %WURBLE would be expanded **before** %MYTAG is evaluated. To avoid this TWiki uses escapes in the format string. For example:
1409 `%MYTAG{format="$percntWURBLE$percnt"}%`
1411 This lets you enter arbitrary strings into parameters without worrying that TWiki will expand them before your plugin gets a chance to deal with them properly. Once you have processed your tag, you will want to expand these tokens to their proper value. That's what this function does.
1413 <table border="1" cellpadding="0" cellspacing="0">
1415 <th bgcolor="#99CCCC"><strong> Escape: </strong></th>
1416 <th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
1419 <td><code>$n</code> or <code>$n()</code></td>
1420 <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
1423 <td><code>$nop</code> or <code>$nop()</code></td>
1424 <td> Is a "no operation". </td>
1427 <td><code>$quot</code></td>
1428 <td> Double quote (<code>"</code>) </td>
1431 <td><code>$percnt</code></td>
1432 <td> Percent sign (<code>%</code>) </td>
1435 <td><code>$dollar</code></td>
1436 <td> Dollar sign (<code>$</code>) </td>
1440 Note thath $quot, $percnt and $dollar all work \*even if they are followed by alphanumeric characters\*. You have been warned!
1442 **Since:** TWiki::Plugins::VERSION 1.2
1444 ## <a name="Searching"></a> Searching
1446 ### <a name="search_InWebContent($searchStrin"></a> searchInWebContent($searchString, $web, \\@topics, \\%options ) -> \\%map
1448 Search for a string in the content of a web. The search is over all content, including meta-data. Meta-data matches will be returned as formatted lines within the topic content (meta-data matches are returned as lines of the format %META:\\w+\{.\*\}%)
1450 - `$searchString` - the search string, in egrep format
1451 - `$web` - The web to search in
1452 - `\@topics` - reference to a list of topics to search
1453 - `\%option` - reference to an options hash
1455 The `\%options` hash may contain the following options:
1457 - `type` - if `regex` will perform a egrep-syntax RE search (default '')
1458 - `casesensitive` - false to ignore case (defaulkt true)
1459 - `files_without_match` - true to return files only (default false). If `files_without_match` is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).
1461 The return value is a reference to a hash which maps each matching topic name to a list of the lines in that topic that matched the search, as would be returned by 'grep'.
1463 To iterate over the returned topics use:
1465 my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics,
1466 { casesensitive => 0, files_without_match => 0 } );
1467 foreach my $topic (keys %$result ) {
1468 foreach my $matching_line ( @{$result->{$topic}} ) {
1471 **Since:** TWiki::Plugins::VERSION 1.1
1473 ## <a name="Plugin-specific file handling"></a> Plugin-specific file handling
1475 ### <a name="get_WorkArea( $pluginName ) - $d"></a> getWorkArea( $pluginName ) -> $directorypath
1477 Gets a private directory for Plugin use. The Plugin is entirely responsible for managing this directory; TWiki will not read from it, or write to it.
1479 The directory is guaranteed to exist, and to be writable by the webserver user. By default it will **not** be web accessible.
1481 The directory and it's contents are permanent, so Plugins must be careful to keep their areas tidy.
1483 **Since:** TWiki::Plugins::VERSION 1.1 (Dec 2005)
1485 ### <a name="readFile( $filename ) - $text"></a> readFile( $filename ) -> $text
1487 Read file, low level. Used for Plugin workarea.
1489 - `$filename` - Full path name of file
1491 Return: `$text` Content of file, empty if not found
1493 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1495 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1497 ### <a name="saveFile( $filename, $text )"></a> saveFile( $filename, $text )
1499 Save file, low level. Used for Plugin workarea.
1501 - `$filename` - Full path name of file
1502 - `$text` - Text to save
1506 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1508 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1510 ## <a name="General Utilities"></a> General Utilities
1512 ### <a name="get_RegularExpression( $name ) -"></a> getRegularExpression( $name ) -> $expr
1514 Retrieves a TWiki predefined regular expression or character class.
1516 - `$name` - Name of the expression to retrieve. See notes below
1518 Return: String or precompiled regular expression matching as described below.
1520 **Since:** TWiki::Plugins::VERSION 1.020 (9 Feb 2004)
1522 **_Note:_** TWiki internally precompiles several regular expressions to represent various string entities in an I18N-compatible manner. Plugins authors are encouraged to use these in matching where appropriate. The following are guaranteed to be present. Others may exist, but their use is unsupported and they may be removed in future TWiki versions.
1524 In the table below, the expression marked type 'String' are intended for use within character classes (i.e. for use within square brackets inside a regular expression), for example:
1526 my $upper = TWiki::Func::getRegularExpression('upperAlpha');
1527 my $alpha = TWiki::Func::getRegularExpression('mixedAlpha');
1528 my $capitalized = qr/[$upper][$alpha]+/;
1530 Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
1532 my $webRE = TWiki::Func::getRegularExpression('webNameRegex');
1533 my $isWebName = ( $s =~ m/$webRE/ );
1535 <table border="1" cellpadding="0" cellspacing="0">
1537 <th bgcolor="#99CCCC"><strong> Name </strong></th>
1538 <th bgcolor="#99CCCC"><strong> Matches </strong></th>
1539 <th bgcolor="#99CCCC"><strong> Type </strong></th>
1542 <td> upperAlpha </td>
1543 <td> Upper case characters </td>
1547 <td> upperAlphaNum </td>
1548 <td> Upper case characters and digits </td>
1552 <td> lowerAlpha </td>
1553 <td> Lower case characters </td>
1557 <td> lowerAlphaNum </td>
1558 <td> Lower case characters and digits </td>
1567 <td> mixedAlpha </td>
1568 <td> Alphabetic characters </td>
1572 <td> mixedAlphaNum </td>
1573 <td> Alphanumeric characters </td>
1577 <td> wikiWordRegex </td>
1578 <td>[[Main/WikiWords]]</td>
1582 <td> webNameRegex </td>
1583 <td> User web names </td>
1587 <td> anchorRegex </td>
1588 <td> #AnchorNames </td>
1592 <td> abbrevRegex </td>
1593 <td> Abbreviations e.g. GOV, IRS </td>
1597 <td> emailAddrRegex </td>
1598 <td><a href="mailto:email@address.com">email@address.com</a></td>
1602 <td> tagNameRegex </td>
1603 <td> Standard variable names e.g. %THIS_BIT% (THIS_BIT only) </td>
1608 ### <a name="normalize_WebTopicName($web, $to"></a> normalizeWebTopicName($web, $topic) -> ($web, $topic)
1610 Parse a web and topic name, supplying defaults as appropriate.
1612 - `$web` - Web name, identifying variable, or empty string
1613 - `$topic` - Topic name, may be a web.topic string, required.
1615 Return: the parsed Web/Topic pair
1617 **Since:** TWiki::Plugins::VERSION 1.1
1619 <table border="1" cellpadding="0" cellspacing="0">
1621 <th bgcolor="#99CCCC"><strong> Input </strong></th>
1622 <th bgcolor="#99CCCC"><strong> Return </strong></th>
1625 <td><tt>( 'Web', 'Topic' ) </tt></td>
1626 <td><tt>( 'Web', 'Topic' ) </tt></td>
1629 <td><tt>( '', 'Topic' ) </tt></td>
1630 <td><tt>( 'Main', 'Topic' ) </tt></td>
1633 <td><tt>( '', '' ) </tt></td>
1634 <td><tt>( 'Main', 'WebHome' ) </tt></td>
1637 <td><tt>( '', 'Web/Topic' ) </tt></td>
1638 <td><tt>( 'Web', 'Topic' ) </tt></td>
1641 <td><tt>( '', 'Web/Subweb/Topic' ) </tt></td>
1642 <td><tt>( 'Web/Subweb', 'Topic' ) </tt></td>
1645 <td><tt>( '', 'Web.Topic' ) </tt></td>
1646 <td><tt>( 'Web', 'Topic' ) </tt></td>
1649 <td><tt>( '', 'Web.Subweb.Topic' ) </tt></td>
1650 <td><tt>( 'Web/Subweb', 'Topic' ) </tt></td>
1653 <td><tt>( 'Web1', 'Web2.Topic' )</tt></td>
1654 <td><tt>( 'Web2', 'Topic' ) </tt></td>
1658 Note that hierarchical web names ([[SubWeb]]) are only available if hierarchical webs are enabled in `configure`.
1660 The symbols %USERSWEB%, %SYSTEMWEB% and %DOCWEB% can be used in the input to represent the web names set in $cfg\{UsersWebName\} and $cfg\{SystemWebName\}. For example:
1662 <table border="1" cellpadding="0" cellspacing="0">
1664 <th bgcolor="#99CCCC"><strong> Input </strong></th>
1665 <th bgcolor="#99CCCC"><strong> Return </strong></th>
1668 <td><tt>( '%USERSWEB%', 'Topic' )</tt></td>
1669 <td><tt>( 'Main', 'Topic' ) </tt></td>
1672 <td><tt>( '%SYSTEMWEB%', 'Topic' )</tt></td>
1673 <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1676 <td><tt>( '', '%DOCWEB%.Topic' )</tt></td>
1677 <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1681 ## <a name="StaticMethod <strong>sanitize_Attachmen"></a> [[StaticMethod]] \*sanitizeAttachmentName `($fname) -> ($fileName,$origName)`
1683 Given a file namer, sanitise it according to the rules for transforming attachment names. Returns the sanitised name together with the basename before sanitisation.
1685 Sanitation includes filtering illegal characters and mapping client file names to legal server names.
1687 **Since:** TWiki::Plugins::VERSION 1.2
1689 ### <a name="space_OutWikiWord( $word, $sep )"></a> spaceOutWikiWord( $word, $sep ) -> $text
1691 Spaces out a wiki word by inserting a string (default: one space) between each word component. With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.
1693 **Since:** TWiki::Plugins::VERSION 1.2
1695 ### <a name="writeWarning( $text )"></a> writeWarning( $text )
1697 Log Warning that may require admin intervention to data/warning.txt
1699 - `$text` - Text to write; timestamp gets added
1703 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1705 ### <a name="writeDebug( $text )"></a> writeDebug( $text )
1707 Log debug message to data/debug.txt
1709 - `$text` - Text to write; timestamp gets added
1713 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1715 ### <a name="formatTime( $time, $format, $tim"></a> formatTime( $time, $format, $timezone ) -> $text
1717 Format the time in seconds into the desired time string
1719 - `$time` - Time in epoc seconds
1720 - `$format` - Format type, optional. Default e.g. `'31 Dec 2002 - 19:30'`. Can be `'$iso'` (e.g. `'2002-12-31T19:30Z'`), `'$rcs'` (e.g. `'2001/12/31 23:59:59'`, `'$http'` for HTTP header format (e.g. `'Thu, 23 Jul 1998 07:21:56 GMT'`), or any string with tokens `'$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz'` for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively
1721 - `$timezone` - either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
1723 Return: `$text` Formatted time string
1725 <table border="1" cellpadding="0" cellspacing="0">
1728 <td> if you used the removed formatGmTime, add a third parameter 'gmtime' </td>
1732 **Since:** TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
1734 ### <a name="isTrue( $value, $default ) - $bo"></a> isTrue( $value, $default ) -> $boolean
1736 Returns 1 if `$value` is true, and 0 otherwise. "true" means set to something with a Perl true value, with the special cases that "off", "false" and "no" (case insensitive) are forced to false. Leading and trailing spaces in `$value` are ignored.
1738 If the value is undef, then `$default` is returned. If `$default` is not specified it is taken as 0.
1740 **Since:** $TWiki::Plugins::VERSION 1.2
1742 ### <a name="is_ValidWikiWord ( $text ) - $bo"></a> isValidWikiWord ( $text ) -> $boolean
1744 Check for a valid [[WikiWord]] or [[WikiName]]
1746 - `$text` - Word to test
1748 **Since:** TWiki::Plugins::VERSION 1.100 (Dec 2005)
1750 ### <a name="extractParameters($attr ) - %par"></a> extractParameters($attr ) -> %params
1752 Extract all parameters from a variable string and returns a hash of parameters
1754 - `$attr` - Attribute string
1756 Return: `%params` Hash containing all parameters. The nameless parameter is stored in key `_DEFAULT`
1758 **Since:** TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
1761 - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1762 - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1763 - Then call this on the text: <br />
1764 - params = TWiki::Func::extractParameters( $text );=
1765 - The `%params` hash contains now: <br />`_DEFAULT => 'nameless'`<br />`name1 => "val1"`<br />`name2 => "val2"`
1767 ### <a name="extract_NameValuePair( $attr, $n"></a> extractNameValuePair( $attr, $name ) -> $value
1769 Extract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters
1771 - `$attr` - Attribute string
1772 - `$name` - Name, optional
1774 Return: `$value` Extracted value
1776 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1779 - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1780 - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1781 - Then call this on the text: <br />`my $noname = TWiki::Func::extractNameValuePair( $text );`<br />`my $val1 = TWiki::Func::extractNameValuePair( $text, "name1" );`<br />`my $val2 = TWiki::Func::extractNameValuePair( $text, "name2" );`
1783 ## <a name="Deprecated functions"></a> Deprecated functions
1785 From time-to-time, the TWiki developers will add new functions to the interface (either to [[TWikiFuncDotPm]], or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable. When this happens, the deprecated functions will be supported in the interface for at least one more TWiki release, and probably longer, though this cannot be guaranteed.
1787 Updated plugins may still need to define deprecated handlers for compatibility with old TWiki versions. In this case, the plugin package that defines old handlers can suppress the warnings in %FAILEDPLUGINS%.
1789 This is done by defining a map from the handler name to the `TWiki::Plugins` version _in which the handler was first deprecated_. For example, if we need to define the `endRenderingHandler` for compatibility with `TWiki::Plugins` versions before 1.1, we would add this to the plugin:
1791 package TWiki::Plugins::SinkPlugin;
1792 use vars qw( %TWikiCompatibility );
1793 $TWikiCompatibility{endRenderingHandler} = 1.1;
1795 If the currently-running TWiki version is 1.1 _or later_, then the _handler will not be called_ and _the warning will not be issued_. TWiki with versions of `TWiki::Plugins` before 1.1 will still call the handler as required.
1797 The following functions are retained for compatibility only. You should stop using them as soon as possible.
1799 ### <a name="get_ScriptUrlPath( ) - $path"></a> getScriptUrlPath( ) -> $path
1803 **DEPRECATED** since 1.1 - use `getScriptUrl` instead.
1805 Return: `$path` URL path of TWiki scripts, e.g. `"/cgi-bin"`
1807 **WARNING:** you are strongly recommended **not** to use this function, as the \{ScriptUrlPaths\} URL rewriting rules will not apply to urls generated using it.
1809 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1811 ### <a name="get_OopsUrl( $web, $topic, $temp"></a> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
1813 Compose fully qualified 'oops' dialog URL
1815 - `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
1816 - `$topic` - Topic name, e.g. `'WebNotify'`
1817 - `$template` - Oops template name, e.g. `'oopsmistake'`. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
1818 - `$param1` ... `$param4` - Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
1820 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked¶m1=joe"`
1822 **DEPRECATED** since 1.1, the recommended approach is to throw an [[oops exception|Main/TWikiOopsExceptionDotPm]].
1824 use Error qw( :try );
1826 throw TWiki::OopsException(
1830 params => [ 'I got my toe stuck' ]);
1832 (this example will use the `oopstoestuckerror` template.)
1834 If this is not possible (e.g. in a REST handler that does not trap the exception) then you can use `getScriptUrl` instead:
1836 my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops',
1837 template => 'oopstoestuckerror',
1838 param1 => 'I got my toe stuck');
1839 TWiki::Func::redirectCgiQuery( undef, $url );
1842 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1844 ### <a name="permissionsSet( $web ) - $boolea"></a> permissionsSet( $web ) -> $boolean
1846 Test if any access restrictions are set for this web, ignoring settings on individual pages
1848 - `$web` - Web name, required, e.g. `'Sandbox'`
1850 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
1852 **DEPRECATED** since 1.2 - use `getPreferencesValue` instead to determine what permissions are set on the web, for example:
1854 foreach my $type qw( ALLOW DENY ) {
1855 foreach my $action qw( CHANGE VIEW ) {
1856 my $pref = $type . 'WEB' . $action;
1857 my $val = getPreferencesValue( $pref, $web ) || '';
1858 if( $val =~ /\S/ ) {
1859 print "$pref is set to $val on $web\n";
1864 ### <a name="get_PublicWebList( ) - @webs"></a> getPublicWebList( ) -> @webs
1866 **DEPRECATED** since 1.1 - use `getListOfWebs` instead.
1868 Get list of all public webs, e.g. all webs that do not have the `NOSEARCHALL` flag set in the [[WebPreferences]]
1870 Return: `@webs` List of all public webs, e.g. `( 'Main', 'Know', 'TWiki' )`
1872 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1874 ### <a name="format_GmTime( $time, $format )"></a><a name="format_GmTime( $time, $format ) "></a> formatGmTime( $time, $format ) -> $text
1876 **DEPRECATED** since 1.1 - use `formatTime` instead.
1878 Format the time to GM time
1880 - `$time` - Time in epoc seconds
1881 - `$format` - Format type, optional. Default e.g. `'31 Dec 2002 - 19:30'`, can be `'iso'` (e.g. `'2002-12-31T19:30Z'`), `'rcs'` (e.g. `'2001/12/31 23:59:59'`, `'http'` for HTTP header format (e.g. `'Thu, 23 Jul 1998 07:21:56 GMT'`)
1883 Return: `$text` Formatted time string
1885 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1887 ### <a name="get_DataDir( ) - $dir"></a> getDataDir( ) -> $dir
1889 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead
1891 Get data directory (topic file root)
1893 Return: `$dir` Data directory, e.g. `'/twiki/data'`
1895 This function violates store encapsulation and is therefore **deprecated**.
1897 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1899 ### <a name="get_PubDir( ) - $dir"></a> getPubDir( ) -> $dir
1901 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead
1903 Get pub directory (file attachment root). Attachments are in `$dir/Web/TopicName`
1905 Return: `$dir` Pub directory, e.g. `'/htdocs/twiki/pub'`
1907 This function violates store encapsulation and is therefore **deprecated**.
1909 Use `readAttachment` and `saveAttachment` instead.
1911 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1913 ### <a name="checkDependencies( $moduleName,"></a><a name="checkDependencies( $moduleName, "></a> checkDependencies( $moduleName, $dependenciesRef ) -> $error
1915 **DEPRECATED** since 1.1 - use TWiki:Plugins.BuildContrib and define DEPENDENCIES that can be statically evaluated at install time instead. It is a lot more efficient.
1917 **Since:** TWiki::Plugins::VERSION 1.025 (01 Aug 2004)