Bookmaker for ExampleBook
| Change book | Close bookmaker |
You can change the order/nesting of topics using drag and drop
Bookmaker for ExampleBook
| Change book | Close bookmaker |
|
|
internal package Foswiki 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.
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 ) $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
ObjectMethod setETags( $cachedPage, \%hopts ) → $boolean 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
ObjectMethod generateHTTPHeaders( \%hopts ) 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, unless redirectCgiQueryHandler (a dangerous, deprecated handler!)
$session->{request} is undef
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 StaticMethod isValidWikiWord( $name ) → $boolean StaticMethod isValidTopicName( $name [, $nonww] ) → $boolean $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 ... - an arbitrary number of name,value parameter pairs that will
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(...) ObjectMethod getPubURL($web, $topic, $attachment, %options) → $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
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)
$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 Webs are returned as absolute web pathnames.
ObjectMethod normalizeWebTopicName( $web, $topic ) → ( $web, $topic ) Normalize a Web.TopicName
SeeFoswiki::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.Parses the Web/Topic path parameters to safely establish a valid web and topic, or assign safe defaults.
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: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() ObjectMethod renderer() ObjectMethod attach() ObjectMethod templates() ObjectMethod i18n() ObjectMethod reset_i18n() ObjectMethod logger() ObjectMethod search() ObjectMethod net() ObjectMethod access() 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() $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 aFoswiki::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 ) $topicObject - the topic
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.
# SMELL: no plugin handler
StaticMethod entityEncode( $text [, $extras] ) → $encodedText Other entities exist for special characters that cannot easily be entered with some keyboards..."
This method encodes:%ENCODE macro,
or the %URLPARAM macro, specifying type="entities" or type="entity".
StaticMethod entityDecode ( $encodedText ) → $text StaticMethod urlEncode( $perlstring ) → $bytestring
...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 $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) 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 \$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 ) enterContext for more information on contexts)
ObjectMethod inContext( $id ) enterContext for more information on contexts)
StaticMethod registerTagHandler( $tag, $fnref, $syntax ) $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: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 ObjectMethod webExists( $web ) → $boolean $web - Web name, required, e.g. 'Sandbox'
ObjectMethod topicExists( $web, $topic ) → $boolean $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.
SMELL: is there a reason this is in Foswiki.pm, and not in Search?
Copyright © by the contributing authors. All material on this site is the property of the contributing authors. 
About