TWiki/TWikiDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki="></a> Package =TWiki
   2
   3 TWiki operates by creating a singleton object (known as the Session object) that acts as a point of reference for all the different modules in the system. This package is the class for this singleton, and also contains the vast bulk of the basic constants and the per- site configuration mechanisms.
   4
   5 Global variables are avoided wherever possible to avoid problems with CGI accelerators such as mod\_perl.
   6
   7 <div>
   8   <ul>
   9     <li><a href="#Package =TWiki="> Package TWiki</a><ul>
  10         <li><a href="#StaticMethod <strong>get_TWikiLibDir</strong> ("> StaticMethod getTWikiLibDir <tt>() -&gt; $path</tt></a></li>
  11         <li><a href="#ObjectMethod *_UTF82SiteCharSet*"> ObjectMethod UTF82SiteCharSet <tt>($utf8) -&gt; $ascii</tt></a></li>
  12         <li><a href="#ObjectMethod *write_CompletePage"> ObjectMethod writeCompletePage <tt>($text,$pageType,$contentType)</tt></a></li>
  13         <li><a href="#ObjectMethod *write_PageHeader*"> ObjectMethod writePageHeader <tt>($query,$pageType,$contentType,$contentLength)</tt></a></li>
  14         <li><a href="#ObjectMethod <strong>redirect</strong> ($url,.."> ObjectMethod redirect <tt>($url,...)</tt></a></li>
  15         <li><a href="#StaticMethod *is_ValidWikiWord*"> StaticMethod isValidWikiWord <tt>($name) -&gt; $boolean</tt></a></li>
  16         <li><a href="#StaticMethod *is_ValidTopicName*"> StaticMethod isValidTopicName <tt>($name) -&gt; $boolean</tt></a></li>
  17         <li><a href="#StaticMethod <strong>is_ValidAbbrev</strong> ($"> StaticMethod isValidAbbrev <tt>($name) -&gt; $boolean</tt></a></li>
  18         <li><a href="#StaticMethod <strong>is_ValidWebName</strong> ("> StaticMethod isValidWebName <tt>($name,$system) -&gt; $boolean</tt></a></li>
  19         <li><a href="#ObjectMethod *read_OnlyMirrorWeb"> ObjectMethod readOnlyMirrorWeb <tt>($theWeb) -&gt; ($mirrorSiteName,$mirrorViewURL,$mirrorLink,$mirrorNote)</tt></a></li>
  20         <li><a href="#ObjectMethod <strong>getSkin</strong> () -> $st"> ObjectMethod getSkin <tt>() -&gt; $string</tt></a></li>
  21         <li><a href="#ObjectMethod <strong>get_ScriptUrl</strong> ($a"> ObjectMethod getScriptUrl <tt>($absolute,$script,$web,$topic,...) -&gt; $scriptURL</tt></a></li>
  22         <li><a href="#ObjectMethod <strong>get_PubUrl</strong> ($abso"> ObjectMethod getPubUrl <tt>($absolute,$web,$topic,$attachment) -&gt; $url</tt></a></li>
  23         <li><a href="#ObjectMethod <strong>get_IconUrl</strong> ($abs"> ObjectMethod getIconUrl <tt>($absolute,$iconName) -&gt; $iconURL</tt></a></li>
  24         <li><a href="#ObjectMethod *map_ToIconFileName"> ObjectMethod mapToIconFileName <tt>($fileName,$default) -&gt; $fileName</tt></a></li>
  25         <li><a href="#ObjectMethod <strong>get_OopsUrl</strong> ($tem"> ObjectMethod getOopsUrl <tt>($template,@options) -&gt; $absoluteOopsURL</tt></a></li>
  26         <li><a href="#ObjectMethod *normalize_WebTopic"> ObjectMethod normalizeWebTopicName <tt>($theWeb,$theTopic) -&gt; ($theWeb,$theTopic)</tt></a></li>
  27         <li><a href="#ClassMethod <strong>new</strong> ($remoteUser,$"> ClassMethod new <tt>($remoteUser,$query)</tt></a></li>
  28         <li><a href="#ObjectMethod *finish*"> ObjectMethod finish <tt></tt></a></li>
  29         <li><a href="#ObjectMethod <strong>writeLog</strong> ($action"> ObjectMethod writeLog <tt>($action,$webTopic,$extra,$user)</tt></a></li>
  30         <li><a href="#ObjectMethod <strong>writeWarning</strong> ($te"> ObjectMethod writeWarning <tt>($text)</tt></a></li>
  31         <li><a href="#ObjectMethod <strong>writeDebug</strong> ($text"> ObjectMethod writeDebug <tt>($text)</tt></a></li>
  32         <li><a href="#StaticMethod *apply_PatternToInc"> StaticMethod applyPatternToIncludedText <tt>($text,$pattern) -&gt; $text</tt></a></li>
  33         <li><a href="#ObjectMethod <strong>inlineAlert</strong> ($tem"> ObjectMethod inlineAlert <tt>($template,$def,...) -&gt; $string</tt></a></li>
  34         <li><a href="#ObjectMethod *expand_VariablesOn"> ObjectMethod expandVariablesOnTopicCreation <tt>($text,$user) -&gt; $text</tt></a></li>
  35         <li><a href="#StaticMethod <strong>entityEncode</strong> ($te"> StaticMethod entityEncode <tt>($text,$extras) -&gt; $encodedText</tt></a></li>
  36         <li><a href="#StaticMethod <strong>entityDecode</strong> ($en"> StaticMethod entityDecode <tt>($encodedText) -&gt; $text</tt></a></li>
  37         <li><a href="#StaticMethod <strong>urlEncode</strong> ($strin"> StaticMethod urlEncode <tt>($string) -&gt; encodedstring</tt></a></li>
  38         <li><a href="#StaticMethod <strong>urlDecode</strong> ($strin"> StaticMethod urlDecode <tt>($string) -&gt; decodedstring</tt></a></li>
  39         <li><a href="#StaticMethod <strong>isTrue</strong> ($value,$d"> StaticMethod isTrue <tt>($value,$default) -&gt; $boolean</tt></a></li>
  40         <li><a href="#StaticMethod *space_OutWikiWord*"> StaticMethod spaceOutWikiWord <tt>($word,$sep) -&gt; $string</tt></a></li>
  41         <li><a href="#ObjectMethod <strong>enterContext</strong> ($id"> ObjectMethod enterContext <tt>($id,$val)</tt></a></li>
  42         <li><a href="#ObjectMethod <strong>leaveContext</strong> ($id"> ObjectMethod leaveContext <tt>($id)</tt></a></li>
  43         <li><a href="#ObjectMethod <strong>inContext</strong> ($id)"> ObjectMethod inContext <tt>($id)</tt></a></li>
  44         <li><a href="#StaticMethod *register_TagHandle"> StaticMethod registerTagHandler <tt>($tag,$fnref)</tt></a><ul>
  45             <li><a href="#registerRESTHandler( $subject, $"> registerRESTHandler( $subject, $verb, \&amp;fn )</a></li>
  46             <li><a href="#restDispatch( $subject, $verb) ="> restDispatch( $subject, $verb) =&gt; \&amp;fn</a></li>
  47           </ul>
  48         </li>
  49         <li><a href="#ObjectMethod *handle_CommonTags*"> ObjectMethod handleCommonTags <tt>($text,$web,$topic) -&gt; $text</tt></a></li>
  50         <li><a href="#ObjectMethod <strong>add_ToHEAD</strong> ($id,$"> ObjectMethod addToHEAD <tt>($id,$html)</tt></a></li>
  51         <li><a href="#StaticMethod <strong>initialize</strong> ($path"> StaticMethod initialize <tt>($pathInfo,$remoteUser,$topic,$url,$query) -&gt; ($topicName,$webName,$scriptUrlPath,$userName,$dataDir)</tt></a></li>
  52         <li><a href="#StaticMethod <strong>readFile</strong> ($filena"> StaticMethod readFile <tt>($filename) -&gt; $text</tt></a></li>
  53       </ul>
  54     </li>
  55   </ul>
  56 </div>
  57
  58 ## <a name="StaticMethod &lt;strong&gt;get_TWikiLibDir&lt;/strong&gt; ("></a> [[StaticMethod]] **getTWikiLibDir** `() -> $path`
  59
  60 STATIC method.
  61
  62 Returns the full path of the directory containing TWiki.pm
  63
  64 ## <a name="ObjectMethod &lt;strong&gt;_UTF82SiteCharSet*"></a> [[ObjectMethod]] \*UTF82SiteCharSet `($utf8) -> $ascii`
  65
  66 Auto-detect UTF-8 vs. site charset in string, and convert UTF-8 into site charset.
  67
  68 ## <a name="ObjectMethod &lt;strong&gt;write_CompletePage"></a> [[ObjectMethod]] \*writeCompletePage `($text,$pageType,$contentType)`
  69
  70 Write a complete HTML page with basic header to the browser. $text is the HTML of the page body (&lt;html&gt; to &lt;/html&gt;)
  71
  72 This method removes noautolink and nop tags before outputting the page.
  73
  74 ## <a name="ObjectMethod &lt;strong&gt;write_PageHeader*"></a><a name="ObjectMethod *write_PageHeader&lt;/strong&gt; "></a> [[ObjectMethod]] **writePageHeader** `($query,$pageType,$contentType,$contentLength)`
  75
  76 All parameters are optional.
  77
  78 - `$query` CGI query object | Session CGI query (there is no good reason to set this)
  79 - `$pageType` - May be "edit", which will cause headers to be generated that force caching for 24 hours, to prevent [[BackFromPreviewLosesText]] bug, which caused data loss with IE5 and IE6.
  80 - `$contentType` - page content type | text/html
  81 - `$contentLength` - content-length | no content-length will be set if this is undefined, as required by HTTP1.1
  82
  83 Implements the post-Dec2001 release plugin API, which requires the writeHeaderHandler in plugin to return a string of HTTP headers, CR/LF delimited. Filters any illegal headers. Plugin headers will override core settings.
  84
  85 ## <a name="ObjectMethod &lt;strong&gt;redirect&lt;/strong&gt; ($url,.."></a> [[ObjectMethod]] **redirect** `($url,...)`
  86
  87 Generate a CGI redirect to $url unless (1) $session-&gt;\{cgiQuery\} is undef or (2) $query-&gt;param('noredirect') is set to a true value. Thus a redirect is only generated when in a CGI context.
  88
  89 The ... parameters are concatenated to the message written when printing to STDOUT, and are ignored for a redirect.
  90
  91 Redirects the request to $url, via the CGI module object $query unless overridden by a plugin declaring a `redirectCgiQueryHandler`.
  92
  93 ## <a name="StaticMethod &lt;strong&gt;is_ValidWikiWord*"></a><a name="StaticMethod *is_ValidWikiWord&lt;/strong&gt; "></a> [[StaticMethod]] **isValidWikiWord** `($name) -> $boolean`
  94
  95 Check for a valid [[WikiWord]] or [[WikiName]]
  96
  97 ## <a name="StaticMethod &lt;strong&gt;is_ValidTopicName*"></a> [[StaticMethod]] \*isValidTopicName `($name) -> $boolean`
  98
  99 Check for a valid topic name
 100
 101 ## <a name="StaticMethod &lt;strong&gt;is_ValidAbbrev&lt;/strong&gt; ($"></a> [[StaticMethod]] **isValidAbbrev** `($name) -> $boolean`
 102
 103 Check for a valid ABBREV (acronym)
 104
 105 ## <a name="StaticMethod &lt;strong&gt;is_ValidWebName&lt;/strong&gt; ("></a> [[StaticMethod]] **isValidWebName** `($name,$system) -> $boolean`
 106
 107 STATIC Check for a valid web name. If $system is true, then system web names are considered valid (names starting with \_) otherwise only user web names are valid
 108
 109 ## <a name="ObjectMethod &lt;strong&gt;read_OnlyMirrorWeb"></a> [[ObjectMethod]] \*readOnlyMirrorWeb `($theWeb) -> ($mirrorSiteName,$mirrorViewURL,$mirrorLink,$mirrorNote)`
 110
 111 If this is a mirrored web, return information about the mirror. The info is returned in a quadruple:
 112
 113 <table border="1" cellpadding="0" cellspacing="0">
 114   <tr>
 115     <td> site name </td>
 116     <td> URL </td>
 117     <td> link </td>
 118     <td> note </td>
 119   </tr>
 120 </table>
 121
 122 ## <a name="ObjectMethod &lt;strong&gt;getSkin&lt;/strong&gt; () - $str"></a> [[ObjectMethod]] **getSkin** `() -> $string`
 123
 124 Get the currently requested skin path
 125
 126 ## <a name="ObjectMethod &lt;strong&gt;get_ScriptUrl&lt;/strong&gt; ($a"></a> [[ObjectMethod]] **getScriptUrl** `($absolute,$script,$web,$topic,...) -> $scriptURL`
 127
 128 Returns the URL to a TWiki script, providing the web and topic as "path info" parameters. The result looks something like this: "http://host/twiki/bin/$script/$web/$topic".
 129
 130 - `...` - 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#XXX?a=1&b=2`
 131
 132 If $absolute is set, generates an absolute URL. $absolute is advisory only; TWiki can decide to generate absolute URLs (for example when run from the command-line) even when relative URLs have been requested.
 133
 134 The default script url is taken from \{ScriptUrlPath\}, unless there is an exception defined for the given script in \{ScriptUrlPaths\}. Both \{ScriptUrlPath\} and \{ScriptUrlPaths\} may be absolute or relative URIs. If they are absolute, then they will always generate absolute URLs. if they are relative, then they will be converted to absolute when required (e.g. when running from the command line, or when generating rss). If $script is not given, absolute URLs will always be generated.
 135
 136 If either the web or the topic is defined, will generate a full url (including web and topic). Otherwise will generate only up to the script name. An undefined web will default to the main web name.
 137
 138 ## <a name="ObjectMethod &lt;strong&gt;get_PubUrl&lt;/strong&gt; ($abso"></a> [[ObjectMethod]] **getPubUrl** `($absolute,$web,$topic,$attachment) -> $url`
 139
 140 Composes a pub url. If $absolute is set, returns an absolute URL. If $absolute is set, generates an absolute URL. $absolute is advisory only; TWiki can decide to generate absolute URLs (for example when run from the command-line) even when relative URLs have been requested.
 141
 142 $web, $topic and $attachment are optional. A partial URL path will be generated if one or all is not given.
 143
 144 ## <a name="ObjectMethod &lt;strong&gt;get_IconUrl&lt;/strong&gt; ($abs"></a> [[ObjectMethod]] **getIconUrl** `($absolute,$iconName) -> $iconURL`
 145
 146 Map an icon name to a URL path.
 147
 148 ## <a name="ObjectMethod &lt;strong&gt;map_ToIconFileName"></a> [[ObjectMethod]] \*mapToIconFileName `($fileName,$default) -> $fileName`
 149
 150 Maps from a filename (or just the extension) to the name of the file that contains the image for that file type.
 151
 152 ## <a name="ObjectMethod &lt;strong&gt;get_OopsUrl&lt;/strong&gt; ($tem"></a> [[ObjectMethod]] **getOopsUrl** `($template,@options) -> $absoluteOopsURL`
 153
 154 Composes a URL for an "oops" error page. The @options consists of a list of key =&gt; value pairs. The following keys are used:
 155
 156 - `-web` - web name
 157 - `-topic` - topic name
 158 - `-def` - optional template def within the main template file
 159 - `-params` - a single parameter, or a reference to an array of parameters These are passed in the URL as '&amp;param1=' etc.
 160
 161 Do _not_ include the "oops" part in front of the template name.
 162
 163 Alternatively you can pass a reference to an [[OopsException]] in place of the template. All other parameters will be ignored.
 164
 165 The returned URL ends up looking something like this: "http://host/twiki/bin/oops/$web/$topic?template=$template&amp;param1=$scriptParams[0]..."
 166
 167 ## <a name="ObjectMethod &lt;strong&gt;normalize_WebTopic"></a> [[ObjectMethod]] \*normalizeWebTopicName `($theWeb,$theTopic) -> ($theWeb,$theTopic)`
 168
 169 Normalize a Web.TopicName
 170
 171     Input:                      Return:
 172       ( 'Web',  'Topic' )         ( 'Web',  'Topic' )
 173       ( '',     'Topic' )         ( 'Main', 'Topic' )
 174       ( '',     '' )              ( 'Main', 'WebHome' )
 175       ( '',     'Web/Topic' )     ( 'Web',  'Topic' )
 176       ( '',     'Web.Topic' )     ( 'Web',  'Topic' )
 177       ( 'Web1', 'Web2.Topic' )    ( 'Web2', 'Topic' )
 178       ( 'Main', 'Web2.Topic' ) ( 'Main', 'Topic' )
 179       ( 'TWiki', 'Web2.Topic' ) ( 'TWiki', 'Topic' )
 180
 181 Note: Function renamed from getWebTopic
 182
 183 SMELL: WARNING: this function defaults the web and topic names. Be very careful where you use it!
 184
 185 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($remoteUser,$"></a> [[ClassMethod]] **new** `($remoteUser,$query)`
 186
 187 Constructs a new TWiki object. Parameters are taken from the query object.
 188
 189 - `$remoteUser` the logged-in user (login name)
 190 - `$query` the query
 191
 192 ## <a name="ObjectMethod &lt;strong&gt;finish*"></a><a name="ObjectMethod *finish&lt;/strong&gt; "></a> [[ObjectMethod]] **finish** ``
 193
 194 Complete processing after the client's HTTP request has been responded to. Right now this only entails one activity: calling TWiki::Client to flushing the user's session (if any) to disk.
 195
 196 ## <a name="ObjectMethod &lt;strong&gt;writeLog&lt;/strong&gt; ($action"></a> [[ObjectMethod]] **writeLog** `($action,$webTopic,$extra,$user)`
 197
 198 - `$action` - what happened, e.g. view, save, rename
 199 - `$wbTopic` - what it happened to
 200 - `$extra` - extra info, such as minor flag
 201 - `$user` - user who did the saving (user object or string user name)
 202
 203 Write the log for an event to the logfile
 204
 205 ## <a name="ObjectMethod &lt;strong&gt;writeWarning&lt;/strong&gt; ($te"></a> [[ObjectMethod]] **writeWarning** `($text)`
 206
 207 Prints date, time, and contents $text to $TWiki::cfg\{WarningFileName\}, typically 'warnings.txt'. Use for warnings and errors that may require admin intervention. Use this for defensive programming warnings (e.g. assertions).
 208
 209 ## <a name="ObjectMethod &lt;strong&gt;writeDebug&lt;/strong&gt; ($text"></a> [[ObjectMethod]] **writeDebug** `($text)`
 210
 211 Prints date, time, and contents of $text to $TWiki::cfg\{DebugFileName\}, typically 'debug.txt'. Use for debugging messages.
 212
 213 ## <a name="StaticMethod &lt;strong&gt;apply_PatternToInc"></a> [[StaticMethod]] \*applyPatternToIncludedText `($text,$pattern) -> $text`
 214
 215 Apply a pattern on included text to extract a subset
 216
 217 ## <a name="ObjectMethod &lt;strong&gt;inlineAlert&lt;/strong&gt; ($tem"></a> [[ObjectMethod]] **inlineAlert** `($template,$def,...) -> $string`
 218
 219 Format an error for inline inclusion in rendered output. The message string is obtained from the template 'oops'.$template, and the DEF $def is selected. The parameters (...) are used to populate %PARAM1%..%PARAMn%
 220
 221 ## <a name="ObjectMethod &lt;strong&gt;expand_VariablesOn"></a> [[ObjectMethod]] \*expandVariablesOnTopicCreation `($text,$user) -> $text`
 222
 223 - `$text` - text to expand
 224 - `$user` - reference to user object. This is the user expanded in e.g. %USERNAME. Optional, defaults to logged-in user.
 225
 226 Expand limited set of variables during topic creation. These are variables expected in templates that must be statically expanded in new content.
 227
 228 # SMELL: no plugin handler
 229
 230 ## <a name="StaticMethod &lt;strong&gt;entityEncode&lt;/strong&gt; ($te"></a> [[StaticMethod]] **entityEncode** `($text,$extras) -> $encodedText`
 231
 232 Escape special characters to HTML numeric entities. This is **not** a generic encoding, it is tuned specifically for use in TWiki.
 233
 234 HTML4.0 spec: "Certain characters in HTML are reserved for use as markup and must be escaped to appear literally. The "&lt;" character may be represented with an _entity_, **&amp;lt;**. Similarly, "&gt;" is escaped as **&amp;gt;**, and "&amp;" is escaped as **&amp;amp;**. If an attribute value contains a double quotation mark and is delimited by double quotation marks, then the quote should be escaped as **&amp;quot;**.
 235
 236 Other entities exist for special characters that cannot easily be entered with some keyboards..."
 237
 238 This method encodes HTML special and any non-printable ascii characters (except for \\n and \\r) using numeric entities.
 239
 240 FURTHER this method also encodes characters that are special in TWiki meta-language.
 241
 242 $extras is an optional param that may be used to include **additional** characters in the set of encoded characters. It should be a string containing the additional chars.
 243
 244 ## <a name="StaticMethod &lt;strong&gt;entityDecode&lt;/strong&gt; ($en"></a> [[StaticMethod]] **entityDecode** `($encodedText) -> $text`
 245
 246 Decodes all numeric entities (e.g. &amp;#123;). _Does not_ decode named entities such as &amp;amp; (use HTML::Entities for that)
 247
 248 ## <a name="StaticMethod &lt;strong&gt;urlEncode&lt;/strong&gt; ($strin"></a> [[StaticMethod]] **urlEncode** `($string) -> encodedstring`
 249
 250 Encode by converting characters that are illegal in URLs to their %NN equivalents. This method is used for encoding strings that must be embedded _verbatim_ in URLs; it cannot be applied to URLs themselves, as it escapes reserved characters such as = and ?.
 251
 252 RFC 1738, Dec. '94:
 253
 254     >
 255     ...Only alphanumerics [0-9a-zA-Z], the special
 256     characters $-_.+!*'(), and reserved characters used for their
 257     reserved purposes may be used unencoded within a URL.
 258
 259 Reserved characters are $&amp;+,/:;=?@ - these are _also_ encoded by this method.
 260
 261 SMELL: For non-ISO-8859-1 $TWiki::cfg\{Site\}\{CharSet\}, need to convert to UTF-8 before URL encoding. This encoding only supports 8-bit character codes.
 262
 263 ## <a name="StaticMethod &lt;strong&gt;urlDecode&lt;/strong&gt; ($strin"></a> [[StaticMethod]] **urlDecode** `($string) -> decodedstring`
 264
 265 Reverses the encoding done in urlEncode.
 266
 267 ## <a name="StaticMethod &lt;strong&gt;isTrue&lt;/strong&gt; ($value,$d"></a> [[StaticMethod]] **isTrue** `($value,$default) -> $boolean`
 268
 269 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.
 270
 271 If the value is undef, then `$default` is returned. If `$default` is not specified it is taken as 0.
 272
 273 ## <a name="StaticMethod &lt;strong&gt;space_OutWikiWord*"></a> [[StaticMethod]] \*spaceOutWikiWord `($word,$sep) -> $string`
 274
 275 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.
 276
 277 ## <a name="ObjectMethod &lt;strong&gt;enterContext&lt;/strong&gt; ($id"></a> [[ObjectMethod]] **enterContext** `($id,$val)`
 278
 279 Add the context id $id into the set of active contexts. The $val can be anything you like, but should always evaluate to boolean TRUE.
 280
 281 An example of the use of contexts is in the use of tag expansion. The commonTagsHandler in plugins is called every time tags need to be expanded, and the context of that expansion is signalled by the expanding module using a context id. So the forms module adds the context id "form" before invoking common tags expansion.
 282
 283 Contexts are not just useful for tag expansion; they are also relevant when rendering.
 284
 285 Contexts are intended for use mainly by plugins. Core modules can use $session-&gt;inContext( $id ) to determine if a context is active.
 286
 287 ## <a name="ObjectMethod &lt;strong&gt;leaveContext&lt;/strong&gt; ($id"></a> [[ObjectMethod]] **leaveContext** `($id)`
 288
 289 Remove the context id $id from the set of active contexts. (see `enterContext` for more information on contexts)
 290
 291 ## <a name="ObjectMethod &lt;strong&gt;inContext&lt;/strong&gt; ($id)"></a> [[ObjectMethod]] **inContext** `($id)`
 292
 293 Return the value for the given context id (see `enterContext` for more information on contexts)
 294
 295 ## <a name="StaticMethod &lt;strong&gt;register_TagHandle"></a> [[StaticMethod]] \*registerTagHandler `($tag,$fnref)`
 296
 297 STATIC Add a tag handler to the function tag handlers.
 298
 299 - `$tag` name of the tag e.g. MYTAG
 300 - `$fnref` Function to execute. Will be passed ($session, \\%params, $web, $topic )
 301
 302 ### <a name="registerRESTHandler( $subject, $"></a> registerRESTHandler( $subject, $verb, \\&amp;fn )
 303
 304 Adds a function to the dispatch table of the REST interface for a given subject. See [[TWikiScripts#rest]] for more info.
 305
 306 - `$subject` - The subject under which the function will be registered.
 307 - `$verb` - The verb under which the function will be registered.
 308 - `\&fn` - Reference to the function.
 309
 310 The handler function must be of the form:
 311
 312     sub handler(\%session,$subject,$verb) -> $text
 313
 314 where:
 315
 316 - `\%session` - a reference to the TWiki session object (may be ignored)
 317 - `$subject` - The invoked subject (may be ignored)
 318 - `$verb` - The invoked verb (may be ignored)
 319
 320 **Since:** TWiki::Plugins::VERSION 1.1
 321
 322 ### <a name="restDispatch( $subject, $verb) ="></a> restDispatch( $subject, $verb) =&gt; \\&amp;fn
 323
 324 Returns the handler function associated to the given $subject and $werb, or undef if none is found.
 325
 326 **Since:** TWiki::Plugins::VERSION 1.1
 327
 328 ## <a name="ObjectMethod &lt;strong&gt;handle_CommonTags*"></a> [[ObjectMethod]] \*handleCommonTags `($text,$web,$topic) -> $text`
 329
 330 Processes %VARIABLE%, and %TOC% syntax; also includes 'commonTagsHandler' plugin hook.
 331
 332 Returns the text of the topic, after file inclusion, variable substitution, table-of-contents generation, and any plugin changes from commonTagsHandler.
 333
 334 ## <a name="ObjectMethod &lt;strong&gt;add_ToHEAD&lt;/strong&gt; ($id,$"></a> [[ObjectMethod]] **addToHEAD** `($id,$html)`
 335
 336 Add `$html` to the HEAD tag of the page currently being generated.
 337
 338 Note that TWiki variables may be used in the HEAD. They will be expanded according to normal variable expansion rules.
 339
 340 The 'id' is used to ensure that multiple adds of the same block of HTML don't result in it being added many times.
 341
 342 ## <a name="StaticMethod &lt;strong&gt;initialize&lt;/strong&gt; ($path"></a> [[StaticMethod]] **initialize** `($pathInfo,$remoteUser,$topic,$url,$query) -> ($topicName,$webName,$scriptUrlPath,$userName,$dataDir)`
 343
 344 Return value: ( $topicName, $webName, $TWiki::cfg\{ScriptUrlPath\}, $userName, $TWiki::cfg\{DataDir\} )
 345
 346 Static method to construct a new singleton session instance. It creates a new TWiki and sets the Plugins $SESSION variable to point to it, so that TWiki::Func methods will work.
 347
 348 This method is **DEPRECATED** but is maintained for script compatibility.
 349
 350 Note that $theUrl, if specified, must be identical to $query-&gt;url()
 351
 352 ## <a name="StaticMethod &lt;strong&gt;readFile&lt;/strong&gt; ($filena"></a> [[StaticMethod]] **readFile** `($filename) -> $text`
 353
 354 Returns the entire contents of the given file, which can be specified in any format acceptable to the Perl open() function. Fast, but inherently unsafe.
 355
 356 WARNING: Never, ever use this for accessing topics or attachments! Use the Store API for that. This is for global control files only, and should be used **only** if there is **absolutely no alternative**.