|
|
|||||||||||||||||
Package
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.
|
|||||||||||||||||
| site name | URL | link | note |
ObjectMethod getSkin () -> $string
Get the currently requested skin pathObjectMethod 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?a=1&b=2#XXX
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 '¶m1=' etc.
ObjectMethod normalizeWebTopicName ($theWeb,$theTopic) -> ($theWeb,$theTopic)
Normalize a Web.TopicName See TWikiFuncDotPm for a full specification of the expansion (not duplicated here) WARNING if there is no web specification (in the web or topic parameters) the web defaults to $TWiki::cfg{UsersWebName}. If there is no topic specification, or the topic is '0', the topic defaults to the web home topic name.ClassMethod new ($loginName,$query,\%initialContext)
Constructs a new TWiki object. Parameters are taken from the query object.-
$loginNameis 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. -
$querythe 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 finish
Complete processing after the client's HTTP request has been responded to. Right now this does two things:- calling TWiki::Client to flushing the user's session (if any) to disk,
- breaking circular references to allow garbage collection in persistent environments
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 subsetObjectMethod inlineAlert ($template,$def,...) -> $string
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%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 aTWiki::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.
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.
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, <. Similarly, ">" is escaped as >, and "&" is escaped as &. If an attribute value contains a double quotation mark and is delimited by double quotation marks, then the quote should be escaped as ". 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. {). Does not decode named entities such as & (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.Reserved characters are $&+,/:;=?@ - these are also encoded by this method. 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. (seeenterContext for more information on contexts)
ObjectMethod inContext ($id)
Return the value for the given context id (seeenterContext for more information on contexts)
StaticMethod registerTagHandler ($tag,$fnref)
STATIC Add a tag handler to the function tag handlers.-
$tagname of the tag e.g. MYTAG -
$fnrefFunction to execute. Will be passed ($session, \%params, $web, $topic )
StaticMethod registerRESTHandler ($subject,$verb,\&fn)
Adds a function to the dispatch table of the REST interface for a given subject. See TWikiScripts#rest for more info.-
$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.
sub handler(\%session,$subject,$verb) -> $textwhere:
-
\%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)
StaticMethod restDispatch ($subject,$verb)=>\&fn
Returns the handler function associated to the given $subject and $werb, or undef if none is found. Since: TWiki::Plugins::VERSION 1.1ObjectMethod handleCommonTags ($text,$web,$topic) -> $text
Processes %VARIABLE%, and %TOC% syntax; also includes 'commonTagsHandler' plugin hook. 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)
Add$html to the HEAD tag of the page currently being generated.
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.StaticMethod expandStandardEscapes ($str) -> $unescapedStr
Expands standard escapes used in parameter values to block evaluation. The following escapes are handled:| Escape: | Expands To: |
|---|---|
$n or $n() | New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() | Is a "no operation". |
$quot | Double quote (") |
$percnt | Percent sign (%) |
$dollar | Dollar sign ($) |
