• $format - Format type, optional. Default e.g. '2014-12-31 - 19:30'. Can be '$iso' (e.g. '2014-12-31T19:30Z'), '$rcs' (e.g. '2014/12/31 23:59:59', '$http' for HTTP header format (e.g. 'The, 2014-07-23 07:21:56 GMT'), or any string with tokens '$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz' for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively

• The version number is now aligned with the TWiki release version.
• A TWiki-6.7.8 release will have a $TWiki::Plugins::VERSION = 6.78.
• In an unlikely case where the patch number is 10 or larger, the patch number is added to the previous patch number. For example, TWiki-6.7.9 will have version 6.79, TWiki-6.7.10 will have 6.7910, and TWiki-6.7.11 will have 6.7911. This ensures that the version number can sort properly.

getExternalResource( $url, \@headers, \%params ) -> $response

• \@headers (an array ref): Additional HTTP headers of form 'name1', 'value1', 'name2', 'value2'. User-Agent header is set to "TWiki::Net/### libwww-perl/#.##" by default, where ### is the revision number of TWiki::Net and #.## is the version of LWP.
• \%params (a hash ref): Additional options.

Below is the list of available %params. See CPAN:LWP::UserAgent for more details.

Example:

my $response = getExternalResource($url,
    ['Cache-Control' => 'max-age=0'], {timeout => 10});

postExternalResource( $url, $text, \@headers, \%params ) -> $response

This method is essentially the same as getExternalResource() except that it uses an HTTP POST method and that the additional $text parameter is required.

The $text is sent to the server as the body content of the HTTP request.

See getExternalResource() for more details.

Since: TWiki::Plugins::VERSION 6.00

• • MyPlugin topic has: * Set COLOR = red

• • MyPlugin topic has: * Set SHOWHELP = off

isAnAdmin( $user, $topic, $web ) -> $boolean

• $user can be either a login name or a WikiName
• a user mapping handler's isAdmin() may take $topic and $web arguments. That's why this function takes them too. For a user mapping handler whose isAdmin() doesn't care $topic and $web (e.g. TWikiUserMapping), $topic and $web are irrelevant, needless to say.

• Set ALLOWTOPICSPIN = IncyWincy

• $ignorePermissions - Set to "1" if checkAccessPermission() is already performed and OK.

redirectCgiQuery( $query, $url, $passthru, $viaCache )

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

• requires optional, comma-separated list of id's of other head blocks this one depends on. Those blocks will be loaded first.

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

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

registerExternalHTTPHandler( \&fn )

Should only be called from initPlugin.

Adds a function to modify all the HTTP requests to any external resources.

• \&fn - Reference to the function.

The handler function must be of the form:

sub handler(\%session, $url) -> (\@headers, \%params)

• \%session - a reference to the TWiki session object (may be ignored)
• $url - a URL being requested

The returned \@headers and \%params are added to the request in the same manner as getExternalResource, except that \%params will not override any entries that have been set earlier. All the params explicitly given by the caller of getExternalResource or postExternalResource will have the highest precedence.

Example:

sub initPlugin {
    TWiki::Func::registerExternalHTTPHandler( \&handleExternalHTTPRequest );
}

sub handleExternalHTTPRequest {
    my ($session, $url) = @_;
    my @headers;
    my %params;

    # Add any necessary @headers and %params
    push @headers, 'X-Example-Header' => 'Value';
    $params{timeout} = 5;

    # Return refs to both
    return (\@headers, \%params);
}

Since: TWiki::Plugins::VERSION 6.00

Read-only and Mirror Webs

The following functions are for ReadOnlyAndMirrorWebs.

getSiteName() -> $siteName

Returns the current site name if it's defined. Otherwise returns the null string.

getContentMode( $web ) -> $contentMode

Returns the content mode of the specified $web. Please read ReadOnlyAndMirrorWebs about content mode.

Since: TWiki::Plugins::VERSION 6.00

webWritable( $web ) -> $boolean

Checks if the web is wriable on this site - if it's master or local. Returns true if it's writable. Returns false otherwise.

Since: TWiki::Plugins::VERSION 6.00

Using multiple disks

The following functions are for UsingMultipleDisks.

getDiskList() -> @diskIDs

Returns IDs of disks used by TWiki. An disk ID is "" (a null string) or a decimal number without leading 0.

Since: TWiki::Plugins::VERSION 6.00

getDiskInfo($web, [$diskID]) -> ($dataDir, $pubDir, $diskID)

Returns the relevant paths and the disk ID of the specified web on the specified site.

Since: TWiki::Plugins::VERSION 6.00

trashWebName(web => $web | disk => $diskID) -> $trashWebName

Returns the name of the trash web to which topics of the $web web are moved. Or returns the name of the trash web of the specified disk.

Each disk (file system) TWiki uses needs to have a trash web since a topic deletion may entail an attachment directory move, which is possible only within the same disk/file system.

Since: TWiki::Plugins::VERSION 6.00

• $user - WikiName, login name or cUID of user, optional. Name of logged-in user is taken if not specified.

• $format - Format type, optional. Default e.g. '2013-12-31 - 19:30'. Can be '$iso' (e.g. '2013-12-31T19:30Z'), '$rcs' (e.g. '2013/12/31 23:59:59', '$http' for HTTP header format (e.g. 'The, 2013-07-23 07:21:56 GMT'), or any string with tokens '$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz' for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively

entityEncode( $text, $extra ) -> $text

Entity encode text.

• $text - Text to encode, may be empty
• $extra - Additional characters to include in the set of encoded characters, optional

Since: TWiki::Plugins::VERSION 6.00

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.

entityDecode( $text ) -> $text

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

• $text - Text to decode, may be empty

Since: TWiki::Plugins::VERSION 6.00

urlEncode( $text ) -> $text

URL encode text, mainly used to encode URL parameters.

• $text - Text to encode, may be empty

Since: TWiki::Plugins::VERSION 6.00

Encoding is done 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.

This URL-encoding handles all character encodings including ISO-8859-*, KOI8-R, EUC-* and 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.

urlDecode( $text ) -> $text

URL decode text, mainly used to decode URL parameters.

• $text - Text to decode, may be empty

Since: TWiki::Plugins::VERSION 6.00

TWiki-6.0 (Jerusalem Release)

EmptyPlugin.pm

Func.pm

• isAnAdmin( $user, $topic, $web ) -> $boolean -- added $topic and $web
• expandVariablesOnTopicCreation( $text, $web, $topic ) -> $text -- added $web and $topic
• postExternalResource( $url, $text, \@headers, \%params ) -> $response
• registerExternalHTTPHandler( \&fn )
• getContentMode( $web ) -> $contentMode
• webWritable( $web ) -> $boolean
• getDiskList() -> @diskIDs
• getDiskInfo($web, $siteName) -> ($dataDir, $pubDir, $diskID)
• trashWebName(web => $web | disk => $diskID) -> $trashWebName
• entityEncode( $text, $extra ) -> $text
• entityDecode( $text ) -> $text
• urlEncode( $text ) -> $text
• urlDecode( $text ) -> $text

getExternalResource( $url, @headers ) -> $response

Optional headers may be supplied of form 'name1', 'value1', 'name2', 'value2'. Do not add a User-Agent header, it will be added.

isValidWebName( $name, $templateWeb ) -> $boolean

Check for a valid web name.

• $name - web name
• $templateWeb - flag, optional. If true, then template web names (starting with _) are considered valid, otherwise only user web names are valid.

If $TWiki::cfg{EnableHierarchicalWebs} is off, it will also return false when a nested web name is passed to it.

Since: TWiki::Plugins::VERSION 1.4

isValidTopicName( $name ) -> $boolean

Check for a valid topic name. Names considerd valid for autolinking are WikiWords (such as 'SanFrancisco') and acronym (such as 'SWMBO').

• $name - topic name

Since: TWiki::Plugins::VERSION 1.4

• $meta - topic meta-data to use while expanding, can be undef (Since TWiki::Plugins::VERSION 1.4)
• $textRef - reference to unexpanded topic text, can be undef (Since TWiki::Plugins::VERSION 1.4)

writeLog( $action, $extra, $web, $topic, $user )

Write the log for an event to the logfile.

• $action - name of the event, such as 'blacklist'.
• $extra - arbitrary extra information to add to the event.
• $web - web name, optional. Base web is taken if empty. Ignored if web is specified in $topic.
• $topic - topic name, optional. Can be Topic or Web.Topic. Base topic is taken if empty.
• $user - WikiName of user, optional. Name of logged-in user is taken if not specified.

Since: TWiki::Plugins::VERSION 1.4

Example: Calling TWiki::Func::writeLog( 'blacklist', 'Magic number is missing' ) will add a log entry like this:

| 2011-01-19 - 01:13 | guest | blacklist | TWiki.TWikiRegistration | Magic number is missing | 1.2.3.4 |

Note: Older plugins that use $TWiki::cfg{LogFileName} or call the internal TWiki function directly should be fixed to use writeLog.

To maintain compatibility with older TWiki releases, you can write conditional code as follows:

  if( defined &TWiki::Func::writeLog ) {
    # use writeLog
    TWiki::Func::writeLog( $web, $topic, 'myevent', $extra );
  } else {
    # deprecated code if plugin is used in older TWiki releases
    $TWiki::Plugins::VERSION > 1.1
      ? $TWiki::Plugins::SESSION->writeLog( 'myevent', "$web.$topic", $extra )
      : TWiki::Store::writeLog( 'myevent', "$web.$topic", $extra );
  }

• afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error, $meta)
• beforeAttachmentSaveHandler(\%attrHash, $topic, $web, $meta)

TWiki-5.1 (Istanbul Release)

EmptyPlugin.pm

• Callback function registered by registerTagHandler has two new parameters $meta and $textRef

Func.pm

• afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error, $meta) -- added $meta
• beforeAttachmentSaveHandler(\%attrHash, $topic, $web, $meta) = added =$meta
• writeLog( $action, $extra, $web, $topic, $user )

Special Handlers

• casesensitive - false to ignore case (default true)

Plugin-specific File Handling

sanitizeAttachmentName($fname) -> ($fileName, $origName)

writeHeader( )

Note: In TWiki versions earlier than TWiki::Plugins::VERSION 1.3, this function used to have $query and $contentLength parameters. Both were marked "you should not pass this parameter".

addToHEAD( $id, $header, $requires )

• requires optional, comma-separated list of id's of other head blocks this one depends on.

buildWikiWord( $text ) -> $text

Converts arbitrary text to a WikiWord.

• $pre - Arbitrary Text

Since: TWiki::Plugins::VERSION 1.3 (18 Jan 2010)

TWiki API History

TWiki-2001-09-01 (Athens Release)

EmptyPlugin.pm

• commonTagsHandler($text, $topic, $web)
• endRenderingHandler($text)
• outsidePREHandler($text)
• insidePREHandler($text)
• startRenderingHandler($text, $web)

Func.pm

• checkAccessPermission($type, $login, $topicText, $topicName, $webName) -> $boolean
• expandCommonVariables($text, $topic, $web) -> $text
• extractNameValuePair($attrs, $name) -> $value
• formatGmTime($time) -> $text
• getCgiQuery() -> $query
• getDataDir() -> $dir
• getDefaultUserName() -> $loginName
• getMainWebname() -> $name
• getOopsUrl($web, $topic, $template, @theParams) -> $url
• getPreferencesFlag($key) -> $boolean
• getPreferencesValue($key, $web) -> $value
• getPublicWebList() -> @webs
• getPubDir() -> $dir
• getPubUrlPath() -> $path
• getRevisionInfo($webName, $topic, $rev, $attachment) -> ($date, $user, $rev, $comment)
• getScriptUrl($web, $topic, $script) -> $url
• getScriptUrlPath() -> $path
• getSessionValue($key) -> $value
• getSkin() -> $skin
• getTopicList($web) -> @topics
• getTwikiWebname() -> $name
• getUrlHost() -> $host
• getViewUrl($web, $topic) -> $url
• getWikiName() -> $wikiName
• getWikiUserName($text) -> $wikiName
• getWikiToolName() -> $name
• internalLink($preamble, $web, $topic, $linkText, $anchor, $createLink) -> $text
• isGuest() -> $boolean
• permissionsSet($web) -> $boolean
• readFile($filename) -> $text
• readTemplate($name, $skin) -> $text
• readTopic($webName, $topic) -> ($meta, $text)
• redirectCgiQuery($query, $url)
• renderText($text, $web) -> $text
• saveFile($filename, $text)
• setSessionValue($key, $value)
• topicExists($web, $topic) -> $boolean
• userToWikiName($user, $dontAddWeb) -> $wikiName
• webExists($web) -> $boolean
• wikiToUserName($wiki) -> $loginName
• writeDebug($text)
• writeHeader()
• writeWarning($text)

TWiki-2003-02-01 (Beijing Release)

EmptyPlugin.pm

• afterEditHandler($text, $topic, $web)
• beforeEditHandler($text, $topic, $web)
• beforeSaveHandler($text, $topic, $web)
• initializeUserHandler($loginName, $url, $pathInfo)
• redirectCgiQueryHandler($query, $url)
• registrationHandler($web, $wikiName, $loginName)
• writeHeaderHandler($query)

Func.pm

• checkTopicEditLock($web, $topic) ->($oopsUrl, $loginName, $unlockTime)
• readTopicText($web, $topic, $rev, $ignorePermissions) -> $text
• saveTopicText($web, $topic, $text, $ignorePermissions, $dontNotify) -> $oopsUrl
• setTopicEditLock($web, $topic, $lock) -> $oopsUrl

TWiki-2004-09-02 (Cairo Release)

EmptyPlugin.pm

• afterCommonTagsHandler($text, $topic, $web)
• afterSaveHandler($text, $topic, $web, $error)
• beforeCommonTagsHandler($text, $topic, $web)
• earlyInitPlugin()

Func.pm

• afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error)
• beforeAttachmentSaveHandler(\%attrHash, $topic, $web)
• checkDependencies($moduleName, $dependenciesRef) -> $error
• extractParameters($attr) -> %params
• formatTime($time, $format, $timezone) -> $text
• getPluginPreferencesFlag($key) -> $boolean
• getPluginPreferencesValue($key) -> $value
• getRegularExpression($regexName) -> $pattern

TWiki-4.0.0 (Dakar Release)

EmptyPlugin.pm

• mergeHandler($diff, $old, $new, \%info) -> $text
• modifyHeaderHandler(\%headers, $query)
• postRenderingHandler($text)
• preRenderingHandler($text, \%map)
• renderFormFieldForEditHandler($name, $type, $size, $value, $attributes, $possibleValues) -> $html
• renderWikiWordHandler($linkText, $hasExplicitLinkLabel, $web, $topic) -> $linkText

• endRenderingHandler($text)
• startRenderingHandler($text, $web)

Func.pm

• addToHEAD($id, $header)
• attachmentExists($web, $topic, $attachment) -> $boolean
• clearSessionValue($key) -> $boolean
• checkDependencies($moduleName, $dependenciesRef) -> $error
• createWeb($newWeb, $baseWeb, $opts)
• expandTemplate($def ) -> $string
• expandVariablesOnTopicCreation($text) -> $text
• getContext() -> \%hash
• getListOfWebs($filter) -> @webs
• getScriptUrl($web, $topic, $script, @params) -> $url
• getRevisionAtTime($web, $topic, $time) -> $rev
• getWorkArea($pluginName) -> $directorypath
• isValidWikiWord($text) -> $boolean
• loadTemplate($name, $skin, $web) -> $text
• moveAttachment($web, $topic, $attachment, $newWeb, $newTopic, $newAttachment)
• moveTopic($web, $topic, $newWeb, $newTopic)
• moveWeb($oldName, $newName)
• normalizeWebTopicName($web, $topic) ->($web, $topic)
• readAttachment($web, $topic, $name, $rev) -> $data
• registerRESTHandler($alias, \&fn,)
• registerTagHandler($var, \&fn, $syntax)
• saveAttachment($web, $topic, $attachment, $opts)
• saveTopic($web, $topic, $meta, $text, $options) -> $error
• searchInWebContent($searchString, $web, \@topics, \%options) -> \%map
• sendEmail($text, $retries) -> $error
• wikiToEmail($wikiName) -> $email
• writeHeader($query, $contentLength)

• checkDependencies($moduleName, $dependenciesRef) -> $error
• formatGmTime($time, $format) -> $text
• getDataDir() -> $dir
• getOopsUrl( $web, $topic, $template, @params ) -> $url
• getPubDir() -> $dir
• getPublicWebList() -> @webs
• getScriptUrlPath() -> $path

TWiki-4.0.1 (Dakar Patch Release)

EmptyPlugin.pm

• afterSaveHandler($text, $topic, $web, $error, $meta)
• beforeSaveHandler($text, $topic, $web, $meta)

Func.pm

TWiki-4.1 (Edinburgh Release)

EmptyPlugin.pm

• afterRenameHandler($oldWeb, $oldTopic, $oldAttachment, $newWeb, $newTopic, $newAttachment)

Func.pm

TWiki-4.2 (Freetown Release)

EmptyPlugin.pm

• afterCommonTagsHandler($text, $topic, $web, $meta)
• beforeCommonTagsHandler($text, $topic, $web, $meta)
• commonTagsHandler($text, $topic, $web, $included, $meta)

Func.pm

• decodeFormatTokens($str) -> $unencodedString
• eachChangeSince($web, $time) -> $iterator
• eachGroup() -> $iterator
• eachGroupMember($group) -> $iterator
• eachMembership($wikiname) -> $iterator
• eachUser() -> $iterator
• emailToWikiNames($email, $dontAddWeb) -> @wikiNames
• expandCommonVariables($text, $topic, $web, $meta) -> $text
• getCanonicalUserID( $user ) -> $cUID
• getExternalResource($url) -> $response
• getSessionKeys() -> @keys
• isAnAdmin($login) -> $boolean
• isGroup($group) -> $boolean
• isGroupMember($group, $login) -> $boolean
• isTrue($value, $default) -> $boolean
• popTopicContext()
• pushTopicContext($web, $topic)
• sanitizeAttachmentName($fname) -> ($fileName, $origName)
• setPreferencesValue($name, $val)
• spaceOutWikiWord($word, $sep) -> $text
• wikiNameToEmails($wikiname) -> @emails
• permissionsSet($web) -> $boolean
• getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url

TWiki-4.3 (Georgetown Release)

EmptyPlugin.pm

Func.pm

TWiki-5.0 (Helsinki Release)

EmptyPlugin.pm

Func.pm

• buildWikiWord( $text ) -> $text

• $user can be a login, wikiname or web.wikiname

wikiToUserName( $id ) -> $loginName

• $id - Wiki name, e.g. 'Main.JohnDoe' or 'JohnDoe'. Since TWiki 4.2.1, $id may also be a login name. This will normally be transparent, but should be borne in mind if you have login names that are also legal wiki names.

• $loginName - Login name, e.g. 'jdoe'. Since TWiki 4.2.1 this may also be a wiki name. This will normally be transparent, but may be relevant if you have login names that are also valid wiki names.

wikinameToEmails( $user ) -> @emails

• $user - wikiname of user to look up

isAnAdmin( $id ) -> $boolean

• $id can be either a login name or a WikiName

isGroupMember( $group, $id ) -> $boolean

• $id can be a login name or a WikiName

eachMembership($id) -> $iterator

• $id - WikiName or login name of the user. If $id is undef, defaults to the currently logged-in user.

checkAccessPermission( $type, $id, $text, $topic, $web, $meta ) -> $boolean

• $id - WikiName of remote user, required, e.g. "PeterThoeny". From TWiki 4.2.1, $id may also be a login name. If $id is '', 0 or undef then access is always permitted.

• $wikiname - wiki name of the user

Since TWiki 4.2.1, $wikiName may also be a login name.

Notes on use of $TWiki::Plugins::VERSION (from 1.2 forwards):

• If the major version (e.g. 1.) is the same then any plugin coded to use any earlier revision of the 1. API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to require plugins to be recoded.
• If the minor version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, deprecation of functions in the interface trigger a minor version increment. Note that deprecated functions are not removed, they are merely frozen, and plugin authors are recommended to stop using them.
• Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.
• TWiki::Plugins::VERSION also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of TWiki::Plugins::VERSION it relates to.

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

getPubUrlPath( ) -> $path

getExternalResource( $url ) -> $response

Note that the $url may have an optional user and password, as specified by the relevant RFC. Any proxy set in configure is honoured.

The $response is an object that is known to implement the following subset of the methods of LWP::Response. It may in fact be an LWP::Response object, but it may also not be if LWP is not available, so callers may only assume the following subset of methods is available:

Note that if LWP is not available, this function:

1. can only really be trusted for HTTP/1.0 urls. If HTTP/1.1 or another protocol is required, you are strongly recommended to require LWP.
2. Will not parse multipart content

In the event of the server returning an error, then is_error() will return true, code() will return a valid HTTP status code as specified in RFC 2616 and RFC 2518, and message() will return the message that was received from the server. In the event of a client-side error (e.g. an unparseable URL) then is_error() will return true and message() will return an explanatory message. code() will return 400 (BAD REQUEST).

my $response = TWiki::Func::getExternalResource($url);
if (!$response->is_error() && $response->isa('HTTP::Response')) {
    ... other methods of HTTP::Response may be called
} else {
    ... only the methods listed above may be called
}

getSessionKeys() -> @keys

Session keys are stored and retrieved using setSessionValue and getSessionValue.

Since: TWiki::Plugins::VERSION 1.2

pushTopicContext($web, $topic)

• $web - new web
• $topic - new topic

It is the duty of the caller to restore the original context by calling popTopicContext.

Note that this call does not re-initialise plugins, so if you have used global variables to remember the web and topic in initPlugin, then those values will be unchanged.

Since: TWiki::Plugins::VERSION 1.2

popTopicContext()

Returns the TWiki context to the state it was in before the pushTopicContext was called.

Since: TWiki::Plugins::VERSION 1.2

setPreferencesValue($name, $val)

Set the preferences value so that future calls to getPreferencesValue will return this value, and %$name% will expand to the preference when used in future variable expansions.

The preference only persists for the rest of this request. Finalised preferences cannot be redefined using this function.

Returns 1 if the preference was defined, and 0 otherwise.

getCanonicalUserID( $user ) -> $cUID

If $user is undefined Get the cUID of logged in user, and will generally be 'BaseUserMapping_666'

• $user can be a cUID, login, wikiname or web.wikiname

Return: $cUID an internal unique and transportable escaped identifier for registered users (they can be autogenerated for an authenticated but unregistered user)

getWikiName( $user ) -> $wikiName

return the WikiName of the specified user if $user is undefined Get Wiki name of logged in user

• $user can be a cUID, login, wikiname or web.wikiname

getWikiUserName( $user ) -> $wikiName

return the userWeb.WikiName of the specified user if $user is undefined Get Wiki name of logged in user

• $user can be a cUID, login, wikiname or web.wikiname

Note that it is possible for several login names to map to the same wikiname. This function will only return the first login name that maps to the wikiname.

returns undef if the WikiName is not found.

emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames

• $email - email address to look up
• $dontAddWeb - Do not add web prefix if "1"

Since: TWiki::Plugins::VERSION 1.2

wikiNameToEmails( $wikiname ) -> @emails

• $wikiname - wikiname of user to look up

Since: TWiki::Plugins::VERSION 1.2

isAnAdmin( $login ) -> $boolean

• $login can be either a login, or a CUID

isGroupMember( $group, $login ) -> $boolean

Find out if $login is in the named group. e.g.

if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) {
    ...
}

• $login can be a login name, or a cUID, or WikiName

Since: TWiki::Plugins::VERSION 1.2

eachUser() -> $iterator

Use it as follows:

    my $iterator = TWiki::Func::eachUser();
    while ($it->hasNext()) {
        my $user = $it->next();
        # $user is a wikiname
    }

WARNING on large sites, this could be a long list!

Since: TWiki::Plugins::VERSION 1.2

eachMembership($wikiname) -> $iterator

Since: TWiki::Plugins::VERSION 1.2

eachGroup() -> $iterator

Use it as follows:

    my $iterator = TWiki::Func::eachGroup();
    while ($it->hasNext()) {
        my $group = $it->next();
        # $group is a group name e.g. TWikiAdminGroup
    }

WARNING on large sites, this could be a long list!

Since: TWiki::Plugins::VERSION 1.2

isGroup( $group ) -> $boolean

Checks if $group is the name of a group known to TWiki.

eachGroupMember($group) -> $iterator

Use it as follows:

    my $iterator = TWiki::Func::eachGroupMember('RadioheadGroup');
    while ($it->hasNext()) {
        my $user = $it->next();
        # $user is a wiki name e.g. 'TomYorke', 'PhilSelway'
    }

WARNING on large sites, this could be a long list!

Since: TWiki::Plugins::VERSION 1.2

eachChangeSince($web, $time) -> $iterator

Get an iterator over the list of all the changes in the given web between $time and now. $time is a time in seconds since 1st Jan 1970, and is not guaranteed to return any changes that occurred before (now - {Store}{RememberChangesFor}). {Store}{RememberChangesFor}) is a setting in configure. Changes are returned in most-recent-first order.

Use it as follows:

    my $iterator = TWiki::Func::eachChangeSince(
        $web, time() - 7 * 24 * 60 * 60); # the last 7 days
    while ($it->hasNext()) {
        my $change = $it->next();
        # $change is a perl hash that contains the following fields:
        # topic => topic name
        # user => wikiname - wikiname of user who made the change
        # time => time of the change
        # revision => revision number *after* the change
        # more => more info about the change (e.g. 'minor')
    }

• $lock 1 to lease the topic, 0 to clear an existing lease

• $query - CGI query object. If not given, the default CGI query will be used (optional, in most cases you should not pass this parameter)
• $contentLength - Length of content (optional, in most cases you should not pass this parameter)

expandCommonVariables( $text, $topic, $web, $meta ) -> $text

• $meta - topic meta-data to use while expanding (Since TWiki::Plugins::VERSION 1.2)

decodeFormatTokens($str) -> $unencodedString

TWiki has an informal standard set of tokens used in format parameters that are used to block evaluation of paramater strings. For example, if you were to write

%MYTAG{format="%WURBLE%"}%

then %WURBLE would be expanded before %MYTAG is evaluated. To avoid this TWiki uses escapes in the format string. For example:

%MYTAG{format="$percntWURBLE$percnt"}%

This lets you enter arbitrary strings into parameters without worrying that TWiki will expand them before your plugin gets a chance to deal with them properly. Once you have processed your tag, you will want to expand these tokens to their proper value. That's what this function does.

Note thath $quot, $percnt and $dollar all work *even if they are followed by alphanumeric characters*. You have been warned!

Since: TWiki::Plugins::VERSION 1.2

StaticMethod sanitizeAttachmentName ($fname) -> ($fileName,$origName)

Given a file namer, sanitise it according to the rules for transforming attachment names. Returns the sanitised name together with the basename before sanitisation.

Sanitation includes filtering illegal characters and mapping client file names to legal server names.

Since: TWiki::Plugins::VERSION 1.2

spaceOutWikiWord( $word, $sep ) -> $text

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.

Since: TWiki::Plugins::VERSION 1.2

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.

Since: $TWiki::Plugins::VERSION 1.2

getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url

Compose fully qualified 'oops' dialog URL

• $web - Web name, e.g. 'Main'. The current web is taken if empty
• $topic - Topic name, e.g. 'WebNotify'
• $template - Oops template name, e.g. 'oopsmistake'. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
• $param1 ... $param4 - Parameter values for %PARAM1% ... %PARAMn% variables in template, optional

DEPRECATED since 1.1, the recommended approach is to throw an oops exception.

   use Error qw( :try );

   throw TWiki::OopsException(
      'toestuckerror',
      web => $web,
      topic => $topic,
      params => [ 'I got my toe stuck' ]);

If this is not possible (e.g. in a REST handler that does not trap the exception) then you can use getScriptUrl instead:

   my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops',
            template => 'oopstoestuckerror',
            param1 => 'I got my toe stuck');
   TWiki::Func::redirectCgiQuery( undef, $url );
   return 0;

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

permissionsSet( $web ) -> $boolean

Test if any access restrictions are set for this web, ignoring settings on individual pages

• $web - Web name, required, e.g. 'Sandbox'

Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

DEPRECATED since 1.2 - use getPreferencesValue instead to determine what permissions are set on the web, for example:

foreach my $type qw( ALLOW DENY ) {
    foreach my $action qw( CHANGE VIEW ) {
        my $pref = $type . 'WEB' . $action;
        my $val = getPreferencesValue( $pref, $web ) || '';
        if( $val =~ /\S/ ) {
            print "$pref is set to $val on $web\n";
        }
    }
}

checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -> $boolean

• $type - Access type, required, e.g. 'VIEW', 'CHANGE'.
• $wikiName - WikiName of remote user, required, e.g. "PeterThoeny". If $wikiName is '', 0 or undef then access is always permitted.
• $text - Topic text, optional. If 'perl false' (undef, 0 or ''), topic $web.$topic is consulted. $text may optionally contain embedded %META:PREFERENCE tags. Provide this parameter if:
  1. You are setting different access controls in the text to those defined in the stored topic,
  2. You already have the topic text in hand, and want to help TWiki avoid having to read it again,
  3. You are providing a $meta parameter.

• $meta - Meta-data object, as returned by readTopic. Optional. If undef, but $text is defined, then access controls will be parsed from $text. If defined, then metadata embedded in $text will be ignored. This parameter is always ignored if $text is undefined. Settings in $meta override Set settings in $text.

Tip if you want, you can use this method to check your own access control types. For example, if you:

• Set ALLOWTOPICSPIN = IncyWincy