ObjectMethod determineWebTopic ($pathInfo,$web,$topic) -> ($web,$topic,$requestedWeb)

Determine the web and topic names from PATH_INFO and web and topic names explicitly provided. And then sanitize them.

Parameter $sep defines the separator between the word components, the default is a space.

Example: "ABC2015ProjectCharter" results in "ABC 2015 Project Charter"

StaticMethod suffixToMimeType ($filename) -> $mimeType

Returns the MIME type corresponding to the extension of the $filename based on the file specified by {MimeTypesFileName}. If there is no extension or the extension is not found in the {MimeTypesFileName} file, 'text/plain' is returned.

Public Data members

ObjectMethod writeCompletePage ($text,$pageType,$contentType,$status)

• $status - page status | 200 OK

ObjectMethod generateHTTPHeaders ($pageType,$contentType,$status) -> $header

• $status - page status | 200 OK

ObjectMethod redirect ($url,$passthrough,$action_redirectto,$viaCache)

• $viaCache - forcibly cache a redirect CGI query. It cuts off all the params in a GET url and replace with a "?$cache=..." param.

ObjectMethod modeAndMaster ($web)

('', undef)

('slave', { # master site data
    siteName         => 'na',
    webScriptUrlTmpl => 'http://twiki.example.com/cgi-bin//Web',
    scriptSuffix     => '',
    webViewUrl       => 'http://twiki.example.com/Web',
})

Even with the other scripts, you may need to get the URLs on the master site. You can get those URLs by providing $master => 1 as a name value pair.

ObjectMethod getDiskInfo ($web,$site,$diskID) -> ($dataDir,$pubDir,$diskID)

You can specify either $web or $diskID, not both.

ObjectMethod getDiskList () -> ('',1,2,...)

ObjectMethod getDataDir ($web,$diskID) -> $dataDir

You can specify either $web or $diskID, not both.

ObjectMethod getPubDir ($web,$diskID) -> $pubDir

You can specify either $web or $diskID, not both.

StaticMethod topLevelWeb ($web) -> toplevelwebof$web

If $web is a top level web, it returns $web. If $web is a subweb, it returns the top level web of $web.

%RENDERHEAD%

• $web - name of web, optional
• $topic - name of topic, optional

• ... - an arbitrary number of name,value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2) will give .../view/x/y?a=1&b=2#XXX

• request Pointer to the TWiki::Request
• response Pointer to the TWiki::Respose

ObjectMethod UTF82SiteCharSet ($utf8) -> $ascii

ObjectMethod generateHTTPHeaders ($pageType,$contentType,$contentLength) -> $header

1. $session->{request} is undef or

ObjectMethod cacheIconData ($action)

• 'delete' - delete cache file
• 'read' - read cache file
• 'expire' - expire (invalidate) cache if needed
• 'save' - save cache file

ObjectMethod formatIcon ($iconName,$format,$default) -> $icon

Format an icon based on name and format parameter. The format parameter handles these variables (with example):

• $name: Name of icon ('home')
• $type: Type of icon ('gif')
• $filename: Icon filename ('home.gif')
• $web: Web where icon is located ('TWiki')
• $topic: Topic where icon is located ('TWikiDocGraphics')
• $description: Icon description ('Home')
• $width: Width of icon ('16')
• $height: Height of icon ('16')
• $img: Full img tag of icon ('')
• $url: URL of icon ('http://example.com/pub/TWiki/TWikiDocGraphics/home.gif')
• $urlpath: URL path of icon ('/pub/TWiki/TWikiDocGraphics/home.gif')

• $query the TWiki::Request query (may be undef, in which case an empty query

ObjectMethod ADDTOHEAD ($args)

%ADDTOHEAD%

• _DEFAULT optional, id of the head block. Used to generate a comment in the output HTML.
• text optional, text to use for the head block. Mutually exclusive with topic.
• topic optional, full TWiki path name of a topic that contains the full text to use for the head block. Mutually exclusive with text. Example: topic="TWiki.MyTopic".
• requires optional, comma-separated list of id's of other head blocks this one depends on.

Use %RENDERHEAD% to generate the sorted head tags.

%<nop}RENDERHEAD%

<-- ... -->

Public Data members

• cgiQuery Pointer to the CGI::
• context Hash of context ids
• moved: loginManager TWiki::LoginManager singleton (moved to TWiki::Users)
• plugins TWiki::Plugins singleton
• prefs TWiki::Prefs singleton
• remoteUser Login ID when using ApacheLogin. Maintained for compatibility only, do not use.
• requestedWebName Name of web found in URL path or web URL parameter
• sandbox TWiki::Sandbox singleton
• scriptUrlPath URL path to the current script. May be dynamically extracted from the URL path if {GetScriptUrlFromCgi}. Only required to support {GetScriptUrlFromCgi} and not consistently used. Avoid.
• security TWiki::Access singleton
• SESSION_TAGS Hash of TWiki variables whose value is specific to the current CGI request.
• store TWiki::Store singleton
• topicName Name of topic found in URL path or topic URL parameter
• urlHost Host part of the URL (including the protocol) determined during intialisation and defaulting to {DefaultUrlHost}
• user Unique user ID of logged-in user
• users TWiki::Users singleton
• webName Name of web found in URL path, or web URL parameter, or {UsersWebName}

StaticMethod UTF82SiteCharSet ($utf8) -> $ascii

ObjectMethod generateHTTPHeaders ($query,$pageType,$contentType,$contentLength) -> $header

StaticMethod isRedirectSafe ($redirect)=>$ok

ObjectMethod redirect ($url,$passthrough,$action_redirectto)

• $url - url or twikitopic to redirect to
• $passthrough - (optional) parameter to *FILLMEIN*
• $action_redirectto - (optional) redirect to where ?redirectto= points to (if it's valid)

ObjectMethod normalizeWebTopicName ($theWeb,$theTopic) -> ($theWeb,$theTopic)

Normalize a Web.TopicName

ClassMethod new ($loginName,$query,\%initialContext)

• $loginName is the login username (not the wikiname) of the user you want to be logged-in if none is available from a session or browser. Used mainly for side scripts and debugging.
• $query the CGI query (may be undef, in which case an empty query is used)
• \%initialContext - reference to a hash containing context name=value pairs to be pre-installed in the context hash

ObjectMethod renderer ()

ObjectMethod attach ()

ObjectMethod templates ()

ObjectMethod i18n ()

ObjectMethod search ()

ObjectMethod security ()

ObjectMethod net ()

ObjectMethod finish ()

• $user - user who did the saving (user id)

ObjectMethod expandVariablesOnTopicCreation ($text,$user,$web,$topic) -> $text

• $user - This is the user expanded in e.g. %USERNAME. Optional, defaults to logged-in user.

• $web - name of web
• $topic - name of topic

StaticMethod urlEncodeAttachment ($text)

For attachments, URL-encode specially to 'freeze' any characters >127 in the site charset (e.g. ISO-8859-1 or KOI8-R), by doing URL encoding into native charset ($siteCharset) - used when generating attachment URLs, to enable the web server to serve attachments, including images, directly.

This encoding is required to handle the cases of:

- browsers that generate UTF-8 URLs automatically from site charset URLs - now quite common - web servers that directly serve attachments, using the site charset for filenames, and cannot convert UTF-8 URLs into site charset filenames

The aim is to prevent the browser from converting a site charset URL in the web page to a UTF-8 URL, which is the default. Hence we 'freeze' the URL into the site character set through URL encoding.

In two cases, no URL encoding is needed: For EBCDIC mainframes, we assume that site charset URLs will be translated (outbound and inbound) by the web server to/from an EBCDIC character set. For sites running in UTF-8, there's no need for TWiki to do anything since all URLs and attachment filenames are already in UTF-8.

This may not handle EBCDIC properly, as it generates an EBCDIC URL-encoded URL, but mainframe web servers seem to translate this outbound before it hits browser - see CGI::Util::escape for another approach.

ObjectMethod expandAllTags (\$text,$topic,$web,$meta)

1. Tags are expanded left to right, in the order they are encountered.
2. Tags are recursively expanded as soon as they are encountered - the algorithm is inherently single-pass
3. A tag is not "encountered" until the matching }% has been seen, by which time all tags in parameters will have been expanded
4. Tag expansions that create new tags recursively are limited to a set number of hierarchical levels of expansion

ObjectMethod handleCommonTags ($text,$web,$topic,$meta) -> $text

• $text is the text of the page body (<html> to </html> if it's HTML)
• $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.
• $contentType - page content type | text/html

ObjectMethod redirect ($url,$passthrough)

Redirects the request to $url, unless

1. It is overridden by a plugin declaring a redirectCgiQueryHandler.
2. $session->{cgiQuery} is undef or
3. $query->param('noredirect') is set to a true value.

Normally this method will ignore parameters to the current query. If $passthrough is set, then it will pass all parameters that were passed to the current query on to the redirect target. If the request_method was GET, then all parameters can be passed in the URL. If the request_method was POST then it caches the form data and passes over a cache reference in the redirect GET.

ObjectMethod cacheQuery () -> $queryString

Caches the current query in the params cache, and returns a rewritten query string for the cache to be picked up again on the other side of a redirect.

We can't encode post params into a redirect, because they may exceed the size of the GET request. So we cache the params, and reload them when the redirect target is reached.

• ... - an arbitrary number of name,value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2) will give .../view/x/y?a=1&b=2#XXX

ClassMethod new ($loginName,$query,\%initialContext)

• $loginName is the username of the user you want to be logged-in if none is available from a session or browser. Used mainly for side scripts and debugging.
• $query the CGI query (may be undef, in which case an empty query is used)
• \%initialContext - reference to a hash containing context name=value pairs to be pre-installed in the context hash

StaticMethod parseSections ($text) -> ($string,$sectionlistref)

Generic parser for sections within a topic. Sections are delimited by STARTSECTION and ENDSECTION, which may be nested, overlapped or otherwise abused. The parser builds an array of sections, which is ordered by the order of the STARTSECTION within the topic. It also removes all the SECTION tags from the text, and returns the text and the array of sections.

Each section is a TWiki::Attrs object, which contains the attributes {type, name, start, end} where start and end are character offsets in the string after all section tags have been removed. All sections are required to be uniquely named; if a section is unnamed, it will be given a generated name. Sections may overlap or nest.

See test/unit/Fn_SECTION.pm for detailed testcases that round out the spec.

StaticMethod registerRESTHandler ($subject,$verb,\&fn)

StaticMethod restDispatch ($subject,$verb)=>\&fn

StaticMethod expandStandardEscapes ($str) -> $unescapedStr

Expands standard escapes used in parameter values to block evaluation. The following escapes are handled:

1. calling TWiki::Client to flushing the user's session (if any) to disk,
2. breaking circular references to allow garbage collection in persistent environments

Package TWiki

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.

Global variables are avoided wherever possible to avoid problems with CGI accelerators such as mod_perl.

StaticMethod getTWikiLibDir () -> $path

STATIC method.

Returns the full path of the directory containing TWiki.pm

ObjectMethod UTF82SiteCharSet ($utf8) -> $ascii

ObjectMethod writeCompletePage ($text,$pageType,$contentType)

Write a complete HTML page with basic header to the browser. $text is the HTML of the page body (<html> to </html>)

This method removes noautolink and nop tags before outputting the page.

ObjectMethod writePageHeader ($query,$pageType,$contentType,$contentLength)

All parameters are optional.

• $query CGI query object | Session CGI query (there is no good reason to set this)
• $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.
• $contentType - page content type | text/html
• $contentLength - content-length | no content-length will be set if this is undefined, as required by HTTP1.1

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.

ObjectMethod redirect ($url,...)

Generate a CGI redirect to $url unless (1) $session->{cgiQuery} is undef or (2) $query->param('noredirect') is set to a true value. Thus a redirect is only generated when in a CGI context.

The ... parameters are concatenated to the message written when printing to STDOUT, and are ignored for a redirect.

Redirects the request to $url, via the CGI module object $query unless overridden by a plugin declaring a redirectCgiQueryHandler.

StaticMethod isValidWikiWord ($name) -> $boolean

Check for a valid WikiWord or WikiName

StaticMethod isValidTopicName ($name) -> $boolean

Check for a valid topic name

StaticMethod isValidAbbrev ($name) -> $boolean

Check for a valid ABBREV (acronym)

StaticMethod isValidWebName ($name,$system) -> $boolean

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

ObjectMethod readOnlyMirrorWeb ($theWeb) -> ($mirrorSiteName,$mirrorViewURL,$mirrorLink,$mirrorNote)

If this is a mirrored web, return information about the mirror. The info is returned in a quadruple:

ObjectMethod getSkin () -> $string

Get the currently requested skin path

ObjectMethod getScriptUrl ($absolute,$script,$web,$topic,...) -> $scriptURL

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".

• ... - 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

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.

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.

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.

ObjectMethod getPubUrl ($absolute,$web,$topic,$attachment) -> $url

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.

$web, $topic and $attachment are optional. A partial URL path will be generated if one or all is not given.

ObjectMethod getIconUrl ($absolute,$iconName) -> $iconURL

Map an icon name to a URL path.

ObjectMethod mapToIconFileName ($fileName,$default) -> $fileName

Maps from a filename (or just the extension) to the name of the file that contains the image for that file type.

ObjectMethod getOopsUrl ($template,@options) -> $absoluteOopsURL

Composes a URL for an "oops" error page. The @options consists of a list of key => value pairs. The following keys are used:

• -web - web name
• -topic - topic name
• -def - optional template def within the main template file
• -params - a single parameter, or a reference to an array of parameters These are passed in the URL as '&param1=' etc.

Do not include the "oops" part in front of the template name.

Alternatively you can pass a reference to an OopsException in place of the template. All other parameters will be ignored.

The returned URL ends up looking something like this: "http://host/twiki/bin/oops/$web/$topic?template=$template&param1=$scriptParams[0]..."

ObjectMethod normalizeWebTopicName ($theWeb,$theTopic) -> ($theWeb,$theTopic)

Normalize a Web.TopicName

Input:                      Return:
  ( 'Web',  'Topic' )         ( 'Web',  'Topic' )
  ( '',     'Topic' )         ( 'Main', 'Topic' )
  ( '',     '' )              ( 'Main', 'WebHome' )
  ( '',     'Web/Topic' )     ( 'Web',  'Topic' )
  ( '',     'Web.Topic' )     ( 'Web',  'Topic' )
  ( 'Web1', 'Web2.Topic' )    ( 'Web2', 'Topic' )
  ( 'Main', 'Web2.Topic' ) ( 'Main', 'Topic' )
  ( 'TWiki', 'Web2.Topic' ) ( 'TWiki', 'Topic' )

SMELL: WARNING: this function defaults the web and topic names. Be very careful where you use it!

ClassMethod new ($remoteUser,$query)

• $remoteUser the logged-in user (login name)
• $query the query

ObjectMethod finish

ObjectMethod writeLog ($action,$webTopic,$extra,$user)

• $action - what happened, e.g. view, save, rename
• $wbTopic - what it happened to
• $extra - extra info, such as minor flag
• $user - user who did the saving (user object or string user name)

ObjectMethod writeWarning ($text)

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).

ObjectMethod writeDebug ($text)

Prints date, time, and contents of $text to $TWiki::cfg{DebugFileName}, typically 'debug.txt'. Use for debugging messages.

StaticMethod applyPatternToIncludedText ($text,$pattern) -> $text

Apply a pattern on included text to extract a subset

ObjectMethod inlineAlert ($template,$def,...) -> $string

ObjectMethod expandVariablesOnTopicCreation ($text,$user) -> $text

• $text - text to expand
• $user - reference to user object. This is the user expanded in e.g. %USERNAME. Optional, defaults to logged-in user.

# SMELL: no plugin handler

StaticMethod entityEncode ($text,$extras) -> $encodedText

Escape special characters to HTML numeric entities. This is not a generic encoding, it is tuned specifically for use in TWiki.

HTML4.0 spec: "Certain characters in HTML are reserved for use as markup and must be escaped to appear literally. The "<" character may be represented with an entity, &lt;. Similarly, ">" is escaped as &gt;, and "&" is escaped as &amp;. If an attribute value contains a double quotation mark and is delimited by double quotation marks, then the quote should be escaped as &quot;.

Other entities exist for special characters that cannot easily be entered with some keyboards..."

This method encodes HTML special and any non-printable ascii characters (except for \n and \r) using numeric entities.

FURTHER this method also encodes characters that are special in TWiki meta-language.

$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.

StaticMethod entityDecode ($encodedText) -> $text

Decodes all numeric entities (e.g. &#123;). Does not decode named entities such as &amp; (use HTML::Entities for that)

StaticMethod urlEncode ($string) -> encodedstring

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 ?.

RFC 1738, Dec. '94:

>
...Only alphanumerics [0-9a-zA-Z], the special
characters $-_.+!*'(), and reserved characters used for their
reserved purposes may be used unencoded within a URL.

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.

StaticMethod urlDecode ($string) -> decodedstring

Reverses the encoding done in urlEncode.

StaticMethod isTrue ($value,$default) -> $boolean

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.

If the value is undef, then $default is returned. If $default is not specified it is taken as 0.

StaticMethod spaceOutWikiWord ($word,$sep) -> $string

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.

ObjectMethod enterContext ($id,$val)

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.

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.

Contexts are not just useful for tag expansion; they are also relevant when rendering.

Contexts are intended for use mainly by plugins. Core modules can use $session->inContext( $id ) to determine if a context is active.

ObjectMethod leaveContext ($id)

Remove the context id $id from the set of active contexts. (see enterContext for more information on contexts)

ObjectMethod inContext ($id)

Return the value for the given context id (see enterContext for more information on contexts)

StaticMethod registerTagHandler ($tag,$fnref)

STATIC Add a tag handler to the function tag handlers.

• $tag name of the tag e.g. MYTAG
• $fnref Function to execute. Will be passed ($session, \%params, $web, $topic )

registerRESTHandler( $subject, $verb, \&fn )

• $subject - The subject under which the function will be registered.
• $verb - The verb under which the function will be registered.
• \&fn - Reference to the function.

The handler function must be of the form:

sub handler(\%session,$subject,$verb) -> $text

• \%session - a reference to the TWiki session object (may be ignored)
• $subject - The invoked subject (may be ignored)
• $verb - The invoked verb (may be ignored)

Since: TWiki::Plugins::VERSION 1.1

restDispatch( $subject, $verb) => \&fn

Since: TWiki::Plugins::VERSION 1.1

ObjectMethod handleCommonTags ($text,$web,$topic) -> $text

Returns the text of the topic, after file inclusion, variable substitution, table-of-contents generation, and any plugin changes from commonTagsHandler.

ObjectMethod addToHEAD ($id,$html)

Note that TWiki variables may be used in the HEAD. They will be expanded according to normal variable expansion rules.

The 'id' is used to ensure that multiple adds of the same block of HTML don't result in it being added many times.

StaticMethod initialize ($pathInfo,$remoteUser,$topic,$url,$query) -> ($topicName,$webName,$scriptUrlPath,$userName,$dataDir)

Return value: ( $topicName, $webName, $TWiki::cfg{ScriptUrlPath}, $userName, $TWiki::cfg{DataDir} )

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.

This method is DEPRECATED but is maintained for script compatibility.

Note that $theUrl, if specified, must be identical to $query->url()

StaticMethod readFile ($filename) -> $text

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.

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.