data/TWiki/TWikiDotPm.txt,v
changeset 0 414e01d06fd5
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     1 head	1.4;
       
     2 access;
       
     3 symbols;
       
     4 locks; strict;
       
     5 comment	@# @;
       
     6 
       
     7 
       
     8 1.4
       
     9 date	2008.01.22.03.21.36;	author TWikiContributor;	state Exp;
       
    10 branches;
       
    11 next	1.3;
       
    12 
       
    13 1.3
       
    14 date	2007.01.16.04.12.01;	author TWikiContributor;	state Exp;
       
    15 branches;
       
    16 next	1.2;
       
    17 
       
    18 1.2
       
    19 date	2006.06.25.16.26.33;	author TWikiContributor;	state Exp;
       
    20 branches;
       
    21 next	1.1;
       
    22 
       
    23 1.1
       
    24 date	2006.02.01.12.01.24;	author TWikiContributor;	state Exp;
       
    25 branches;
       
    26 next	;
       
    27 
       
    28 
       
    29 desc
       
    30 @new-topic
       
    31 @
       
    32 
       
    33 
       
    34 1.4
       
    35 log
       
    36 @buildrelease
       
    37 @
       
    38 text
       
    39 @---+ Package =TWiki=
       
    40 
       
    41 TWiki operates by creating a singleton object (known as the Session
       
    42 object) that acts as a point of reference for all the different
       
    43 modules in the system. This package is the class for this singleton,
       
    44 and also contains the vast bulk of the basic constants and the per-
       
    45 site configuration mechanisms.
       
    46 
       
    47 Global variables are avoided wherever possible to avoid problems
       
    48 with CGI accelerators such as mod_perl.
       
    49 
       
    50 ---++ Public Data members
       
    51    * =cgiQuery=         Pointer to the CGI::
       
    52    * =context=          Hash of context ids
       
    53    * moved: =loginManager=     TWiki::LoginManager singleton (moved to TWiki::Users)
       
    54    * =plugins=          TWiki::Plugins singleton
       
    55    * =prefs=            TWiki::Prefs singleton
       
    56    * =remoteUser=       Login ID when using ApacheLogin. Maintained for
       
    57                         compatibility only, do not use.
       
    58    * =requestedWebName= Name of web found in URL path or =web= URL parameter
       
    59    * =sandbox=          TWiki::Sandbox singleton
       
    60    * =scriptUrlPath=    URL path to the current script. May be dynamically
       
    61                         extracted from the URL path if {GetScriptUrlFromCgi}.
       
    62                         Only required to support {GetScriptUrlFromCgi} and
       
    63                         not consistently used. Avoid.
       
    64    * =security=         TWiki::Access singleton
       
    65    * =SESSION_TAGS=     Hash of TWiki variables whose value is specific to
       
    66                         the current CGI request.
       
    67    * =store=            TWiki::Store singleton
       
    68    * =topicName=        Name of topic found in URL path or =topic= URL
       
    69                         parameter
       
    70    * =urlHost=          Host part of the URL (including the protocol)
       
    71                         determined during intialisation and defaulting to
       
    72                         {DefaultUrlHost}
       
    73    * =user=             Unique user ID of logged-in user
       
    74    * =users=            TWiki::Users singleton
       
    75    * =webName=          Name of web found in URL path, or =web= URL parameter,
       
    76                         or {UsersWebName}
       
    77 
       
    78 
       
    79 %TOC%
       
    80 
       
    81 ---++ StaticMethod *getTWikiLibDir* <tt>() -> $path</tt>
       
    82 
       
    83 Returns the full path of the directory containing TWiki.pm
       
    84 
       
    85 
       
    86 
       
    87 ---++ StaticMethod *UTF82SiteCharSet* <tt>($utf8) -> $ascii</tt>
       
    88 
       
    89 Auto-detect UTF-8 vs. site charset in string, and convert UTF-8 into site
       
    90 charset.
       
    91 
       
    92 
       
    93 
       
    94 ---++ ObjectMethod *writeCompletePage* <tt>($text,$pageType,$contentType)</tt>
       
    95 
       
    96 Write a complete HTML page with basic header to the browser.
       
    97    * =$text= is the text of the page body (&lt;html&gt; to &lt;/html&gt; if it's HTML)
       
    98    * =$pageType= - May be "edit", which will cause headers to be generated that force
       
    99      caching for 24 hours, to prevent Codev.BackFromPreviewLosesText bug, which caused
       
   100      data loss with IE5 and IE6.
       
   101    * =$contentType= - page content type | text/html
       
   102 
       
   103 This method removes noautolink and nop tags before outputting the page unless
       
   104 $contentType is text/plain.
       
   105 
       
   106 
       
   107 
       
   108 ---++ ObjectMethod *generateHTTPHeaders* <tt>($query,$pageType,$contentType,$contentLength) -> $header</tt>
       
   109 
       
   110 All parameters are optional.
       
   111 
       
   112    * =$query= CGI query object | Session CGI query (there is no good reason to set this)
       
   113    * =$pageType= - May be "edit", which will cause headers to be generated that force caching for 24 hours, to prevent Codev.BackFromPreviewLosesText bug, which caused data loss with IE5 and IE6.
       
   114    * =$contentType= - page content type | text/html
       
   115    * =$contentLength= - content-length | no content-length will be set if this is undefined, as required by HTTP1.1
       
   116 
       
   117 Implements the post-Dec2001 release plugin API, which requires the
       
   118 writeHeaderHandler in plugin to return a string of HTTP headers, CR/LF
       
   119 delimited. Filters any illegal headers. Plugin headers will override
       
   120 core settings.
       
   121 
       
   122 Does *not* add a =Content-length= header.
       
   123 
       
   124 
       
   125 
       
   126 ---++ StaticMethod *isRedirectSafe* <tt>($redirect)=>$ok</tt>
       
   127 
       
   128 tests if the $redirect is an external URL, returning false if AllowRedirectUrl is denied
       
   129 
       
   130 
       
   131 
       
   132 ---++ ObjectMethod *redirect* <tt>($url,$passthrough,$action_redirectto)</tt>
       
   133 
       
   134    * $url - url or twikitopic to redirect to
       
   135    * $passthrough - (optional) parameter to **FILLMEIN**
       
   136    * $action_redirectto - (optional) redirect to where ?redirectto=
       
   137      points to (if it's valid)
       
   138 
       
   139 Redirects the request to =$url=, *unless*
       
   140    1 It is overridden by a plugin declaring a =redirectCgiQueryHandler=.
       
   141    1 =$session->{cgiQuery}= is =undef= or
       
   142    1 $query->param('noredirect') is set to a true value.
       
   143 Thus a redirect is only generated when in a CGI context.
       
   144 
       
   145 Normally this method will ignore parameters to the current query. Sometimes,
       
   146 for example when redirecting to a login page during authentication (and then
       
   147 again from the login page to the original requested URL), you want to make
       
   148 sure all parameters are passed on, and for this $passthrough should be set to
       
   149 true. In this case it will pass all parameters that were passed to the
       
   150 current query on to the redirect target. If the request_method for the
       
   151 current query was GET, then all parameters will be passed by encoding them
       
   152 in the URL (after ?). If the request_method was POST, then there is a risk the
       
   153 URL would be too big for the receiver, so it caches the form data and passes
       
   154 over a cache reference in the redirect GET.
       
   155 
       
   156 NOTE: Passthrough is only meaningful if the redirect target is on the same
       
   157 server.
       
   158 
       
   159 
       
   160 
       
   161 ---++ ObjectMethod *cacheQuery* <tt>() -> $queryString</tt>
       
   162 
       
   163 Caches the current query in the params cache, and returns a rewritten
       
   164 query string for the cache to be picked up again on the other side of a
       
   165 redirect.
       
   166 
       
   167 We can't encode post params into a redirect, because they may exceed the
       
   168 size of the GET request. So we cache the params, and reload them when the
       
   169 redirect target is reached.
       
   170 
       
   171 
       
   172 
       
   173 ---++ StaticMethod *isValidWikiWord* <tt>($name) -> $boolean</tt>
       
   174 
       
   175 Check for a valid WikiWord or WikiName
       
   176 
       
   177 
       
   178 
       
   179 ---++ StaticMethod *isValidTopicName* <tt>($name) -> $boolean</tt>
       
   180 
       
   181 Check for a valid topic name
       
   182 
       
   183 
       
   184 
       
   185 ---++ StaticMethod *isValidAbbrev* <tt>($name) -> $boolean</tt>
       
   186 
       
   187 Check for a valid ABBREV (acronym)
       
   188 
       
   189 
       
   190 
       
   191 ---++ StaticMethod *isValidWebName* <tt>($name,$system) -> $boolean</tt>
       
   192 
       
   193 STATIC Check for a valid web name. If $system is true, then
       
   194 system web names are considered valid (names starting with _)
       
   195 otherwise only user web names are valid
       
   196 
       
   197 If $TWiki::cfg{EnableHierarchicalWebs} is off, it will also return false
       
   198 when a nested web name is passed to it.
       
   199 
       
   200 
       
   201 
       
   202 ---++ ObjectMethod *readOnlyMirrorWeb* <tt>($theWeb) -> ($mirrorSiteName,$mirrorViewURL,$mirrorLink,$mirrorNote)</tt>
       
   203 
       
   204 If this is a mirrored web, return information about the mirror. The info
       
   205 is returned in a quadruple:
       
   206 
       
   207 | site name | URL | link | note |
       
   208 
       
   209 
       
   210 
       
   211 ---++ ObjectMethod *getSkin* <tt>() -> $string</tt>
       
   212 
       
   213 Get the currently requested skin path
       
   214 
       
   215 
       
   216 
       
   217 ---++ ObjectMethod *getScriptUrl* <tt>($absolute,$script,$web,$topic,...) -> $scriptURL</tt>
       
   218 
       
   219 Returns the URL to a TWiki script, providing the web and topic as
       
   220 "path info" parameters.  The result looks something like this:
       
   221 "http://host/twiki/bin/$script/$web/$topic".
       
   222    * =...= - 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. <tt>getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2)</tt> will give <tt>.../view/x/y?a=1&b=2#XXX</tt>
       
   223 
       
   224 If $absolute is set, generates an absolute URL. $absolute is advisory only;
       
   225 TWiki can decide to generate absolute URLs (for example when run from the
       
   226 command-line) even when relative URLs have been requested.
       
   227 
       
   228 The default script url is taken from {ScriptUrlPath}, unless there is
       
   229 an exception defined for the given script in {ScriptUrlPaths}. Both
       
   230 {ScriptUrlPath} and {ScriptUrlPaths} may be absolute or relative URIs. If
       
   231 they are absolute, then they will always generate absolute URLs. if they
       
   232 are relative, then they will be converted to absolute when required (e.g.
       
   233 when running from the command line, or when generating rss). If
       
   234 $script is not given, absolute URLs will always be generated.
       
   235 
       
   236 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.
       
   237 
       
   238 
       
   239 
       
   240 ---++ ObjectMethod *getPubUrl* <tt>($absolute,$web,$topic,$attachment) -> $url</tt>
       
   241 
       
   242 Composes a pub url. If $absolute is set, returns an absolute URL.
       
   243 If $absolute is set, generates an absolute URL. $absolute is advisory only;
       
   244 TWiki can decide to generate absolute URLs (for example when run from the
       
   245 command-line) even when relative URLs have been requested.
       
   246 
       
   247 $web, $topic and $attachment are optional. A partial URL path will be
       
   248 generated if one or all is not given.
       
   249 
       
   250 
       
   251 
       
   252 ---++ ObjectMethod *getIconUrl* <tt>($absolute,$iconName) -> $iconURL</tt>
       
   253 
       
   254 Map an icon name to a URL path.
       
   255 
       
   256 
       
   257 
       
   258 ---++ ObjectMethod *mapToIconFileName* <tt>($fileName,$default) -> $fileName</tt>
       
   259 
       
   260 Maps from a filename (or just the extension) to the name of the
       
   261 file that contains the image for that file type.
       
   262 
       
   263 
       
   264 
       
   265 ---++ ObjectMethod *normalizeWebTopicName* <tt>($theWeb,$theTopic) -> ($theWeb,$theTopic)</tt>
       
   266 
       
   267 Normalize a Web<nop>.<nop>TopicName
       
   268 
       
   269 See TWikiFuncDotPm for a full specification of the expansion (not duplicated
       
   270 here)
       
   271 
       
   272 *WARNING* if there is no web specification (in the web or topic parameters)
       
   273 the web defaults to $TWiki::cfg{UsersWebName}. If there is no topic
       
   274 specification, or the topic is '0', the topic defaults to the web home topic
       
   275 name.
       
   276 
       
   277 
       
   278 
       
   279 ---++ ClassMethod *new* <tt>($loginName,$query,\%initialContext)</tt>
       
   280 
       
   281 Constructs a new TWiki object. Parameters are taken from the query object.
       
   282 
       
   283    * =$loginName= is the login username (*not* the wikiname) of the user you
       
   284      want to be logged-in if none is available from a session or browser.
       
   285      Used mainly for side scripts and debugging.
       
   286    * =$query= the CGI query (may be undef, in which case an empty query
       
   287      is used)
       
   288    * =\%initialContext= - reference to a hash containing context
       
   289      name=value pairs to be pre-installed in the context hash
       
   290 
       
   291 
       
   292 
       
   293 ---++ ObjectMethod *renderer* <tt>()</tt>
       
   294 Get a reference to the renderer object. Done lazily because not everyone
       
   295 needs the renderer.
       
   296 
       
   297 
       
   298 
       
   299 ---++ ObjectMethod *attach* <tt>()</tt>
       
   300 Get a reference to the attach object. Done lazily because not everyone
       
   301 needs the attach.
       
   302 
       
   303 
       
   304 
       
   305 ---++ ObjectMethod *templates* <tt>()</tt>
       
   306 Get a reference to the templates object. Done lazily because not everyone
       
   307 needs the templates.
       
   308 
       
   309 
       
   310 
       
   311 ---++ ObjectMethod *i18n* <tt>()</tt>
       
   312 Get a reference to the i18n object. Done lazily because not everyone
       
   313 needs the i18ner.
       
   314 
       
   315 
       
   316 
       
   317 ---++ ObjectMethod *search* <tt>()</tt>
       
   318 Get a reference to the search object. Done lazily because not everyone
       
   319 needs the searcher.
       
   320 
       
   321 
       
   322 
       
   323 ---++ ObjectMethod *security* <tt>()</tt>
       
   324 Get a reference to the security object. Done lazily because not everyone
       
   325 needs the security.
       
   326 
       
   327 
       
   328 
       
   329 ---++ ObjectMethod *net* <tt>()</tt>
       
   330 Get a reference to the net object. Done lazily because not everyone
       
   331 needs the net.
       
   332 
       
   333 
       
   334 
       
   335 ---++ ObjectMethod *finish* <tt>()</tt>
       
   336 Break circular references.
       
   337 
       
   338 
       
   339 
       
   340 ---++ ObjectMethod *writeLog* <tt>($action,$webTopic,$extra,$user)</tt>
       
   341 
       
   342    * =$action= - what happened, e.g. view, save, rename
       
   343    * =$wbTopic= - what it happened to
       
   344    * =$extra= - extra info, such as minor flag
       
   345    * =$user= - user who did the saving (user id)
       
   346 Write the log for an event to the logfile
       
   347 
       
   348 
       
   349 
       
   350 ---++ ObjectMethod *writeWarning* <tt>($text)</tt>
       
   351 
       
   352 Prints date, time, and contents $text to $TWiki::cfg{WarningFileName}, typically
       
   353 'warnings.txt'. Use for warnings and errors that may require admin
       
   354 intervention. Use this for defensive programming warnings (e.g. assertions).
       
   355 
       
   356 
       
   357 
       
   358 ---++ ObjectMethod *writeDebug* <tt>($text)</tt>
       
   359 
       
   360 Prints date, time, and contents of $text to $TWiki::cfg{DebugFileName}, typically
       
   361 'debug.txt'.  Use for debugging messages.
       
   362 
       
   363 
       
   364 
       
   365 ---++ StaticMethod *applyPatternToIncludedText* <tt>($text,$pattern) -> $text</tt>
       
   366 
       
   367 Apply a pattern on included text to extract a subset
       
   368 
       
   369 
       
   370 
       
   371 ---++ ObjectMethod *inlineAlert* <tt>($template,$def,...) -> $string</tt>
       
   372 
       
   373 Format an error for inline inclusion in rendered output. The message string
       
   374 is obtained from the template 'oops'.$template, and the DEF $def is
       
   375 selected. The parameters (...) are used to populate %PARAM1%..%PARAMn%
       
   376 
       
   377 
       
   378 
       
   379 ---++ StaticMethod *parseSections* <tt>($text) -> ($string,$sectionlistref)</tt>
       
   380 
       
   381 Generic parser for sections within a topic. Sections are delimited
       
   382 by STARTSECTION and ENDSECTION, which may be nested, overlapped or
       
   383 otherwise abused. The parser builds an array of sections, which is
       
   384 ordered by the order of the STARTSECTION within the topic. It also
       
   385 removes all the SECTION tags from the text, and returns the text
       
   386 and the array of sections.
       
   387 
       
   388 Each section is a =TWiki::Attrs= object, which contains the attributes
       
   389 {type, name, start, end}
       
   390 where start and end are character offsets in the
       
   391 string *after all section tags have been removed*. All sections
       
   392 are required to be uniquely named; if a section is unnamed, it
       
   393 will be given a generated name. Sections may overlap or nest.
       
   394 
       
   395 See test/unit/Fn_SECTION.pm for detailed testcases that
       
   396 round out the spec.
       
   397 
       
   398 
       
   399 
       
   400 ---++ ObjectMethod *expandVariablesOnTopicCreation* <tt>($text,$user,$web,$topic) -> $text</tt>
       
   401 
       
   402    * =$text= - text to expand
       
   403    * =$user= - This is the user expanded in e.g. %USERNAME. Optional, defaults to logged-in user.
       
   404 Expand limited set of variables during topic creation. These are variables
       
   405 expected in templates that must be statically expanded in new content.
       
   406    * =$web= - name of web
       
   407    * =$topic= - name of topic
       
   408 
       
   409 # SMELL: no plugin handler
       
   410 
       
   411 
       
   412 
       
   413 ---++ StaticMethod *entityEncode* <tt>($text,$extras) -> $encodedText</tt>
       
   414 
       
   415 Escape special characters to HTML numeric entities. This is *not* a generic
       
   416 encoding, it is tuned specifically for use in TWiki.
       
   417 
       
   418 HTML4.0 spec:
       
   419 "Certain characters in HTML are reserved for use as markup and must be
       
   420 escaped to appear literally. The "&lt;" character may be represented with
       
   421 an <em>entity</em>, <strong class=html>&amp;lt;</strong>. Similarly, "&gt;"
       
   422 is escaped as <strong class=html>&amp;gt;</strong>, and "&amp;" is escaped
       
   423 as <strong class=html>&amp;amp;</strong>. If an attribute value contains a
       
   424 double quotation mark and is delimited by double quotation marks, then the
       
   425 quote should be escaped as <strong class=html>&amp;quot;</strong>.</p>
       
   426 
       
   427 Other entities exist for special characters that cannot easily be entered
       
   428 with some keyboards..."
       
   429 
       
   430 This method encodes HTML special and any non-printable ascii
       
   431 characters (except for \n and \r) using numeric entities.
       
   432 
       
   433 FURTHER this method also encodes characters that are special in TWiki
       
   434 meta-language.
       
   435 
       
   436 $extras is an optional param that may be used to include *additional*
       
   437 characters in the set of encoded characters. It should be a string
       
   438 containing the additional chars.
       
   439 
       
   440 
       
   441 
       
   442 ---++ StaticMethod *entityDecode* <tt>($encodedText) -> $text</tt>
       
   443 
       
   444 Decodes all numeric entities (e.g. &amp;#123;). _Does not_ decode
       
   445 named entities such as &amp;amp; (use HTML::Entities for that)
       
   446 
       
   447 
       
   448 
       
   449 ---++ StaticMethod *urlEncodeAttachment* <tt>($text)</tt>
       
   450 
       
   451 For attachments, URL-encode specially to 'freeze' any characters >127 in the
       
   452 site charset (e.g. ISO-8859-1 or KOI8-R), by doing URL encoding into native
       
   453 charset ($siteCharset) - used when generating attachment URLs, to enable the
       
   454 web server to serve attachments, including images, directly.  
       
   455 
       
   456 This encoding is required to handle the cases of:
       
   457 
       
   458     - browsers that generate UTF-8 URLs automatically from site charset URLs - now quite common
       
   459     - web servers that directly serve attachments, using the site charset for
       
   460       filenames, and cannot convert UTF-8 URLs into site charset filenames
       
   461 
       
   462 The aim is to prevent the browser from converting a site charset URL in the web
       
   463 page to a UTF-8 URL, which is the default.  Hence we 'freeze' the URL into the
       
   464 site character set through URL encoding. 
       
   465 
       
   466 In two cases, no URL encoding is needed:  For EBCDIC mainframes, we assume that 
       
   467 site charset URLs will be translated (outbound and inbound) by the web server to/from an
       
   468 EBCDIC character set. For sites running in UTF-8, there's no need for TWiki to
       
   469 do anything since all URLs and attachment filenames are already in UTF-8.
       
   470 
       
   471 
       
   472 
       
   473 ---++ StaticMethod *urlEncode* <tt>($string) -> encodedstring</tt>
       
   474 
       
   475 Encode by converting characters that are illegal in URLs to
       
   476 their %NN equivalents. This method is used for encoding
       
   477 strings that must be embedded _verbatim_ in URLs; it cannot
       
   478 be applied to URLs themselves, as it escapes reserved
       
   479 characters such as = and ?.
       
   480 
       
   481 RFC 1738, Dec. '94:
       
   482     <verbatim>
       
   483     ...Only alphanumerics [0-9a-zA-Z], the special
       
   484     characters $-_.+!*'(), and reserved characters used for their
       
   485     reserved purposes may be used unencoded within a URL.
       
   486     </verbatim>
       
   487 
       
   488 Reserved characters are $&+,/:;=?@@ - these are _also_ encoded by
       
   489 this method.
       
   490 
       
   491 This URL-encoding handles all character encodings including ISO-8859-*,
       
   492 KOI8-R, EUC-* and UTF-8. 
       
   493 
       
   494 This may not handle EBCDIC properly, as it generates an EBCDIC URL-encoded
       
   495 URL, but mainframe web servers seem to translate this outbound before it hits browser
       
   496 - see CGI::Util::escape for another approach.
       
   497 
       
   498 
       
   499 
       
   500 ---++ StaticMethod *urlDecode* <tt>($string) -> decodedstring</tt>
       
   501 
       
   502 Reverses the encoding done in urlEncode.
       
   503 
       
   504 
       
   505 
       
   506 ---++ StaticMethod *isTrue* <tt>($value,$default) -> $boolean</tt>
       
   507 
       
   508 Returns 1 if =$value= is true, and 0 otherwise. "true" means set to
       
   509 something with a Perl true value, with the special cases that "off",
       
   510 "false" and "no" (case insensitive) are forced to false. Leading and
       
   511 trailing spaces in =$value= are ignored.
       
   512 
       
   513 If the value is undef, then =$default= is returned. If =$default= is
       
   514 not specified it is taken as 0.
       
   515 
       
   516 
       
   517 
       
   518 ---++ StaticMethod *spaceOutWikiWord* <tt>($word,$sep) -> $string</tt>
       
   519 
       
   520 Spaces out a wiki word by inserting a string (default: one space) between each word component.
       
   521 With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.
       
   522 
       
   523 
       
   524 
       
   525 ---++ ObjectMethod *expandAllTags* <tt>(\$text,$topic,$web,$meta)</tt>
       
   526 Expands variables by replacing the variables with their
       
   527 values. Some example variables: %<nop>TOPIC%, %<nop>SCRIPTURL%,
       
   528 %<nop>WIKINAME%, etc.
       
   529 $web and $incs are passed in for recursive include expansion. They can
       
   530 safely be undef.
       
   531 The rules for tag expansion are:
       
   532    1 Tags are expanded left to right, in the order they are encountered.
       
   533    1 Tags are recursively expanded as soon as they are encountered -
       
   534      the algorithm is inherently single-pass
       
   535    1 A tag is not "encountered" until the matching }% has been seen, by
       
   536      which time all tags in parameters will have been expanded
       
   537    1 Tag expansions that create new tags recursively are limited to a
       
   538      set number of hierarchical levels of expansion
       
   539 
       
   540 
       
   541 
       
   542 ---++ ObjectMethod *enterContext* <tt>($id,$val)</tt>
       
   543 
       
   544 Add the context id $id into the set of active contexts. The $val
       
   545 can be anything you like, but should always evaluate to boolean
       
   546 TRUE.
       
   547 
       
   548 An example of the use of contexts is in the use of tag
       
   549 expansion. The commonTagsHandler in plugins is called every
       
   550 time tags need to be expanded, and the context of that expansion
       
   551 is signalled by the expanding module using a context id. So the
       
   552 forms module adds the context id "form" before invoking common
       
   553 tags expansion.
       
   554 
       
   555 Contexts are not just useful for tag expansion; they are also
       
   556 relevant when rendering.
       
   557 
       
   558 Contexts are intended for use mainly by plugins. Core modules can
       
   559 use $session->inContext( $id ) to determine if a context is active.
       
   560 
       
   561 
       
   562 
       
   563 ---++ ObjectMethod *leaveContext* <tt>($id)</tt>
       
   564 
       
   565 Remove the context id $id from the set of active contexts.
       
   566 (see =enterContext= for more information on contexts)
       
   567 
       
   568 
       
   569 
       
   570 ---++ ObjectMethod *inContext* <tt>($id)</tt>
       
   571 
       
   572 Return the value for the given context id
       
   573 (see =enterContext= for more information on contexts)
       
   574 
       
   575 
       
   576 
       
   577 ---++ StaticMethod *registerTagHandler* <tt>($tag,$fnref)</tt>
       
   578 
       
   579 STATIC Add a tag handler to the function tag handlers.
       
   580    * =$tag= name of the tag e.g. MYTAG
       
   581    * =$fnref= Function to execute. Will be passed ($session, \%params, $web, $topic )
       
   582 
       
   583 
       
   584 
       
   585 ---++ StaticMethod *registerRESTHandler* <tt>($subject,$verb,\&fn)</tt>
       
   586 
       
   587 Adds a function to the dispatch table of the REST interface 
       
   588 for a given subject. See TWikiScripts#rest for more info.
       
   589 
       
   590    * =$subject= - The subject under which the function will be registered.
       
   591    * =$verb= - The verb under which the function will be registered.
       
   592    * =\&fn= - Reference to the function.
       
   593 
       
   594 The handler function must be of the form:
       
   595 <verbatim>
       
   596 sub handler(\%session,$subject,$verb) -> $text
       
   597 </verbatim>
       
   598 where:
       
   599    * =\%session= - a reference to the TWiki session object (may be ignored)
       
   600    * =$subject= - The invoked subject (may be ignored)
       
   601    * =$verb= - The invoked verb (may be ignored)
       
   602 
       
   603 *Since:* TWiki::Plugins::VERSION 1.1
       
   604 
       
   605 
       
   606 
       
   607 ---++ StaticMethod *restDispatch* <tt>($subject,$verb)=>\&fn</tt>
       
   608 
       
   609 Returns the handler  function associated to the given $subject and $werb,
       
   610 or undef if none is found.
       
   611 
       
   612 *Since:* TWiki::Plugins::VERSION 1.1
       
   613 
       
   614 
       
   615 
       
   616 ---++ ObjectMethod *handleCommonTags* <tt>($text,$web,$topic,$meta) -> $text</tt>
       
   617 
       
   618 Processes %<nop>VARIABLE%, and %<nop>TOC% syntax; also includes
       
   619 'commonTagsHandler' plugin hook.
       
   620 
       
   621 Returns the text of the topic, after file inclusion, variable substitution,
       
   622 table-of-contents generation, and any plugin changes from commonTagsHandler.
       
   623 
       
   624 $meta may be undef when, for example, expanding templates, or one-off strings
       
   625 at a time when meta isn't available.
       
   626 
       
   627 
       
   628 
       
   629 ---++ ObjectMethod *addToHEAD* <tt>($id,$html)</tt>
       
   630 
       
   631 Add =$html= to the HEAD tag of the page currently being generated.
       
   632 
       
   633 Note that TWiki variables may be used in the HEAD. They will be expanded
       
   634 according to normal variable expansion rules.
       
   635 
       
   636 The 'id' is used to ensure that multiple adds of the same block of HTML don't
       
   637 result in it being added many times.
       
   638 
       
   639 
       
   640 
       
   641 ---++ StaticMethod *initialize* <tt>($pathInfo,$remoteUser,$topic,$url,$query) -> ($topicName,$webName,$scriptUrlPath,$userName,$dataDir)</tt>
       
   642 
       
   643 Return value: ( $topicName, $webName, $TWiki::cfg{ScriptUrlPath}, $userName, $TWiki::cfg{DataDir} )
       
   644 
       
   645 Static method to construct a new singleton session instance.
       
   646 It creates a new TWiki and sets the Plugins $SESSION variable to
       
   647 point to it, so that TWiki::Func methods will work.
       
   648 
       
   649 This method is *DEPRECATED* but is maintained for script compatibility.
       
   650 
       
   651 Note that $theUrl, if specified, must be identical to $query->url()
       
   652 
       
   653 
       
   654 
       
   655 ---++ StaticMethod *readFile* <tt>($filename) -> $text</tt>
       
   656 
       
   657 Returns the entire contents of the given file, which can be specified in any
       
   658 format acceptable to the Perl open() function. Fast, but inherently unsafe.
       
   659 
       
   660 WARNING: Never, ever use this for accessing topics or attachments! Use the
       
   661 Store API for that. This is for global control files only, and should be
       
   662 used *only* if there is *absolutely no alternative*.
       
   663 
       
   664 
       
   665 
       
   666 ---++ StaticMethod *expandStandardEscapes* <tt>($str) -> $unescapedStr</tt>
       
   667 
       
   668 Expands standard escapes used in parameter values to block evaluation. The following escapes
       
   669 are handled:
       
   670 
       
   671 | *Escape:* | *Expands To:* |
       
   672 | =$n= or =$n()= | New line. Use =$n()= if followed by alphanumeric character, e.g. write =Foo$n()Bar= instead of =Foo$nBar= |
       
   673 | =$nop= or =$nop()= | Is a "no operation". |
       
   674 | =$quot= | Double quote (="=) |
       
   675 | =$percnt= | Percent sign (=%=) |
       
   676 | =$dollar= | Dollar sign (=$=) |
       
   677 
       
   678 
       
   679 @
       
   680 
       
   681 
       
   682 1.3
       
   683 log
       
   684 @buildrelease
       
   685 @
       
   686 text
       
   687 @d12 28
       
   688 a44 2
       
   689 STATIC method.
       
   690 
       
   691 d49 1
       
   692 a49 1
       
   693 ---++ ObjectMethod *UTF82SiteCharSet* <tt>($utf8) -> $ascii</tt>
       
   694 d70 1
       
   695 a70 1
       
   696 ---++ ObjectMethod *writePageHeader* <tt>($query,$pageType,$contentType,$contentLength)</tt>
       
   697 d84 5
       
   698 d90 1
       
   699 d92 8
       
   700 a99 1
       
   701 ---++ ObjectMethod *redirect* <tt>($url,$passthrough)</tt>
       
   702 d107 10
       
   703 a116 6
       
   704 Normally this method will ignore parameters to the current query.
       
   705 If $passthrough is set, then it will pass all parameters that were passed
       
   706 to the current query on to the redirect target. If the request_method was
       
   707 GET, then all parameters can be passed in the URL. If the
       
   708 request_method was POST then it caches the form data and passes over a
       
   709 cache reference in the redirect GET.
       
   710 d118 2
       
   711 a119 1
       
   712 Passthrough is only meaningful if the redirect target is on the same server.
       
   713 d159 3
       
   714 d227 32
       
   715 a258 1
       
   716 ---++ ObjectMethod *getOopsUrl* <tt>($template,@@options) -> $absoluteOopsURL</tt>
       
   717 a259 6
       
   718 Composes a URL for an "oops" error page. The @@options consists of a list
       
   719 of key => value pairs. The following keys are used:
       
   720    * =-web= - web name
       
   721    * =-topic= - topic name
       
   722    * =-def= - optional template def within the main template file
       
   723    * =-params= - a single parameter, or a reference to an array of parameters  These are passed in the URL as '&param1=' etc.
       
   724 d261 3
       
   725 a263 1
       
   726 Do _not_ include the "oops" part in front of the template name.
       
   727 a264 1
       
   728 Alternatively you can pass a reference to an OopsException in place of the template. All other parameters will be ignored.
       
   729 a265 2
       
   730 The returned URL ends up looking something like this:
       
   731 "http://host/twiki/bin/oops/$web/$topic?template=$template&param1=$scriptParams[0]..."
       
   732 d267 3
       
   733 a269 2
       
   734 Note: if {keep} is true in the params, then they will also be pushed into the
       
   735 current query.
       
   736 d273 3
       
   737 a275 1
       
   738 ---++ ObjectMethod *normalizeWebTopicName* <tt>($theWeb,$theTopic) -> ($theWeb,$theTopic)</tt>
       
   739 a276 1
       
   740 Normalize a Web<nop>.<nop>TopicName
       
   741 a277 1
       
   742 See TWikiFuncDotPm for a full specification of the expansion (not duplicated here)
       
   743 d279 3
       
   744 a281 3
       
   745 *WARNING* if there is no web specification (in the web or topic parameters) the web
       
   746 defaults to $TWiki::cfg{UsersWebName}. If there is no topic specification, or the topic
       
   747 is '0', the topic defaults to the web home topic name.
       
   748 d285 3
       
   749 a287 1
       
   750 ---++ ClassMethod *new* <tt>($loginName,$query,\%initialContext)</tt>
       
   751 a288 1
       
   752 Constructs a new TWiki object. Parameters are taken from the query object.
       
   753 a289 5
       
   754    * =$loginName= is the username of the user you want to be logged-in if none is
       
   755      available from a session or browser. Used mainly for side scripts and debugging.
       
   756    * =$query= the CGI query (may be undef, in which case an empty query is used)
       
   757    * =\%initialContext= - reference to a hash containing context name=value pairs
       
   758      to be pre-installed in the context hash
       
   759 d291 3
       
   760 a295 1
       
   761 ---++ ObjectMethod *finish* <tt></tt>
       
   762 d297 2
       
   763 a298 5
       
   764 Complete processing after the client's HTTP request has been responded
       
   765 to. Right now this does two things:
       
   766    1 calling TWiki::Client to flushing the user's session (if any) to disk,
       
   767    2 breaking circular references to allow garbage collection in persistent
       
   768      environments
       
   769 d307 1
       
   770 a307 1
       
   771    * =$user= - user who did the saving (user object or string user name)
       
   772 d362 1
       
   773 a362 1
       
   774 ---++ ObjectMethod *expandVariablesOnTopicCreation* <tt>($text,$user) -> $text</tt>
       
   775 d365 1
       
   776 a365 1
       
   777    * =$user= - reference to user object. This is the user expanded in e.g. %USERNAME. Optional, defaults to logged-in user.
       
   778 d368 2
       
   779 d411 24
       
   780 d444 6
       
   781 a449 5
       
   782 <verbatim>>
       
   783 ...Only alphanumerics [0-9a-zA-Z], the special
       
   784 characters $-_.+!*'(), and reserved characters used for their
       
   785 reserved purposes may be used unencoded within a URL.
       
   786 </verbatim>
       
   787 d453 6
       
   788 a458 3
       
   789 SMELL: For non-ISO-8859-1 $TWiki::cfg{Site}{CharSet}, need to convert to
       
   790 UTF-8 before URL encoding. This encoding only supports 8-bit
       
   791 character codes.
       
   792 d487 17
       
   793 d578 1
       
   794 a578 1
       
   795 ---++ ObjectMethod *handleCommonTags* <tt>($text,$web,$topic) -> $text</tt>
       
   796 d586 3
       
   797 @
       
   798 
       
   799 
       
   800 1.2
       
   801 log
       
   802 @buildrelease
       
   803 @
       
   804 text
       
   805 @d24 1
       
   806 d33 5
       
   807 a37 1
       
   808 $text is the HTML of the page body (&lt;html&gt; to &lt;/html&gt;)
       
   809 d39 2
       
   810 a40 1
       
   811 This method removes noautolink and nop tags before outputting the page.
       
   812 d60 14
       
   813 a73 1
       
   814 ---++ ObjectMethod *redirect* <tt>($url,...)</tt>
       
   815 d75 1
       
   816 a75 3
       
   817 Generate a CGI redirect to $url unless (1) $session->{cgiQuery} is undef or
       
   818 (2) $query->param('noredirect') is set to a true value. Thus a redirect is
       
   819 only generated when in a CGI context.
       
   820 a76 2
       
   821 The ... parameters are concatenated to the message written when printing
       
   822 to STDOUT, and are ignored for a redirect.
       
   823 d78 10
       
   824 a87 2
       
   825 Redirects the request to $url, via the CGI module object $query unless
       
   826 overridden by a plugin declaring a =redirectCgiQueryHandler=.
       
   827 d137 1
       
   828 a137 1
       
   829    * =...= - 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. <tt>getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2)</tt> will give <tt>.../view/x/y#XXX?a=1&b=2</tt>
       
   830 d196 3
       
   831 a203 12
       
   832 <pre>
       
   833 Input:                      Return:
       
   834   ( 'Web',  'Topic' )         ( 'Web',  'Topic' )
       
   835   ( '',     'Topic' )         ( 'Main', 'Topic' )
       
   836   ( '',     '' )              ( 'Main', 'WebHome' )
       
   837   ( '',     'Web/Topic' )     ( 'Web',  'Topic' )
       
   838   ( '',     'Web.Topic' )     ( 'Web',  'Topic' )
       
   839   ( 'Web1', 'Web2.Topic' )    ( 'Web2', 'Topic' )
       
   840   ( '%MAINWEB%', 'Web2.Topic' ) ( 'Main', 'Topic' )
       
   841   ( '%TWIKIWEB%', 'Web2.Topic' ) ( 'TWiki', 'Topic' )
       
   842 </pre>
       
   843 Note: Function renamed from getWebTopic
       
   844 d205 1
       
   845 a205 2
       
   846 SMELL: WARNING: this function defaults the web and topic names.
       
   847 Be very careful where you use it!
       
   848 d207 3
       
   849 d212 3
       
   850 a214 1
       
   851 ---++ ClassMethod *new* <tt>($remoteUser,$query)</tt>
       
   852 d217 5
       
   853 a221 2
       
   854    * =$remoteUser= the logged-in user (login name)
       
   855    * =$query= the query
       
   856 d226 1
       
   857 d236 1
       
   858 d267 1
       
   859 d274 21
       
   860 d296 1
       
   861 d433 2
       
   862 a434 1
       
   863 ---+++ registerRESTHandler( $subject, $verb, \&fn )
       
   864 d453 4
       
   865 a456 1
       
   866 ---+++ restDispatch( $subject, $verb) => \&fn
       
   867 d462 2
       
   868 d465 1
       
   869 d475 1
       
   870 d510 14
       
   871 @
       
   872 
       
   873 
       
   874 1.1
       
   875 log
       
   876 @buildrelease
       
   877 @
       
   878 text
       
   879 @d206 4
       
   880 a209 3
       
   881 to. Right now this only entails one activity: calling TWiki::Client to
       
   882 flushing the user's
       
   883 session (if any) to disk.
       
   884 @