See
PublishedAPI for packages intended to be used by Plugin and Contrib authors, or
browse all packages.
See also
Developing plugins,
Developer's Bible,
Technical Overview
internal package
Foswiki
Foswiki 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.
Public Data members
-
request
Pointer to the Foswiki::Request
-
response
Pointer to the Foswiki::Response
-
context
Hash of context ids
-
plugins
Foswiki::Plugins singleton
-
prefs
Foswiki::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
-
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.
-
access
Foswiki::Access singleton
-
store
Foswiki::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
Foswiki::Users singleton
-
webName
Name of web found in URL path, or web
URL parameter, or {UsersWebName}
StaticMethod
decode_utf8($octets) → $unicode
Decode a binary string of octets known to be encoded using UTF-8 into
perl characters (unicode).
StaticMethod
encode_utf8($unicode) → $octets
Encode a perl character string into a binary string of octets
encoded using UTF-8.
ObjectMethod
writeCompletePage( $text, $pageType, $contentType )
Write a complete HTML page with basic header to the browser.
-
$text
is the text of the page script (<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
This method removes noautolink and nop tags before outputting the page unless
$contentType is text/plain.
ObjectMethod
satisfiedByCache( $action, $web, $topic ) → $boolean
Try and satisfy the current request for the given web.topic from the cache, given
the current action (view, edit, rest etc).
If the action is satisfied, the cache content is written to the output and
true is returned. Otherwise ntohing is written, and false is returned.
Designed for calling from
Foswiki::UI::*
ObjectMethod
setCacheControl( $pageType, \%hopts )
Set the cache control headers in a response
-
$pageType
- page type - 'view', ;edit' etc
- =\%hopts - ref to partially filled in hash of headers
Set etags (and modify status) depending on what the cached page specifies.
Return 1 if the page has been modified since it was last retrieved, 0 otherwise.
-
$cachedPage
- page cache to use
- =\%hopts - ref to partially filled in hash of headers
All parameters are optional.
- =\%hopts - optional ref to partially filled in hash of headers (will be written to)
ObjectMethod
redirectto($url) → $url
If the CGI parameter 'redirectto' is present on the query, then will validate
that it is a legal redirection target (url or topic name). If 'redirectto'
is not present on the query, performs the same steps on $url.
Returns undef if the target is not valid, and the target URL otherwise.
StaticMethod
splitAnchorFromUrl( $url ) → ( $url, $anchor )
Takes a full url (including possible query string) and splits off the anchor.
The anchor includes the # sign. Returns an empty string if not found in the url.
ObjectMethod
redirect( $url, $passthrough, $status )
- $url - url or topic to redirect to
- $passthrough - (optional) parameter to pass through current query parameters (see below)
- $status - HTTP status code (30x) to redirect with. Defaults to 302.
Redirects the request to
$url
,
unless
- It is overridden by a plugin declaring a
redirectCgiQueryHandler
(a dangerous, deprecated handler!)
-
$session→{request}
is undef
Thus a redirect is only generated when in a CGI context.
Normally this method will ignore parameters to the current query. Sometimes,
for example when redirecting to a login page during authentication (and then
again from the login page to the original requested URL), you want to make
sure all parameters are passed on, and for this $passthrough should be set to
true. In this case it will pass all parameters that were passed to the
current query on to the redirect target. If the request_method for the
current query was GET, then all parameters will be passed by encoding them
in the URL (after ?). If the request_method was POST, then there is a risk the
URL would be too big for the receiver, so it caches the form data and passes
over a cache reference in the redirect GET.
NOTE: Passthrough is only meaningful if the redirect target is on the same
server.
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.
ObjectMethod
getCGISession() → $cgisession
Get the CGI::Session object associated with this session, if there is
one. May return undef.
ObjectMethod
getLoginManager() → $loginManager
Get the
Foswiki::LoginManager object associated with this session, if there is
one. May return undef.
StaticMethod
isValidWikiWord( $name ) → $boolean
Check for a valid
WikiWord or
WikiName
StaticMethod
isValidTopicName( $name [, $nonww] ) → $boolean
Check for a valid topic
$name
. If
$nonww
, then accept non wiki-words
(though they must still be composed of only valid, unfiltered characters)
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
If $Foswiki::cfg{EnableHierarchicalWebs} is off, it will also return false
when a nested web name is passed to it.
StaticMethod
isValidEmailAddress( $name ) → $boolean
STATIC Check for a valid email address name.
ObjectMethod
getSkin () → $string
Get the currently requested skin path
ObjectMethod
getScriptUrl( $absolute, $script, $web, $topic, … ) → $scriptURL
Returns the URL to a Foswiki script, providing the web and topic as
"path info" parameters. The result looks something like this:
"http://host/foswiki/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
If $absolute is set, generates an absolute URL. $absolute is advisory only;
Foswiki 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.
As required by RFC3986, the returned URL will only contain the
allowed characters -A-Za-z0-9_.~!*\'();:@&=+$,/?%#[]
StaticMethod
make_params(...)
Generate a URL parameters string from parameters given. A parameter
named '#' will generate a fragment identifier.
ObjectMethod
getPubURL($web, $topic, $attachment, %options) → $url
Composes a pub url.
-
$web
- name of the web for the URL, defaults to $session→{webName}
-
$topic
- name of the topic, defaults to $session→{topicName}
-
$attachment
- name of the attachment, defaults to no attachment
Supported %options are:
-
topic_version
- version of topic to retrieve attachment from
-
attachment_version
- version of attachment to retrieve
-
absolute
- requests an absolute URL (rather than a relative path)
If
$web
is not given,
$topic
and
$attachment
are ignored.
If
$topic
is not given,
$attachment
is ignored.
If
topic_version
is not given, the most recent revision of the topic
will be linked. Similarly if attachment_version= is not given, the most recent
revision of the attachment will be assumed. If
topic_version
is specified
but
attachment_version
is not (or the specified
attachment_version
is not
present), then the most recent version of the attachment in that topic version
will be linked.
If Foswiki is running in an absolute URL context (e.g. the skin requires
absolute URLs, such as print or rss, or Foswiki is running from the
command-line) then
absolute
will automatically be set.
Note: for compatibility with older plugins, which use %PUBURL*% with
a constructed URL path, do not use
*
unless
web
,
topic
, and
attachment
are all specified.
As required by RFC3986, the returned URL will only contain the
allowed characters -A-Za-z0-9_.~!*\'();:@&=+$,/?%#[]
ObjectMethod
deepWebList($filter, $web) → @list
Deep list subwebs of the named web. $filter is a
Foswiki::WebFilter
object that is used to filter the list. The listing of subwebs is
dependent on $Foswiki::cfg{EnableHierarchicalWebs} being true.
Webs are returned as absolute web pathnames.
ObjectMethod
normalizeWebTopicName( $web, $topic ) → ( $web, $topic )
Normalize a Web.TopicName
See
Foswiki::Func
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 $Foswiki::cfg{UsersWebName}. If there is no topic
specification, or the topic is '0', the topic defaults to the web home topic
name.
WARNING if the input topic name is tainted, then the output web and
topic names will be tainted.
StaticMethod
load_package( $full_package_name )
Will cleanly load the package or fail. This is better than 'eval "require $package"'.
It is not perfect for Perl < 5.10. For Perl 5.8, if somewhere else 'eval "require $package"'
was used
earlier for a module that fails to load, then not only is the failure not detected
then. Neither will it be detected here.
The recommendation is to replace all dynamic require calls in Foswiki to be replaced with this call.
This functionality used to be done via module Class::Load, but that had painful dependencies.
See
http://blog.fox.geek.nz/2010/11/searching-design-spec-for-ultimate.html for the gory details.
Private _parsePath( $this, $webtopic, $defaultweb, $topicOverride )
Parses the Web/Topic path parameters to safely establish a valid web and topic,
or assign safe defaults.
- $webtopic - A "web/topic" path. It might have originated from the query path_info, or from the topic= URL parameter. (only when the topic param contained a web component)
- $defaultweb - The default web to use if the web part of webtopic is missing or invalid. This can be from the default UsersWebName, or from the url parameter defaultweb.
- $topicOverride - A topic name to use instead of any topic provided in the pathinfo.
Note if $webtopic ends with a trailing slash, it provides a hint that the last component should be
considered web. This allows disambiguation between a topic and subweb with the same name.
Trailing slash forces it to be recognized as a webname, otherwise the topic is shown.
Note. If the web doesn't exist, the force will be ignored. It's not possible to create a missing web
by referencing it in a URL.
This routine sets two variables when encountering invalid input:
- $this→{invalidWeb} contains original invalid web / pathinfo content when validation fails.
- $this→{invalidTopic} Same function but for topic name
When invalid / illegal characters are encountered, the session {webName} and {topicName} will be
defaulted to safe defaults. Scripts using those fields should also test if the corresponding
invalid* versions are defined, and should throw an oops exception rathern than allowing execution
to proceed with defaulted values.
The topic name will always have the first character converted to upper case, to prevent creation of
or access to invalid topics.
ClassMethod
new( $defaultUser, $query, \%initialContext )
Constructs a new Foswiki session object. A unique session object exists for
every transaction with Foswiki, for example every browser request, or every
script run. Session objects do not persist between mod_perl runs.
-
$defaultUser
is the username (not the wikiname) of the default user you want to be logged-in, if none is available from a session or browser. Used mainly for unit tests and debugging, it is typically undef, in which case the default user is taken from $Foswiki::cfg{DefaultUserName}.
-
$query
the Foswiki::Request 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. May be undef.
ObjectMethod
renderer()
Get a reference to the renderer object. Done lazily because not everyone
needs the renderer.
ObjectMethod
renderer()
Get a reference to the zone renderer object. Done lazily because not everyone
needs the zones.
ObjectMethod
attach()
Get a reference to the attach object. Done lazily because not everyone
needs the attach.
ObjectMethod
templates()
Get a reference to the templates object. Done lazily because not everyone
needs the templates.
ObjectMethod
i18n()
Get a reference to the i18n object. Done lazily because not everyone
needs the i18ner.
ObjectMethod
reset_i18n()
Kill the i18n object, if there is one, to force language re-initialisation.
Essential for changing language dynamically.
ObjectMethod
logger()
ObjectMethod
search()
Get a reference to the search object. Done lazily because not everyone
needs the searcher.
ObjectMethod
net()
Get a reference to the net object. Done lazily because not everyone
needs the net.
ObjectMethod
access()
Get a reference to the ACL object.
ObjectMethod
DESTROY()
called by Perl when the Foswiki object goes out of scope
(maybe should be used kist to ASSERT that finish() was called..
ObjectMethod
finish()
Break circular references.
DEPRECATED ObjectMethod logEvent( $action, $webTopic, $extra, $user )
-
$action
- what happened, e.g. view, save, rename
-
$webTopic
- what it happened to
-
$extra
- extra info, such as minor flag
-
$user
- login name of user - default current user, or failing that the user agent
Write the log for an event to the logfile
The method is deprecated, Call logger→log directly.
StaticMethod
validatePattern( $pattern ) → $pattern
Validate a pattern provided in a parameter to $pattern so that
dangerous chars (interpolation and execution) are disabled.
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%
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
Foswiki::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
expandMacrosOnTopicCreation ( $topicObject )
Expand only that subset of Foswiki variables that are
expanded during topic creation, in the body text and
PREFERENCE meta only. The expansion is in-place inside
the topic object.
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 Foswiki.
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:
- all non-printable 7-bit chars (< \x1f), except \n (\xa) and \r (\xd)
- HTML special characters '>', '<', '&', ''' (single quote) and '"' (double quote).
- TML special characters '%', '|', '[', ']', '@', '_', '*', '$' and "="
$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.
This internal function is available for use by expanding the
%ENCODE
macro,
or the
%URLPARAM
macro, specifying
type="entities"
or
type="entity"
.
StaticMethod
entityDecode ( $encodedText ) → $text
Decodes all numeric entities (e.g. {).
Does not decode
named entities such as & (use HTML::Entities for that)
StaticMethod
urlEncode( $perlstring ) → $bytestring
Encode by converting characters that are reserved 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.
However this function is tuned for use with Foswiki. As such, it
encodes
all characters except 0-9a-zA-Z-_.:~!*/
This internal function is available for use by expanding the
%ENCODE
macro,
specifying
type="url"
. It is also the default encoding used by the
%URLPARAM
macro.
StaticMethod
urlDecode( $bytestring ) → $perlstring
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
innerExpandMacros(\$text, $topicObject)
Expands variables by replacing the variables with their
values. Some example variables: %TOPIC%, %SCRIPTURL%,
%WIKINAME%, etc.
$web and $incs are passed in for recursive include expansion. They can
safely be undef.
The rules for tag expansion are:
- Tags are expanded left to right, in the order they are encountered.
- Tags are recursively expanded as soon as they are encountered - the algorithm is inherently single-pass
- A tag is not "encountered" until the matching }% has been seen, by which time all tags in parameters will have been expanded
- Tag expansions that create new tags recursively are limited to a set number of hierarchical levels of expansion
StaticMethod
takeOutBlocks( \$text, $tag, \%map ) → $text
-
$text
- Text to process
-
$tag
- XML-style tag.
-
\%map
- Reference to a hash to contain the removed blocks
Return value: $text with blocks removed
Searches through $text and extracts blocks delimited by an XML-style tag,
storing the extracted block, and replacing with a token string which is
not affected by TML rendering. The text after these substitutions is
returned.
StaticMethod
putBackBlocks( \$text, \%map, $tag, $newtag, $callBack ) → $text
Return value: $text with blocks added back
-
\$text
- reference to text to process
-
\%map
- map placeholders to blocks removed by takeOutBlocks
-
$tag
- Tag name processed by takeOutBlocks
-
$newtag
- Tag name to use in output, in place of $tag. If undefined, uses $tag.
-
$callback
- Reference to function to call on each block being inserted (optional)
Reverses the actions of takeOutBlocks.
Each replaced block is processed by the callback (if there is one) before
re-insertion.
Parameters to the outermost cut block are replaced into the open tag,
even if that tag is changed. This allows things like
<verbatim class=''>
to be changed to
<pre class=''>
If you set $newtag to ”, replaces the taken-out block with the contents
of the block, not including the open/close. This is used for <literal>,
for example.
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, $syntax )
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 )
-
$syntax
somewhat legacy - 'classic' or 'context-free' (context-free may be removed in future)
$syntax parameter:
Way back in prehistory, back when the dinosaur still roamed the earth,
Crawford tried to extend the tag syntax of macros such that they could be processed
by a context-free parser (hence the "context-free")
and bring them into line with HTML.
This work was banjaxed by one particular tyrranosaur,
who felt that the existing syntax was perfect.
However by that time Crawford had used it in a couple of places - most notable in the action tracker.
The syntax isn't vastly different from what's there; the differences are:
- Use either type of quote for parameters
- Optional quotes on parameter values e.g. recurse=on
- Standardised use of \ for escapes
- Boolean (valueless) options (i.e. recurse instead of recurse="on"
ObjectMethod
expandMacros( $text, $topicObject ) → $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.
$topicObject may be undef when, for example, expanding templates, or one-off strings
at a time when meta isn't available.
DO NOT CALL THIS DIRECTLY; use $topicObject→expandMacros instead.
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. See
FormatTokens for a full list of supported tokens.
ObjectMethod
webExists( $web ) → $boolean
Test if web exists
-
$web
- Web name, required, e.g. 'Sandbox'
A web
has to have a preferences topic to be a web.
ObjectMethod
topicExists( $web, $topic ) → $boolean
Test if topic exists
-
$web
- Web name, optional, e.g. 'Main'
-
$topic
- Topic name, required, e.g. 'TokyoOffice'
, or "Main.TokyoOffice"
ObjectMethod
getWorkArea( $key ) → $directorypath
Gets a private directory uniquely identified by $key. The directory is
intended as a work area for plugins etc. The directory will exist.
ObjectMethod
getApproxRevTime ( $web, $topic ) → $epochSecs
Get an approximate rev time for the latest rev of the topic. This method
is used to optimise searching. Needs to be as fast as possible.