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' )
( '%MAINWEB%', 'Web2.Topic' ) ( 'Main', 'Topic' )
( '%TWIKIWEB%', 'Web2.Topic' ) ( 'TWiki', 'Topic' )
Note: Function renamed from getWebTopic
SMELL: WARNING: this function defaults the web and topic names.
Be very careful where you use it!
---++ ClassMethod *new* ($remoteUser,$query)
Constructs a new TWiki object. Parameters are taken from the query object.
* =$remoteUser= the logged-in user (login name)
* =$query= the query
---++ ObjectMethod *finish*
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.
---++ 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)
Write the log for an event to the logfile
---++ 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
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%
---++ 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.
Expand limited set of variables during topic creation. These are variables
expected in templates that must be statically expanded in new content.
# 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, <. 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.
(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 )
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.
The handler function must be of the form:
sub handler(\%session,$subject,$verb) -> $text
where:
* =\%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
Returns the handler function associated to the given $subject and $werb,
or undef if none is found.
*Since:* TWiki::Plugins::VERSION 1.1
---++ ObjectMethod *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*.