TWiki/TWikiFuncDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Func="></a> Package =TWiki::Func
   2
   3 _Official list of stable TWiki functions for Plugin developers_
   4
   5 This module defines official functions that [[Plugins|TWiki/TWikiPlugins]] can use to interact with the TWiki engine and content.
   6
   7 Refer to [[EmptyPlugin]] and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.
   8
   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.
  10
  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.
  12
  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%` variable. The 'Since' field in the function documentation refers to the VERSION number and the date that the function was addded.
  14
  15 **_Note:_** Beware! These methods should only ever be called from the context of a TWiki Plugin. They require a Plugins SESSION context to be established before they are called, and will not work if simply called from another TWiki module. For example,
  16
  17     use TWiki;
  18     print TWiki::Func::getSkin(),"\n";
  19
  20 will fail with `Can't call method "getSkin" on an undefined value at TWiki/Func.pm line 83`.
  21
  22 If you want to call the methods outside the context of a plugin, you can create a Plugins SESSION object. For example, the script:
  23
  24     use TWiki:
  25     $TWiki::Plugins::SESSION = new TWiki();
  26     print TWiki::Func::getSkin(),"\n";
  27
  28 will work happily.
  29
  30 <div>
  31   <ul>
  32     <li><a href="#Package =TWiki::Func="> Package TWiki::Func</a><ul>
  33         <li><a href="#Environment"> Environment</a><ul>
  34             <li><a href="#getSkin( ) -> $skin"> getSkin( ) -&gt; $skin</a></li>
  35             <li><a href="#get_UrlHost( ) -> $host"> getUrlHost( ) -&gt; $host</a></li>
  36             <li><a href="#get_ScriptUrl( $web, $topic, $sc"> getScriptUrl( $web, $topic, $script, ... ) -&gt; $url</a></li>
  37             <li><a href="#get_ViewUrl( $web, $topic ) -> $"> getViewUrl( $web, $topic ) -&gt; $url</a></li>
  38             <li><a href="#get_OopsUrl( $web, $topic, $temp"> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -&gt; $url</a></li>
  39             <li><a href="#get_PubUrlPath( ) -> $path"> getPubUrlPath( ) -&gt; $path</a></li>
  40             <li><a href="#get_CgiQuery( ) -> $query"> getCgiQuery( ) -&gt; $query</a></li>
  41             <li><a href="#get_SessionValue( $key ) -> $val"> getSessionValue( $key ) -&gt; $value</a></li>
  42             <li><a href="#set_SessionValue( $key, $value )"> setSessionValue( $key, $value ) -&gt; $boolean</a></li>
  43             <li><a href="#clear_SessionValue( $key ) -> $b"> clearSessionValue( $key ) -&gt; $boolean</a></li>
  44             <li><a href="#getContext() -> \%hash"> getContext() -&gt; \%hash</a></li>
  45           </ul>
  46         </li>
  47         <li><a href="#Preferences"> Preferences</a><ul>
  48             <li><a href="#get_PreferencesValue( $key, $web"> getPreferencesValue( $key, $web ) -&gt; $value</a></li>
  49             <li><a href="#get_PluginPreferencesValue( $key"> getPluginPreferencesValue( $key ) -&gt; $value</a></li>
  50             <li><a href="#get_PreferencesFlag( $key, $web"> getPreferencesFlag( $key, $web ) -&gt; $value</a></li>
  51             <li><a href="#get_PluginPreferencesFlag( $key"> getPluginPreferencesFlag( $key ) -&gt; $boolean</a></li>
  52             <li><a href="#get_WikiToolName( ) -> $name"> getWikiToolName( ) -&gt; $name</a></li>
  53             <li><a href="#get_MainWebname( ) -> $name"> getMainWebname( ) -&gt; $name</a></li>
  54             <li><a href="#get_TwikiWebname( ) -> $name"> getTwikiWebname( ) -&gt; $name</a></li>
  55           </ul>
  56         </li>
  57         <li><a href="#User Handling and Access Control"> User Handling and Access Control</a><ul>
  58             <li><a href="#get_DefaultUserName( ) -> $login"> getDefaultUserName( ) -&gt; $loginName</a></li>
  59             <li><a href="#get_WikiName( ) -> $wikiName"> getWikiName( ) -&gt; $wikiName</a></li>
  60             <li><a href="#get_WikiUserName( ) -> $wikiName"> getWikiUserName( ) -&gt; $wikiName</a></li>
  61             <li><a href="#wiki_ToUserName( $wikiName ) ->"> wikiToUserName( $wikiName ) -&gt; $loginName</a></li>
  62             <li><a href="#user_ToWikiName( $loginName, $do"> userToWikiName( $loginName, $dontAddWeb ) -&gt; $wikiName</a></li>
  63             <li><a href="#isGuest( ) -> $boolean"> isGuest( ) -&gt; $boolean</a></li>
  64             <li><a href="#permissionsSet( $web ) -> $boole"> permissionsSet( $web ) -&gt; $boolean</a></li>
  65             <li><a href="#check_AccessPermission( $type, $"> checkAccessPermission( $type, $wikiName, $text, $topic, $web ) -&gt; $boolean</a></li>
  66           </ul>
  67         </li>
  68         <li><a href="#Webs, Topics and Attachments"> Webs, Topics and Attachments</a><ul>
  69             <li><a href="#get_ListOfWebs( $filter ) -> @we"> getListOfWebs( $filter ) -&gt; @webs</a></li>
  70             <li><a href="#webExists( $web ) -> $boolean"> webExists( $web ) -&gt; $boolean</a></li>
  71             <li><a href="#createWeb( $newWeb, $baseWeb, $o"> createWeb( $newWeb, $baseWeb, $opts )</a></li>
  72             <li><a href="#moveWeb( $oldName, $newName )"> moveWeb( $oldName, $newName )</a></li>
  73             <li><a href="#get_TopicList( $web ) -> @topics"> getTopicList( $web ) -&gt; @topics</a></li>
  74             <li><a href="#topicExists( $web, $topic ) -> $"> topicExists( $web, $topic ) -&gt; $boolean</a></li>
  75             <li><a href="#check_TopicEditLock( $web, $topi"> checkTopicEditLock( $web, $topic ) -&gt; ( $oopsUrl, $loginName, $unlockTime )</a></li>
  76             <li><a href="#set_TopicEditLock( $web, $topic,"> setTopicEditLock( $web, $topic, $lock )</a></li>
  77             <li><a href="#saveTopic( $web, $topic, $meta,"> saveTopic( $web, $topic, $meta, $text, $options ) -&gt; $error</a></li>
  78             <li><a href="#save_TopicText( $web, $topic, $t"> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -&gt; $oopsUrl</a></li>
  79             <li><a href="#moveTopic( $web, $topic, $newWeb"> moveTopic( $web, $topic, $newWeb, $newTopic )</a></li>
  80             <li><a href="#get_RevisionInfo($web, $topic, $"> getRevisionInfo($web, $topic, $rev, $attachment ) -&gt; ( $date, $user, $rev, $comment ) </a></li>
  81             <li><a href="#get_RevisionAtTime( $web, $topic"> getRevisionAtTime( $web, $topic, $time ) -&gt; $rev</a></li>
  82             <li><a href="#readTopic( $web, $topic, $rev )"> readTopic( $web, $topic, $rev ) -&gt; ( $meta, $text )</a></li>
  83             <li><a href="#read_TopicText( $web, $topic, $r"> readTopicText( $web, $topic, $rev, $ignorePermissions ) -&gt; $text</a></li>
  84             <li><a href="#attachmentExists( $web, $topic,"> attachmentExists( $web, $topic, $attachment ) -&gt; $boolean</a></li>
  85             <li><a href="#readAttachment( $web, $topic, $n"> readAttachment( $web, $topic, $name, $rev ) -&gt; $data</a></li>
  86             <li><a href="#saveAttachment( $web, $topic, $a"> saveAttachment( $web, $topic, $attachment, $opts )</a></li>
  87             <li><a href="#moveAttachment( $web, $topic, $a"> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )</a></li>
  88           </ul>
  89         </li>
  90         <li><a href="#Assembling Pages"> Assembling Pages</a><ul>
  91             <li><a href="#readTemplate( $name, $skin ) ->"> readTemplate( $name, $skin ) -&gt; $text</a></li>
  92             <li><a href="#loadTemplate ( $name, $skin, $we"> loadTemplate ( $name, $skin, $web ) -&gt; $text</a></li>
  93             <li><a href="#expandTemplate( $def  ) -> $stri"> expandTemplate( $def ) -&gt; $string</a></li>
  94             <li><a href="#writeHeader( $query, $contentLen"> writeHeader( $query, $contentLength )</a></li>
  95             <li><a href="#redirect_CgiQuery( $query, $url"> redirectCgiQuery( $query, $url )</a></li>
  96             <li><a href="#add_ToHEAD( $id, $header )"> addToHEAD( $id, $header )</a></li>
  97             <li><a href="#expand_CommonVariables( $text, $"> expandCommonVariables( $text, $topic, $web ) -&gt; $text</a></li>
  98             <li><a href="#renderText( $text, $web ) -> $te"> renderText( $text, $web ) -&gt; $text</a></li>
  99             <li><a href="#internalLink( $pre, $web, $topic"> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -&gt; $text</a></li>
 100           </ul>
 101         </li>
 102         <li><a href="#E-mail"> E-mail</a><ul>
 103             <li><a href="#sendEmail ( $text, $retries ) ->"> sendEmail ( $text, $retries ) -&gt; $error</a></li>
 104             <li><a href="#wiki_ToEmail( $wikiName ) -> $em"> wikiToEmail( $wikiName ) -&gt; $email</a></li>
 105           </ul>
 106         </li>
 107         <li><a href="#Creating New Topics"> Creating New Topics</a><ul>
 108             <li><a href="#expand_VariablesOnTopicCreation"> expandVariablesOnTopicCreation ( $text ) -&gt; $text</a></li>
 109           </ul>
 110         </li>
 111         <li><a href="#Special handlers"> Special handlers</a><ul>
 112             <li><a href="#register_TagHandler( $var, \fn,"> registerTagHandler( $var, \&amp;fn, $syntax )</a></li>
 113             <li><a href="#registerRESTHandler( $alias, \fn"> registerRESTHandler( $alias, \&amp;fn, )</a></li>
 114           </ul>
 115         </li>
 116         <li><a href="#Searching"> Searching</a><ul>
 117             <li><a href="#search_InWebContent($searchStrin"> searchInWebContent($searchString, $web, \@topics, \%options ) -&gt; \%map</a></li>
 118           </ul>
 119         </li>
 120         <li><a href="#Plugin-specific file handling"> Plugin-specific file handling</a><ul>
 121             <li><a href="#get_WorkArea( $pluginName ) -> $"> getWorkArea( $pluginName ) -&gt; $directorypath</a></li>
 122             <li><a href="#readFile( $filename ) -> $text"> readFile( $filename ) -&gt; $text</a></li>
 123             <li><a href="#saveFile( $filename, $text )"> saveFile( $filename, $text )</a></li>
 124           </ul>
 125         </li>
 126         <li><a href="#General Utilities"> General Utilities</a><ul>
 127             <li><a href="#get_RegularExpression( $name ) -"> getRegularExpression( $name ) -&gt; $expr</a></li>
 128             <li><a href="#normalize_WebTopicName($web, $to"> normalizeWebTopicName($web, $topic) -&gt; ($web, $topic)</a></li>
 129             <li><a href="#writeWarning( $text )"> writeWarning( $text )</a></li>
 130             <li><a href="#writeDebug( $text )"> writeDebug( $text )</a></li>
 131             <li><a href="#formatTime( $time, $format, $tim"> formatTime( $time, $format, $timezone ) -&gt; $text</a></li>
 132             <li><a href="#is_ValidWikiWord ( $text ) -> $b"> isValidWikiWord ( $text ) -&gt; $boolean</a></li>
 133             <li><a href="#extractParameters($attr ) -> %pa"> extractParameters($attr ) -&gt; %params</a></li>
 134             <li><a href="#extract_NameValuePair( $attr, $n"> extractNameValuePair( $attr, $name ) -&gt; $value</a></li>
 135           </ul>
 136         </li>
 137         <li><a href="#Deprecated functions"> Deprecated functions</a><ul>
 138             <li><a href="#get_ScriptUrlPath( ) -> $path"> getScriptUrlPath( ) -&gt; $path</a></li>
 139             <li><a href="#get_PublicWebList( ) -> @webs"> getPublicWebList( ) -&gt; @webs</a></li>
 140             <li><a href="#format_GmTime( $time, $format )"> formatGmTime( $time, $format ) -&gt; $text</a></li>
 141             <li><a href="#get_DataDir( ) -> $dir"> getDataDir( ) -&gt; $dir</a></li>
 142             <li><a href="#get_PubDir( ) -> $dir"> getPubDir( ) -&gt; $dir</a></li>
 143             <li><a href="#checkDependencies( $moduleName,"> checkDependencies( $moduleName, $dependenciesRef ) -&gt; $error</a></li>
 144           </ul>
 145         </li>
 146       </ul>
 147     </li>
 148   </ul>
 149 </div>
 150
 151 ## <a name="Environment"></a> Environment
 152
 153 ### <a name="getSkin( ) - $skin"></a> getSkin( ) -&gt; $skin
 154
 155 Get the skin path, set by the `SKIN` and `COVER` preferences variables or the `skin` and `cover` CGI parameters
 156
 157 Return: `$skin` Comma-separated list of skins, e.g. `'gnu,tartan'`. Empty string if none.
 158
 159 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 160
 161 ### <a name="get_UrlHost( ) - $host"></a> getUrlHost( ) -&gt; $host
 162
 163 Get protocol, domain and optional port of script URL
 164
 165 Return: `$host` URL host, e.g. `"http://example.com:80"`
 166
 167 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 168
 169 ### <a name="get_ScriptUrl( $web, $topic, $sc"></a> getScriptUrl( $web, $topic, $script, ... ) -&gt; $url
 170
 171 Compose fully qualified URL
 172
 173 - `$web` - Web name, e.g. `'Main'`
 174 - `$topic` - Topic name, e.g. `'WebNotify'`
 175 - `$script` - Script name, e.g. `'view'`
 176
 177 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
 178
 179 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 180
 181 ### <a name="get_ViewUrl( $web, $topic ) - $u"></a> getViewUrl( $web, $topic ) -&gt; $url
 182
 183 Compose fully qualified view URL
 184
 185 - `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
 186 - `$topic` - Topic name, e.g. `'WebNotify'`
 187
 188 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
 189
 190 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 191
 192 ### <a name="get_OopsUrl( $web, $topic, $temp"></a> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -&gt; $url
 193
 194 Compose fully qualified 'oops' dialog URL
 195
 196 - `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
 197 - `$topic` - Topic name, e.g. `'WebNotify'`
 198 - `$template` - Oops template name, e.g. `'oopsmistake'`. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
 199 - `$param1` ... `$param4` - Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
 200
 201 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&param1=joe"`
 202
 203 This might be used like this:
 204
 205        my $url = TWiki::Func::getOopsUrl($web, $topic, 'oopsmistake', 'I made a boo-boo');
 206        TWiki::Func::redirectCgiQuery( undef, $url );
 207        return 0;
 208
 209 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 210
 211 Since TWiki::Plugins::VERSION 1.1, the recommended approach is to throw an [[oops exception|Main/TWikiOopsExceptionDotPm]].
 212
 213        use Error qw( :try );
 214
 215        throw TWiki::OopsException($web, $topic, undef, 0, [ 'I made a boo-boo' ]);
 216
 217 and let TWiki handle the cleanup.
 218
 219 ### <a name="get_PubUrlPath( ) - $path"></a> getPubUrlPath( ) -&gt; $path
 220
 221 Get pub URL path
 222
 223 Return: `$path` URL path of pub directory, e.g. `"/pub"`
 224
 225 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 226
 227 ### <a name="get_CgiQuery( ) - $query"></a> getCgiQuery( ) -&gt; $query
 228
 229 Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set
 230
 231 Return: `$query` CGI query object; or 0 if script is called as a shell script
 232
 233 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 234
 235 ### <a name="get_SessionValue( $key ) - $valu"></a> getSessionValue( $key ) -&gt; $value
 236
 237 Get a session value from the client session module
 238
 239 - `$key` - Session key
 240
 241 Return: `$value` Value associated with key; empty string if not set
 242
 243 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 200)
 244
 245 ### <a name="set_SessionValue( $key, $value )"></a> setSessionValue( $key, $value ) -&gt; $boolean
 246
 247 Set a session value via the client session module
 248
 249 - `$key` - Session key
 250 - `$value` - Value associated with key
 251
 252 Return: true if function succeeded
 253
 254 **Since:** TWiki::Plugins::VERSION 1.000 (17 Aug 2001)
 255
 256 ### <a name="clear_SessionValue( $key ) - $bo"></a> clearSessionValue( $key ) -&gt; $boolean
 257
 258 Clear a session value via the client session module
 259
 260 - `$key` - Session key
 261
 262 Return: true if function succeeded
 263
 264 **Since:** TWiki::Plugins::VERSION 1.1
 265
 266 ### <a name="getContext() - \%hash"></a> getContext() -&gt; \\%hash
 267
 268 Get a hash of context identifiers representing the currently active context.
 269
 270 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 [[TWikiTemplates]] topic. Please be careful not to overwrite any of these identifiers!
 271
 272 Context identifiers can be used to communicate between Plugins, and between Plugins and templates. For example, in [[FirstPlugin]].pm, you might write:
 273
 274     sub initPlugin {
 275        TWiki::Func::getContext()->{'MyID'} = 1;
 276        ...
 277
 278 This can be used in SecondPlugin.pm like this:
 279
 280     sub initPlugin {
 281        if( TWiki::Func::getContext()->{'MyID'} ) {
 282           ...
 283        }
 284        ...
 285
 286 or in a template, like this:
 287
 288     %TMPL:DEF{"ON"}% Not off %TMPL:END%
 289     %TMPL:DEF{"OFF"}% Not on %TMPL:END%
 290     %TMPL:P{context="MyID" then="ON" else="OFF"}%
 291
 292 or in a topic:
 293
 294     %IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%
 295
 296 **_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.
 297
 298 **Since:** TWiki::Plugins::VERSION 1.1
 299
 300 ## <a name="Preferences"></a> Preferences
 301
 302 ### <a name="get_PreferencesValue( $key, $web"></a> getPreferencesValue( $key, $web ) -&gt; $value
 303
 304 Get a preferences value from TWiki or from a Plugin
 305
 306 - `$key` - Preferences key
 307 - `$web` - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
 308
 309 Return: `$value` Preferences value; empty string if not set
 310
 311 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 312
 313 - Example for Plugin setting:
 314   - [[MyPlugin]] topic has: `* Set COLOR = red`
 315   - Use `"MYPLUGIN_COLOR"` for `$key`
 316   - `my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );`
 317
 318 - Example for preferences setting:
 319   - [[WebPreferences]] topic has: `* Set WEBBGCOLOR = #FFFFC0`
 320   - `my $webColor = TWiki::Func::getPreferencesValue( 'WEBBGCOLOR', 'Sandbox' );`
 321
 322 ### <a name="get_PluginPreferencesValue( $key"></a> getPluginPreferencesValue( $key ) -&gt; $value
 323
 324 Get a preferences value from your Plugin
 325
 326 - `$key` - Plugin Preferences key w/o PLUGINNAME\_ prefix.
 327
 328 Return: `$value` Preferences value; empty string if not set
 329
 330 **_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)
 331
 332 **Since:** TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
 333
 334 ### <a name="get_PreferencesFlag( $key, $web"></a><a name="get_PreferencesFlag( $key, $web "></a> getPreferencesFlag( $key, $web ) -&gt; $value
 335
 336 Get a preferences flag from TWiki or from a Plugin
 337
 338 - `$key` - Preferences key
 339 - `$web` - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
 340
 341 Return: `$value` Preferences flag `'1'` (if set), or `"0"` (for preferences values `"off"`, `"no"` and `"0"`)
 342
 343 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 344
 345 - Example for Plugin setting:
 346   - [[MyPlugin]] topic has: `* Set SHOWHELP = off`
 347   - Use `"MYPLUGIN_SHOWHELP"` for `$key`
 348   - `my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );`
 349
 350 ### <a name="get_PluginPreferencesFlag( $key"></a><a name="get_PluginPreferencesFlag( $key "></a> getPluginPreferencesFlag( $key ) -&gt; $boolean
 351
 352 Get a preferences flag from your Plugin
 353
 354 - `$key` - Plugin Preferences key w/o PLUGINNAME\_ prefix.
 355
 356 Return: false for preferences values `"off"`, `"no"` and `"0"`, or values not set at all. True otherwise.
 357
 358 **_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)
 359
 360 **Since:** TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
 361
 362 ### <a name="get_WikiToolName( ) - $name"></a> getWikiToolName( ) -&gt; $name
 363
 364 Get toolname as defined in TWiki.cfg
 365
 366 Return: `$name` Name of tool, e.g. `'TWiki'`
 367
 368 Synonymous with TWiki::Func::getPreferencesValue('WIKITOOLNAME');
 369
 370 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 371
 372 ### <a name="get_MainWebname( ) - $name"></a> getMainWebname( ) -&gt; $name
 373
 374 Get name of Main web as defined in TWiki.cfg
 375
 376 Return: `$name` Name, e.g. `'Main'`
 377
 378 Synonymous with TWiki::Func::getPreferencesValue('MAINWEB');
 379
 380 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 381
 382 ### <a name="get_TwikiWebname( ) - $name"></a> getTwikiWebname( ) -&gt; $name
 383
 384 Get name of TWiki documentation web as defined in TWiki.cfg
 385
 386 Return: `$name` Name, e.g. `'TWiki'`
 387
 388 Synonymous with TWiki::Func::getPreferencesValue('TWIKIWEB');
 389
 390 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 391
 392 ## <a name="User Handling and Access Control"></a> User Handling and Access Control
 393
 394 ### <a name="get_DefaultUserName( ) - $loginN"></a> getDefaultUserName( ) -&gt; $loginName
 395
 396 Get default user name as defined in the configuration as `DefaultUserLogin`
 397
 398 Return: `$loginName` Default user name, e.g. `'guest'`
 399
 400 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 401
 402 ### <a name="get_WikiName( ) - $wikiName"></a> getWikiName( ) -&gt; $wikiName
 403
 404 Get Wiki name of logged in user
 405
 406 Return: `$wikiName` Wiki Name, e.g. `'JohnDoe'`
 407
 408 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 409
 410 ### <a name="get_WikiUserName( ) - $wikiName"></a> getWikiUserName( ) -&gt; $wikiName
 411
 412 Get Wiki name of logged in user with web prefix
 413
 414 Return: `$wikiName` Wiki Name, e.g. `"Main.JohnDoe"`
 415
 416 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 417
 418 ### <a name="wiki_ToUserName( $wikiName ) - $"></a> wikiToUserName( $wikiName ) -&gt; $loginName
 419
 420 Translate a Wiki name to a login name based on [[Main.TWikiUsers|Main/TWikiUsers]] topic
 421
 422 - `$wikiName` - Wiki name, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
 423
 424 Return: `$loginName` Login name of user, e.g. `'jdoe'`
 425
 426 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 427
 428 ### <a name="user_ToWikiName( $loginName, $do"></a> userToWikiName( $loginName, $dontAddWeb ) -&gt; $wikiName
 429
 430 Translate a login name to a Wiki name based on [[Main.TWikiUsers|Main/TWikiUsers]] topic
 431
 432 - `$loginName` - Login name, e.g. `'jdoe'`
 433 - `$dontAddWeb` - Do not add web prefix if `"1"`
 434
 435 Return: `$wikiName` Wiki name of user, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
 436
 437 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 438
 439 ### <a name="isGuest( ) - $boolean"></a> isGuest( ) -&gt; $boolean
 440
 441 Test if logged in user is a guest ([[TWikiGuest]])
 442
 443 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 444
 445 ### <a name="permissionsSet( $web ) - $boolea"></a> permissionsSet( $web ) -&gt; $boolean
 446
 447 Test if any access restrictions are set for this web, ignoring settings on individual pages
 448
 449 - `$web` - Web name, required, e.g. `'Sandbox'`
 450
 451 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 452
 453 ### <a name="check_AccessPermission( $type, $"></a> checkAccessPermission( $type, $wikiName, $text, $topic, $web ) -&gt; $boolean
 454
 455 Check access permission for a topic based on the [[TWiki.TWikiAccessControl|TWiki/TWikiAccessControl]] rules
 456
 457 - `$type` - Access type, e.g. `'VIEW'`, `'CHANGE'`, `'CREATE'`
 458 - `$wikiName` - [[WikiName]] of remote user, i.e. `"Main.PeterThoeny"`
 459 - `$text` - Topic text, optional. If empty, topic `$web.$topic` is consulted
 460 - `$topic` - Topic name, required, e.g. `'PrivateStuff'`
 461 - `$web` - Web name, required, e.g. `'Sandbox'`
 462
 463 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 464
 465 ## <a name="Webs, Topics and Attachments"></a> Webs, Topics and Attachments
 466
 467 ### <a name="get_ListOfWebs( $filter ) - @web"></a> getListOfWebs( $filter ) -&gt; @webs
 468
 469 - `$filter` - spec of web types to recover
 470
 471 Gets a list of webs, filtered according to the spec in the $filter, which may include one of:
 472
 473 1. 'user' (for only user webs)
 474 2. 'template' (for only template webs i.e. those starting with "\_")
 475
 476 `$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.
 477
 478 For example, the deprecated getPublicWebList function can be duplicated as follows:
 479
 480        my @webs = TWiki::Func::getListOfWebs( "user,public" );
 481
 482 **Since:** TWiki::Plugins::VERSION 1.1
 483
 484 ### <a name="webExists( $web ) - $boolean"></a> webExists( $web ) -&gt; $boolean
 485
 486 Test if web exists
 487
 488 - `$web` - Web name, required, e.g. `'Sandbox'`
 489
 490 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 491
 492 ### <a name="createWeb( $newWeb, $baseWeb, $o"></a> createWeb( $newWeb, $baseWeb, $opts )
 493
 494 - `$newWeb` is the name of the new web.
 495 - `$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.
 496 - `$opts` is a ref to a hash that contains settings to be modified in
 497
 498 the web preferences topic in the new web.
 499
 500     use Error qw( :try );
 501     use TWiki::AccessControlException;
 502
 503     try {
 504         TWiki::Func::createWeb( "Newweb" );
 505     } catch Error::Simple with {
 506         my $e = shift;
 507         # see documentation on Error::Simple
 508     } catch TWiki::AccessControlException with {
 509         my $e = shift;
 510         # see documentation on TWiki::AccessControlException
 511     } otherwise {
 512         ...
 513     };
 514
 515 **Since:** TWiki::Plugins::VERSION 1.1
 516
 517 ### <a name="moveWeb( $oldName, $newName )"></a> moveWeb( $oldName, $newName )
 518
 519 Move (rename) a web.
 520
 521     use Error qw( :try );
 522     use TWiki::AccessControlException;
 523
 524     try {
 525         TWiki::Func::moveWeb( "Oldweb", "Newweb" );
 526     } catch Error::Simple with {
 527         my $e = shift;
 528         # see documentation on Error::Simple
 529     } catch TWiki::AccessControlException with {
 530         my $e = shift;
 531         # see documentation on TWiki::AccessControlException
 532     } otherwise {
 533         ...
 534     };
 535
 536 To delete a web, move it to a subweb of `Trash`
 537
 538     TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );
 539
 540 **Since:** TWiki::Plugins::VERSION 1.1
 541
 542 ### <a name="get_TopicList( $web ) - @topics"></a> getTopicList( $web ) -&gt; @topics
 543
 544 Get list of all topics in a web
 545
 546 - `$web` - Web name, required, e.g. `'Sandbox'`
 547
 548 Return: `@topics` Topic list, e.g. `( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )`
 549
 550 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 551
 552 ### <a name="topicExists( $web, $topic ) - $b"></a> topicExists( $web, $topic ) -&gt; $boolean
 553
 554 Test if topic exists
 555
 556 - `$web` - Web name, optional, e.g. `'Main'`.
 557 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`, or `"Main.TokyoOffice"`
 558
 559 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
 560
 561 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 562
 563 ### <a name="check_TopicEditLock( $web, $topi"></a> checkTopicEditLock( $web, $topic ) -&gt; ( $oopsUrl, $loginName, $unlockTime )
 564
 565 Check if a lease has been taken by some other user.
 566
 567 - `$web` Web name, e.g. `"Main"`, or empty
 568 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
 569
 570 Return: `( $oopsUrl, $loginName, $unlockTime )` - The `$oopsUrl` for calling redirectCgiQuery(), user's `$loginName`, and estimated `$unlockTime` in minutes, or ( '', '', 0 ) if no lease exists.
 571
 572 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 573
 574 ### <a name="set_TopicEditLock( $web, $topic,"></a> setTopicEditLock( $web, $topic, $lock )
 575
 576 - `$web` Web name, e.g. `"Main"`, or empty
 577 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
 578 - `$lock` 1 to lease the topic, 0 to clear the lease=
 579
 580 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.
 581
 582 It is **impossible** to fully lock a topic. Concurrent changes will be merged.
 583
 584 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 585
 586 ### <a name="saveTopic( $web, $topic, $meta,"></a><a name="saveTopic( $web, $topic, $meta, "></a> saveTopic( $web, $topic, $meta, $text, $options ) -&gt; $error
 587
 588 - `$web` - web for the topic
 589 - `$topic` - topic name
 590 - `$meta` - reference to TWiki::Meta object
 591 - `$text` - text of the topic (without embedded meta-data!!!
 592 - `\%options` - ref to hash of save options `\%options` may include: <table border="1" cellpadding="0" cellspacing="0">
 593   <tr>
 594     <td><code>dontlog</code></td>
 595     <td> don't log this change in twiki log </td>
 596   </tr>
 597   <tr>
 598     <td><code>comment</code></td>
 599     <td> comment for save </td>
 600   </tr>
 601   <tr>
 602     <td><code>minor</code></td>
 603     <td> True if this is a minor change, and is not to be notified </td>
 604   </tr>
 605 </table>
 606
 607 Return: error message or undef.
 608
 609 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 610
 611 For example,
 612
 613     my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic )
 614     $text =~ s/APPLE/ORANGE/g;
 615     TWiki::Func::saveTopic( $web, $topic, $meta, $text, { comment => 'refruited' } );
 616
 617 **_Note:_** Plugins handlers ( e.g. `beforeSaveHandler` ) will be called as appropriate.
 618
 619 ### <a name="save_TopicText( $web, $topic, $t"></a> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -&gt; $oopsUrl
 620
 621 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.
 622
 623 - `$web` - Web name, e.g. `'Main'`, or empty
 624 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
 625 - `$text` - Topic text to save, assumed to include meta data
 626 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK
 627 - `$dontNotify` - Set to `"1"` if not to notify users of the change
 628
 629 Return: `$oopsUrl` Empty string if OK; the `$oopsUrl` for calling redirectCgiQuery() in case of error
 630
 631 This method is a lot less efficient and much more dangerous than `saveTopic`.
 632
 633 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 634
 635     my $text = TWiki::Func::readTopicText( $web, $topic );
 636
 637     # check for oops URL in case of error:
 638     if( $text =~ /^http.*?\/oops/ ) {
 639         TWiki::Func::redirectCgiQuery( $query, $text );
 640         return;
 641     }
 642     # do topic text manipulation like:
 643     $text =~ s/old/new/g;
 644     # do meta data manipulation like:
 645     $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
 646     $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
 647
 648 ### <a name="moveTopic( $web, $topic, $newWeb"></a> moveTopic( $web, $topic, $newWeb, $newTopic )
 649
 650 - `$web` source web - required
 651 - `$topic` source topic - required
 652 - `$newWeb` dest web
 653 - `$newTopic` dest topic
 654
 655 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.
 656
 657 The destination topic must not already exist.
 658
 659 Rename a topic to the $TWiki::cfg\{TrashWebName\} to delete it.
 660
 661 **Since:** TWiki::Plugins::VERSION 1.1
 662
 663     use Error qw( :try );
 664
 665     try {
 666         moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
 667     } catch Error::Simple with {
 668         my $e = shift;
 669         # see documentation on Error::Simple
 670     } catch TWiki::AccessControlException with {
 671         my $e = shift;
 672         # see documentation on TWiki::AccessControlException
 673     } otherwise {
 674         ...
 675     };
 676
 677 ### <a name="get_RevisionInfo($web, $topic, $"></a> getRevisionInfo($web, $topic, $rev, $attachment ) -&gt; ( $date, $user, $rev, $comment )
 678
 679 Get revision info of a topic or attachment
 680
 681 - `$web` - Web name, optional, e.g. `'Main'`
 682 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
 683 - `$rev` - revsion number, or tag name (can be in the format 1.2, or just the minor number)
 684 - `$attachment` -attachment filename
 685
 686 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" )`
 687
 688 <table border="1" cellpadding="0" cellspacing="0">
 689   <tr>
 690     <td> $date </td>
 691     <td> in epochSec </td>
 692   </tr>
 693   <tr>
 694     <td> $user </td>
 695     <td> Wiki name of the author (<strong>not</strong> login name) </td>
 696   </tr>
 697   <tr>
 698     <td> $rev </td>
 699     <td> actual rev number </td>
 700   </tr>
 701   <tr>
 702     <td> $comment </td>
 703     <td> WHAT COMMENT? </td>
 704   </tr>
 705 </table>
 706
 707 NOTE: if you are trying to get revision info for a topic, use `$meta->getRevisionInfo` instead if you can - it is significantly more efficient, and returns a user object that contains other user information.
 708
 709 NOTE: prior versions of TWiki may under some circumstances have returned the login name of the user rather than the wiki name; the code documentation was totally unclear, and we have been unable to establish the intent. However the wikiname is obviously more useful, so that is what is returned.
 710
 711 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 712
 713 ### <a name="get_RevisionAtTime( $web, $topic"></a> getRevisionAtTime( $web, $topic, $time ) -&gt; $rev
 714
 715 Get the revision number of a topic at a specific time.
 716
 717 - `$web` - web for topic
 718 - `$topic` - topic
 719 - `$time` - time (in epoch secs) for the rev
 720
 721 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)
 722
 723 **Since:** TWiki::Plugins::VERSION 1.1
 724
 725 ### <a name="readTopic( $web, $topic, $rev )"></a><a name="readTopic( $web, $topic, $rev ) "></a> readTopic( $web, $topic, $rev ) -&gt; ( $meta, $text )
 726
 727 Read topic text and meta data, regardless of access permissions.
 728
 729 - `$web` - Web name, required, e.g. `'Main'`
 730 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
 731 - `$rev` - revision to read (default latest)
 732
 733 Return: `( $meta, $text )` Meta data object and topic text
 734
 735 `$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.
 736
 737 This method **ignores** topic access permissions. You should be careful to use `checkAccessPermissions` to ensure the current user has read access to the topic.
 738
 739 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 740
 741 ### <a name="read_TopicText( $web, $topic, $r"></a> readTopicText( $web, $topic, $rev, $ignorePermissions ) -&gt; $text
 742
 743 Read topic text, including meta data
 744
 745 - `$web` - Web name, e.g. `'Main'`, or empty
 746 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
 747 - `$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.
 748 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
 749
 750 Return: `$text` Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
 751
 752 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..
 753
 754 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 755
 756 ### <a name="attachmentExists( $web, $topic,"></a><a name="attachmentExists( $web, $topic, "></a> attachmentExists( $web, $topic, $attachment ) -&gt; $boolean
 757
 758 Test if attachment exists
 759
 760 - `$web` - Web name, optional, e.g. `Main`.
 761 - `$topic` - Topic name, required, e.g. `TokyoOffice`, or `Main.TokyoOffice`
 762 - `$attachment` - attachment name, e.g.=logo.gif=
 763
 764 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
 765
 766 **Since:** TWiki::Plugins::VERSION 1.1
 767
 768 ### <a name="readAttachment( $web, $topic, $n"></a> readAttachment( $web, $topic, $name, $rev ) -&gt; $data
 769
 770 - `$web` - web for topic
 771 - `$topic` - topic
 772 - `$name` - attachment name
 773 - `$rev` - revision to read (default latest)
 774
 775 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.
 776
 777 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 user passed in.
 778
 779     my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic );
 780     my @attachments = $meta->find( 'FILEATTACHMENT' );
 781     foreach my $a ( @attachments ) {
 782        try {
 783            my $data = TWiki::Func::readAttachment( $meta, $a->{name} );
 784            ...
 785        } catch TWiki::AccessControlException with {
 786        };
 787     }
 788
 789 **Since:** TWiki::Plugins::VERSION 1.1
 790
 791 ### <a name="saveAttachment( $web, $topic, $a"></a> saveAttachment( $web, $topic, $attachment, $opts )
 792
 793 - `$web` - web for topic
 794 - `$topic` - topic to atach to
 795 - `$attachment` - name of the attachment
 796 - `$opts` - Ref to hash of options
 797
 798 `$opts` may include:
 799
 800 <table border="1" cellpadding="0" cellspacing="0">
 801   <tr>
 802     <td><code>dontlog</code></td>
 803     <td> don't log this change in twiki log </td>
 804   </tr>
 805   <tr>
 806     <td><code>comment</code></td>
 807     <td> comment for save </td>
 808   </tr>
 809   <tr>
 810     <td><code>hide</code></td>
 811     <td> if the attachment is to be hidden in normal topic view </td>
 812   </tr>
 813   <tr>
 814     <td><code>stream</code></td>
 815     <td> Stream of file to upload </td>
 816   </tr>
 817   <tr>
 818     <td><code>file</code></td>
 819     <td> Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. </td>
 820   </tr>
 821   <tr>
 822     <td><code>filepath</code></td>
 823     <td> Client path to file </td>
 824   </tr>
 825   <tr>
 826     <td><code>filesize</code></td>
 827     <td> Size of uploaded data </td>
 828   </tr>
 829   <tr>
 830     <td><code>filedate</code></td>
 831     <td> Date </td>
 832   </tr>
 833 </table>
 834
 835 Save an attachment to the store for a topic. On success, returns undef. If there is an error, an exception will be thrown.
 836
 837         try {
 838             TWiki::Func::saveAttachment( $web, $topic, 'image.gif',
 839                                          { file => 'image.gif',
 840                                            comment => 'Picture of Health',
 841                                            hide => 1 } );
 842        } catch Error::Simple with {
 843           # see documentation on Error
 844        } otherwise {
 845           ...
 846        };
 847
 848 **Since:** TWiki::Plugins::VERSION 1.1
 849
 850 ### <a name="moveAttachment( $web, $topic, $a"></a> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )
 851
 852 - `$web` source web - required
 853 - `$topic` source topic - required
 854 - `$attachment` source attachment - required
 855 - `$newWeb` dest web
 856 - `$newTopic` dest topic
 857 - `$newAttachment` dest attachment
 858
 859 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.
 860
 861 The destination topic must already exist, but the destination attachment must **not** exist.
 862
 863 Rename an attachment to $TWiki::cfg\{TrashWebName\}.TrashAttament to delete it.
 864
 865     use Error qw( :try );
 866
 867     try {
 868        # move attachment between topics
 869        moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat",
 870                          "Countries", "France" );
 871        # Note destination attachment name is defaulted to the same as source
 872     } catch TWiki::AccessControlException with {
 873        my $e = shift;
 874        # see documentation on TWiki::AccessControlException
 875     } catch Error::Simple with {
 876        my $e = shift;
 877        # see documentation on Error::Simple
 878     };
 879
 880 **Since:** TWiki::Plugins::VERSION 1.1
 881
 882 ## <a name="Assembling Pages"></a> Assembling Pages
 883
 884 ### <a name="readTemplate( $name, $skin ) - $"></a> readTemplate( $name, $skin ) -&gt; $text
 885
 886 Read a template or skin. Embedded [[template directives|TWiki/TWikiTemplates]] get expanded
 887
 888 - `$name` - Template name, e.g. `'view'`
 889 - `$skin` - Comma-separated list of skin names, optional, e.g. `'print'`
 890
 891 Return: `$text` Template text
 892
 893 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 894
 895 ### <a name="loadTemplate ( $name, $skin, $we"></a> loadTemplate ( $name, $skin, $web ) -&gt; $text
 896
 897 - `$name` - template file name
 898 - `$skin` - comma-separated list of skins to use (default: current skin)
 899 - `$web` - the web to look in for topics that contain templates (default: current web)
 900
 901 Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)
 902
 903 **Since:** TWiki::Plugins::VERSION 1.1
 904
 905 Reads a template and extracts template definitions, adding them to the list of loaded templates, overwriting any previous definition.
 906
 907 How TWiki searches for templates is described in [[TWikiTemplates]].
 908
 909 If template text is found, extracts include statements and fully expands them.
 910
 911 ### <a name="expandTemplate( $def  ) - $strin"></a> expandTemplate( $def ) -&gt; $string
 912
 913 Do a , only expanding the template (not expanding any variables other than %TMPL)
 914
 915 - `$def` - template name
 916
 917 Return: the text of the expanded template
 918
 919 **Since:** TWiki::Plugins::VERSION 1.1
 920
 921 A template is defined using a %TMPL:DEF% statement in a template file. See the documentation on TWiki templates for more information.
 922
 923 ### <a name="writeHeader( $query, $contentLen"></a> writeHeader( $query, $contentLength )
 924
 925 Prints a basic content-type HTML header for text/html to standard out
 926
 927 - `$query` - CGI query object. If not given, the default CGI query will be used. In most cases you should _not_ pass this parameter.
 928 - `$contentLength` - Length of content
 929
 930 Return: none
 931
 932 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 933
 934 ### <a name="redirect_CgiQuery( $query, $url"></a><a name="redirect_CgiQuery( $query, $url "></a> redirectCgiQuery( $query, $url )
 935
 936 Redirect to URL
 937
 938 - `$query` - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
 939 - `$url` - URL to redirect to
 940
 941 Return: none, never returns
 942
 943 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 944
 945 ### <a name="add_ToHEAD( $id, $header )"></a> addToHEAD( $id, $header )
 946
 947 Adds `$header` to the HTML header (the
 948
 949 tag). This is useful for Plugins that want to include some javascript custom css.
 950
 951 - `$id` - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN\_JSCALENDAR)
 952 - `$header` - the HTML to be added to the
 953
 954 section. The HTML must be valid in a HEAD tag - no checks are performed.
 955
 956 All TWiki variables present in `$header` will be expanded before being inserted into the ``
 957
 958 section.
 959
 960 Note that this is _not_ the same as the HTTP header, which is modified through the Plugins `modifyHeaderHandler`.
 961
 962 **Since:** TWiki::Plugins::VERSION 1.1
 963
 964 example:
 965
 966     TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')
 967
 968 ### <a name="expand_CommonVariables( $text, $"></a> expandCommonVariables( $text, $topic, $web ) -&gt; $text
 969
 970 Expand all common `%VARIABLES%`
 971
 972 - `$text` - Text with variables to expand, e.g. `'Current user is %WIKIUSER%'`
 973 - `$topic` - Current topic name, e.g. `'WebNotify'`
 974 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
 975
 976 Return: `$text` Expanded text, e.g. `'Current user is TWikiGuest'`
 977
 978 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 979
 980 See also: expandVariablesOnTopicCreation
 981
 982 ### <a name="renderText( $text, $web ) - $tex"></a> renderText( $text, $web ) -&gt; $text
 983
 984 Render text from TWiki markup into XHTML as defined in [[TWiki.TextFormattingRules|TWiki/TextFormattingRules]]
 985
 986 - `$text` - Text to render, e.g. `'*bold* text and =fixed font='`
 987 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
 988
 989 Return: `$text` XHTML text, e.g. `'<b>bold</b> and <code>fixed font</code>'`
 990
 991 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 992
 993 ### <a name="internalLink( $pre, $web, $topic"></a> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -&gt; $text
 994
 995 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()`
 996
 997 - `$pre` - Text occuring before the TWiki link syntax, optional
 998 - `$web` - Web name, required, e.g. `'Main'`
 999 - `$topic` - Topic name to link to, required, e.g. `'WebNotify'`
1000 - `$label` - Link label, required. Usually the same as `$topic`, e.g. `'notify'`
1001 - `$anchor` - Anchor, optional, e.g. `'#Jump'`
1002 - `$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
1003
1004 Return: `$text` XHTML anchor, e.g. `'<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'`
1005
1006 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1007
1008 ## <a name="E-mail"></a> E-mail
1009
1010 ### <a name="sendEmail ( $text, $retries ) -"></a><a name="sendEmail ( $text, $retries ) - "></a> sendEmail ( $text, $retries ) -&gt; $error
1011
1012 - `$text` - text of the mail, including MIME headers
1013 - `$retries` - number of times to retry the send (default 1)
1014
1015 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:
1016
1017     To: liz@windsor.gov.uk
1018     From: serf@hovel.net
1019     CC: george@whitehouse.gov
1020     Subject: Revolution
1021
1022     Dear Liz,
1023
1024     Please abolish the monarchy (with King George's permission, of course)
1025
1026     Thanks,
1027
1028     A. Peasant
1029
1030 Leave a blank line between the last header field and the message body.
1031
1032 **Since:** TWiki::Plugins::VERSION 1.1
1033
1034 ### <a name="wiki_ToEmail( $wikiName ) - $ema"></a> wikiToEmail( $wikiName ) -&gt; $email
1035
1036 - `$wikiName` - wiki name of the user
1037
1038 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.
1039
1040 **Since:** TWiki::Plugins::VERSION 1.1
1041
1042 ## <a name="Creating New Topics"></a> Creating New Topics
1043
1044 ### <a name="expand_VariablesOnTopicCreation"></a><a name="expand_VariablesOnTopicCreation "></a> expandVariablesOnTopicCreation ( $text ) -&gt; $text
1045
1046 Expand the limited set of variables that are always expanded during topic creation
1047
1048 - `$text` - the text to process
1049
1050 Return: text with variables expanded
1051
1052 **Since:** TWiki::Plugins::VERSION 1.1
1053
1054 Expands only the variables expected in templates that must be statically expanded in new content.
1055
1056 The expanded variables are:
1057
1058 - `%DATE%` Signature-format date
1059 - `%SERVERTIME%` See [[TWikiVariables]]
1060 - `%GMTIME%` See [[TWikiVariables]]
1061 - `%USERNAME%` Base login name
1062 - `%WIKINAME%` Wiki name
1063 - `%WIKIUSERNAME%` Wiki name with prepended web
1064 - `%URLPARAM{...}%` - Parameters to the current CGI query
1065 - `%NOP%` No-op
1066
1067 See also: expandVariables
1068
1069 ## <a name="Special handlers"></a> Special handlers
1070
1071 Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.
1072
1073 ### <a name="register_TagHandler( $var, \fn,"></a><a name="register_TagHandler( $var, \fn, "></a> registerTagHandler( $var, \\&amp;fn, $syntax )
1074
1075 Should only be called from initPlugin.
1076
1077 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`.
1078
1079 - `$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.
1080 - `\&fn` - Reference to the handler function.
1081 - `$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"\}%
1082
1083 **Since:** TWiki::Plugins::VERSION 1.1
1084
1085 The variable handler function must be of the form:
1086
1087     sub handler(\%session, \%params, $topic, $web)
1088
1089 where:
1090
1091 - `\%session` - a reference to the TWiki session object (may be ignored)
1092 - `\%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.
1093 - `$topic` - name of the topic in the query
1094 - `$web` - name of the web in the query
1095
1096 for example, to execute an arbitrary command on the server, you might do this:
1097
1098     sub initPlugin{
1099        TWiki::Func::registerTagHandler('EXEC', \&boo);
1100     }
1101
1102     sub boo {
1103         my( $session, $params, $topic, $web ) = @_;
1104         my $cmd = $params->{_DEFAULT};
1105
1106         return "NO COMMAND SPECIFIED" unless $cmd;
1107
1108         my $result = `$cmd 2>&1`;
1109         return $params->{silent} ? '' : $result;
1110     }
1111     }
1112
1113 would let you do this: `%EXEC{"ps -Af" silent="on"}%`
1114
1115 ### <a name="registerRESTHandler( $alias, \fn"></a> registerRESTHandler( $alias, \\&amp;fn, )
1116
1117 Should only be called from initPlugin.
1118
1119 Adds a function to the dispatch table of the REST interface
1120
1121 - `$alias` - The name .
1122 - `\&fn` - Reference to the function.
1123
1124 **Since:** TWiki::Plugins::VERSION 1.1
1125
1126 The handler function must be of the form:
1127
1128     sub handler(\%session)
1129
1130 where:
1131
1132 - `\%session` - a reference to the TWiki session object (may be ignored)
1133
1134 From the REST interface, the name of the plugin must be used as the subject of the invokation.
1135
1136 Example
1137
1138 ----
1139
1140 The [[EmptyPlugin]] has the following call in the initPlugin handler:
1141
1142        TWiki::Func::registerRESTHandler('example', \&restExample);
1143
1144 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
1145
1146 `http://server:port/bin/rest/EmptyPlugin/example`
1147
1148 note that the URL
1149
1150 `http://server:port/bin/rest/EmptyPlugin/restExample`
1151
1152 (ie, with the name of the function instead of the alias) will not work.
1153
1154 ## <a name="Searching"></a> Searching
1155
1156 ### <a name="search_InWebContent($searchStrin"></a> searchInWebContent($searchString, $web, \\@topics, \\%options ) -&gt; \\%map
1157
1158 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+\{.\*\}%)
1159
1160 - `$searchString` - the search string, in egrep format
1161 - `$web` - The web to search in
1162 - `\@topics` - reference to a list of topics to search
1163 - `\%option` - reference to an options hash
1164
1165 The `\%options` hash may contain the following options:
1166
1167 - `type` - if `regex` will perform a egrep-syntax RE search (default '')
1168 - `casesensitive` - false to ignore case (defaulkt true)
1169 - `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).
1170
1171 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'.
1172
1173 To iterate over the returned topics use:
1174
1175     my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics,
1176        { casesensitive => 0, files_without_match => 0 } );
1177     foreach my $topic (keys %$result ) {
1178        foreach my $matching_line ( @{$result->{$topic}} ) {
1179           ...etc
1180
1181 **Since:** TWiki::Plugins::VERSION 1.1
1182
1183 ## <a name="Plugin-specific file handling"></a> Plugin-specific file handling
1184
1185 ### <a name="get_WorkArea( $pluginName ) - $d"></a> getWorkArea( $pluginName ) -&gt; $directorypath
1186
1187 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.
1188
1189 The directory is guaranteed to exist, and to be writable by the webserver user. By default it will **not** be web accessible.
1190
1191 The directory and it's contents are permanent, so Plugins must be careful to keep their areas tidy.
1192
1193 **Since:** TWiki::Plugins::VERSION 1.1 (Dec 2005)
1194
1195 ### <a name="readFile( $filename ) - $text"></a> readFile( $filename ) -&gt; $text
1196
1197 Read file, low level. Used for Plugin workarea.
1198
1199 - `$filename` - Full path name of file
1200
1201 Return: `$text` Content of file, empty if not found
1202
1203 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1204
1205 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1206
1207 ### <a name="saveFile( $filename, $text )"></a> saveFile( $filename, $text )
1208
1209 Save file, low level. Used for Plugin workarea.
1210
1211 - `$filename` - Full path name of file
1212 - `$text` - Text to save
1213
1214 Return: none
1215
1216 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1217
1218 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1219
1220 ## <a name="General Utilities"></a> General Utilities
1221
1222 ### <a name="get_RegularExpression( $name ) -"></a> getRegularExpression( $name ) -&gt; $expr
1223
1224 Retrieves a TWiki predefined regular expression or character class.
1225
1226 - `$name` - Name of the expression to retrieve. See notes below
1227
1228 Return: String or precompiled regular expression matching as described below.
1229
1230 **Since:** TWiki::Plugins::VERSION 1.020 (9 Feb 2004)
1231
1232 **_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.
1233
1234 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:
1235
1236        my $upper = TWiki::Func::getRegularExpression('upperAlpha');
1237        my $alpha = TWiki::Func::getRegularExpression('mixedAlpha');
1238        my $capitalized = qr/[$upper][$alpha]+/;
1239
1240 Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
1241
1242        my $webRE = TWiki::Func::getRegularExpression('webNameRegex');
1243        my $isWebName = ( $s =~ m/$webRE/ );
1244
1245 <table border="1" cellpadding="0" cellspacing="0">
1246   <tr>
1247     <th bgcolor="#99CCCC"><strong> Name </strong></th>
1248     <th bgcolor="#99CCCC"><strong> Matches </strong></th>
1249     <th bgcolor="#99CCCC"><strong> Type </strong></th>
1250   </tr>
1251   <tr>
1252     <td> upperAlpha </td>
1253     <td> Upper case characters </td>
1254     <td> String </td>
1255   </tr>
1256   <tr>
1257     <td> upperAlphaNum </td>
1258     <td> Upper case characters and digits </td>
1259     <td> String </td>
1260   </tr>
1261   <tr>
1262     <td> lowerAlpha </td>
1263     <td> Lower case characters </td>
1264     <td> String </td>
1265   </tr>
1266   <tr>
1267     <td> lowerAlphaNum </td>
1268     <td> Lower case characters and digits </td>
1269     <td> String </td>
1270   </tr>
1271   <tr>
1272     <td> numeric </td>
1273     <td> Digits </td>
1274     <td> String </td>
1275   </tr>
1276   <tr>
1277     <td> mixedAlpha </td>
1278     <td> Alphabetic characters </td>
1279     <td> String </td>
1280   </tr>
1281   <tr>
1282     <td> mixedAlphaNum </td>
1283     <td> Alphanumeric characters </td>
1284     <td> String </td>
1285   </tr>
1286   <tr>
1287     <td> wikiWordRegex </td>
1288     <td>[[Main/WikiWords]]</td>
1289     <td> RE </td>
1290   </tr>
1291   <tr>
1292     <td> webNameRegex </td>
1293     <td> User web names </td>
1294     <td> RE </td>
1295   </tr>
1296   <tr>
1297     <td> anchorRegex </td>
1298     <td> #AnchorNames </td>
1299     <td> RE </td>
1300   </tr>
1301   <tr>
1302     <td> abbrevRegex </td>
1303     <td> Abbreviations e.g. GOV, IRS </td>
1304     <td> RE </td>
1305   </tr>
1306   <tr>
1307     <td> emailAddrRegex </td>
1308     <td><a href="mailto:email@address.com">email@address.com</a></td>
1309     <td> RE </td>
1310   </tr>
1311   <tr>
1312     <td> tagNameRegex </td>
1313     <td> Standard variable names e.g. %THIS_BIT% (THIS_BIT only) </td>
1314     <td> RE </td>
1315   </tr>
1316 </table>
1317
1318 ### <a name="normalize_WebTopicName($web, $to"></a> normalizeWebTopicName($web, $topic) -&gt; ($web, $topic)
1319
1320 Parse a web and topic name, supplying defaults as appropriate.
1321
1322 - `$web` - Web name, identifying variable, or empty string
1323 - `$topic` - Topic name, may be a web.topic string, required.
1324
1325 Return: the parsed Web/Topic pai
1326
1327 **Since:** TWiki::Plugins::VERSION 1.1
1328
1329 <table border="1" cellpadding="0" cellspacing="0">
1330   <tr>
1331     <th bgcolor="#99CCCC"><strong> Input </strong></th>
1332     <th bgcolor="#99CCCC"><strong> Return </strong></th>
1333   </tr>
1334   <tr>
1335     <td><tt>( 'Web', 'Topic' ) </tt></td>
1336     <td><tt>( 'Web', 'Topic' ) </tt></td>
1337   </tr>
1338   <tr>
1339     <td><tt>( '', 'Topic' ) </tt></td>
1340     <td><tt>( 'Main', 'Topic' ) </tt></td>
1341   </tr>
1342   <tr>
1343     <td><tt>( '', '' ) </tt></td>
1344     <td><tt>( 'Main', 'WebHome' ) </tt></td>
1345   </tr>
1346   <tr>
1347     <td><tt>( '', 'Web/Topic' ) </tt></td>
1348     <td><tt>( 'Web', 'Topic' ) </tt></td>
1349   </tr>
1350   <tr>
1351     <td><tt>( '', 'Web.Topic' ) </tt></td>
1352     <td><tt>( 'Web', 'Topic' ) </tt></td>
1353   </tr>
1354   <tr>
1355     <td><tt>( 'Web1', 'Web2.Topic' )</tt></td>
1356     <td><tt>( 'Web2', 'Topic' ) </tt></td>
1357   </tr>
1358   <tr>
1359     <td><tt>( 'Main', 'Topic' )</tt></td>
1360     <td><tt>( 'Main', 'Topic' ) </tt></td>
1361   </tr>
1362   <tr>
1363     <td><tt>( 'TWiki', 'Topic' )</tt></td>
1364     <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1365   </tr>
1366 </table>
1367
1368 where `Main` and `TWiki` are the web names set in $cfg\{UsersWebName\} and $cfg\{SystemWebName\} respectively.
1369
1370 ### <a name="writeWarning( $text )"></a> writeWarning( $text )
1371
1372 Log Warning that may require admin intervention to data/warning.txt
1373
1374 - `$text` - Text to write; timestamp gets added
1375
1376 Return: none
1377
1378 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1379
1380 ### <a name="writeDebug( $text )"></a> writeDebug( $text )
1381
1382 Log debug message to data/debug.txt
1383
1384 - `$text` - Text to write; timestamp gets added
1385
1386 Return: none
1387
1388 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1389
1390 ### <a name="formatTime( $time, $format, $tim"></a> formatTime( $time, $format, $timezone ) -&gt; $text
1391
1392 Format the time in seconds into the desired time string
1393
1394 - `$time` - Time in epoc seconds
1395 - `$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
1396 - `$timezone` - either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
1397
1398 Return: `$text` Formatted time string
1399
1400 <table border="1" cellpadding="0" cellspacing="0">
1401   <tr>
1402     <td> Note: </td>
1403     <td> if you used the removed formatGmTime, add a third parameter 'gmtime' </td>
1404   </tr>
1405 </table>
1406
1407 **Since:** TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
1408
1409 ### <a name="is_ValidWikiWord ( $text ) - $bo"></a> isValidWikiWord ( $text ) -&gt; $boolean
1410
1411 Check for a valid [[WikiWord]] or [[WikiName]]
1412
1413 - `$text` - Word to test
1414
1415 **Since:** TWiki::Plugins::VERSION 1.100 (Dec 2005)
1416
1417 ### <a name="extractParameters($attr ) - %par"></a> extractParameters($attr ) -&gt; %params
1418
1419 Extract all parameters from a variable string and returns a hash of parameters
1420
1421 - `$attr` - Attribute string
1422
1423 Return: `%params` Hash containing all parameters. The nameless parameter is stored in key `_DEFAULT`
1424
1425 **Since:** TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
1426
1427 - Example:
1428   - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1429   - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1430   - Then call this on the text: <br />
1431 - params = TWiki::Func::extractParameters( $text );=
1432   - The `%params` hash contains now: <br />`_DEFAULT => 'nameless'`<br />`name1 => "val1"`<br />`name2 => "val2"`
1433
1434 ### <a name="extract_NameValuePair( $attr, $n"></a> extractNameValuePair( $attr, $name ) -&gt; $value
1435
1436 Extract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters
1437
1438 - `$attr` - Attribute string
1439 - `$name` - Name, optional
1440
1441 Return: `$value` Extracted value
1442
1443 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1444
1445 - Example:
1446   - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1447   - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1448   - 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" );`
1449
1450 ## <a name="Deprecated functions"></a> Deprecated functions
1451
1452 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.
1453
1454 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%.
1455
1456 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:
1457
1458     package TWiki::Plugins::SinkPlugin;
1459     use vars qw( %TWikiCompatibility );
1460     $TWikiCompatibility{endRenderingHandler} = 1.1;
1461
1462 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.
1463
1464 The following functions are retained for compatibility only. You should stop using them as soon as possible.
1465
1466 ### <a name="get_ScriptUrlPath( ) - $path"></a> getScriptUrlPath( ) -&gt; $path
1467
1468 Get script URL path
1469
1470 **DEPRECATED** since 1.1 - use `getScriptUrl` instead.
1471
1472 Return: `$path` URL path of TWiki scripts, e.g. `"/cgi-bin"`
1473
1474 **WARNING:** you are strongly recommended **not** to use this function, as the \{ScriptUrlPaths\} URL rewriting rules will not apply to urls generated using it.
1475
1476 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1477
1478 ### <a name="get_PublicWebList( ) - @webs"></a> getPublicWebList( ) -&gt; @webs
1479
1480 **DEPRECATED** since 1.1 - use `getListOfWebs` instead.
1481
1482 Get list of all public webs, e.g. all webs that do not have the `NOSEARCHALL` flag set in the [[WebPreferences]]
1483
1484 Return: `@webs` List of all public webs, e.g. `( 'Main',  'Know', 'TWiki' )`
1485
1486 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1487
1488 ### <a name="format_GmTime( $time, $format )"></a><a name="format_GmTime( $time, $format ) "></a> formatGmTime( $time, $format ) -&gt; $text
1489
1490 **DEPRECATED** since 1.1 - use `formatTime` instead.
1491
1492 Format the time to GM time
1493
1494 - `$time` - Time in epoc seconds
1495 - `$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'`)
1496
1497 Return: `$text` Formatted time string
1498
1499 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1500
1501 ### <a name="get_DataDir( ) - $dir"></a> getDataDir( ) -&gt; $dir
1502
1503 **DEPRECATED** since 1.1 - use the [[content handling functions|Main/WebHome#Functions_Content_Handling]] to manipulate topics instead
1504
1505 Get data directory (topic file root)
1506
1507 Return: `$dir` Data directory, e.g. `'/twiki/data'`
1508
1509 This function violates store encapsulation and is therefore **deprecated**.
1510
1511 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1512
1513 ### <a name="get_PubDir( ) - $dir"></a> getPubDir( ) -&gt; $dir
1514
1515 **DEPRECATED** since 1.1 - use the [[content handling functions|Main/WebHome#Functions_Content_Handling]] to manipulateattachments instead
1516
1517 Get pub directory (file attachment root). Attachments are in `$dir/Web/TopicName`
1518
1519 Return: `$dir` Pub directory, e.g. `'/htdocs/twiki/pub'`
1520
1521 This function violates store encapsulation and is therefore **deprecated**.
1522
1523 Use `readAttachment` and `saveAttachment` instead.
1524
1525 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1526
1527 ### <a name="checkDependencies( $moduleName,"></a><a name="checkDependencies( $moduleName, "></a> checkDependencies( $moduleName, $dependenciesRef ) -&gt; $error
1528
1529 **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.
1530
1531 **Since:** TWiki::Plugins::VERSION 1.025 (01 Aug 2004)