Difference: TWikiFuncDotPm (10 vs. 11)

Environment

getSkin( ) -> $skin

Get the skin path, set by the SKIN and COVER preferences variables or the skin and cover CGI parameters

getUrlHost( ) -> $host

Get protocol, domain and optional port of script URL

getScriptUrl( $web, $topic, $script, ... ) -> $url

Compose fully qualified URL

getViewUrl( $web, $topic ) -> $url

Compose fully qualified view URL

getPubUrlPath( ) -> $path

Get pub URL path

getExternalResource( $url ) -> $response

Get whatever is at the other end of a URL (using an HTTP GET request). Will

getCgiQuery( ) -> $query

Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set

getSessionKeys() -> @keys

getSessionValue( $key ) -> $value

Get a session value from the client session module

setSessionValue( $key, $value ) -> $boolean

Set a session value.

clearSessionValue( $key ) -> $boolean

Clear a session value that was set using setSessionValue.

getContext() -> \%hash

Get a hash of context identifiers representing the currently active

pushTopicContext($web, $topic)

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

popTopicContext()

Returns the TWiki context to the state it was in before the

Preferences

getPreferencesValue( $key, $web ) -> $value

Get a preferences value from TWiki or from a Plugin

getPluginPreferencesValue( $key ) -> $value

Get a preferences value from your Plugin

getPreferencesFlag( $key, $web ) -> $value

Get a preferences flag from TWiki or from a Plugin

getPluginPreferencesFlag( $key ) -> $boolean

Get a preferences flag from your Plugin

setPreferencesValue($name, $val)

Set the preferences value so that future calls to getPreferencesValue will

getWikiToolName( ) -> $name

Get toolname as defined in TWiki.cfg

getMainWebname( ) -> $name

Get name of Main web as defined in TWiki.cfg

getTwikiWebname( ) -> $name

Get name of TWiki documentation web as defined in TWiki.cfg

User Handling and Access Control

getDefaultUserName( ) -> $loginName

getCanonicalUserID( $user ) -> $cUID

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

getWikiName( $user ) -> $wikiName

return the WikiName of the specified user

getWikiUserName( $user ) -> $wikiName

return the userWeb.WikiName of the specified user

wikiToUserName( $id ) -> $loginName

• $id - Wiki name, e.g. 'Main.JohnDoe' or 'JohnDoe'.

userToWikiName( $loginName, $dontAddWeb ) -> $wikiName

• $loginName - Login name, e.g. 'jdoe'. Since TWiki 4.2.1 this may

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

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

wikinameToEmails( $user ) -> @emails

• $user - wikiname of user to look up

isGuest( ) -> $boolean

Test if logged in user is a guest (TWikiGuest)

isAnAdmin( $id ) -> $boolean

Find out if the user is an admin or not. If the user is not given,

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

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

eachUser() -> $iterator

eachMembership($id) -> $iterator

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

eachGroup() -> $iterator

isGroup( $group ) -> $boolean

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

eachGroupMember($group) -> $iterator

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

Check access permission for a topic based on the

Webs, Topics and Attachments

getListOfWebs( $filter ) -> @webs

• $filter - spec of web types to recover

webExists( $web ) -> $boolean

Test if web exists

createWeb( $newWeb, $baseWeb, $opts )

• $newWeb is the name of the new web.

moveWeb( $oldName, $newName )

Move (rename) a web.

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

Get an iterator over the list of all the changes in the given web between

getTopicList( $web ) -> @topics

Get list of all topics in a web

topicExists( $web, $topic ) -> $boolean

Test if topic exists

checkTopicEditLock( $web, $topic, $script ) -> ( $oopsUrl, $loginName, $unlockTime )

Check if a lease has been taken by some other user.

setTopicEditLock( $web, $topic, $lock )

• $web Web name, e.g. "Main", or empty

saveTopic( $web, $topic, $meta, $text, $options ) -> $error

• $web - web for the topic

saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $oopsUrl

Save topic text, typically obtained by readTopicText(). Topic data usually includes meta data; the file attachment meta data is replaced by the meta data from the topic file if it exists.

moveTopic( $web, $topic, $newWeb, $newTopic )

• $web source web - required

getRevisionInfo($web, $topic, $rev, $attachment ) -> ( $date, $user, $rev, $comment )

Get revision info of a topic or attachment

getRevisionAtTime( $web, $topic, $time ) -> $rev

Get the revision number of a topic at a specific time.

readTopic( $web, $topic, $rev ) -> ( $meta, $text )

Read topic text and meta data, regardless of access permissions.

readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $text

Read topic text, including meta data

attachmentExists( $web, $topic, $attachment ) -> $boolean

Test if attachment exists

readAttachment( $web, $topic, $name, $rev ) -> $data

• $web - web for topic

saveAttachment( $web, $topic, $attachment, $opts )

• $web - web for topic

moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )

• $web source web - required

Assembling Pages

readTemplate( $name, $skin ) -> $text

Read a template or skin. Embedded template directives get expanded

loadTemplate ( $name, $skin, $web ) -> $text

• $name - template file name

expandTemplate( $def ) -> $string

Do a , only expanding the template (not expanding any variables other than %TMPL)

writeHeader( )

Print a basic content-type HTML header for text/html to standard out. No return value.

redirectCgiQuery( $query, $url, $passthru )

Redirect to URL

addToHEAD( $id, $header, $requires )

Adds $header to the HTML header (the tag).

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

Expand all common %VARIABLES%

renderText( $text, $web ) -> $text

Render text from TWiki markup into XHTML as defined in TWiki.TextFormattingRules

internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text

Render topic name and link label into an XHTML link. Normally you do not need to call this funtion, it is called internally by renderText()

E-mail

sendEmail ( $text, $retries ) -> $error

• $text - text of the mail, including MIME headers

wikiToEmail( $wikiName ) -> $email

• $wikiname - wiki name of the user

Creating New Topics

expandVariablesOnTopicCreation ( $text ) -> $text

Expand the limited set of variables that are always expanded during topic creation

registerTagHandler( $var, \&fn, $syntax )

Should only be called from initPlugin.

• registered tag handlers cannot return another tag as their only result (e.g. return '%SERVERTIME%';). It won't work.

registerRESTHandler( $alias, \&fn, )

Should only be called from initPlugin.

decodeFormatTokens($str) -> $unencodedString

TWiki has an informal standard set of tokens used in format

Searching

searchInWebContent($searchString, $web, \@topics, \%options ) -> \%map

Search for a string in the content of a web. The search is over all content, including meta-data. Meta-data matches will be returned as formatted lines within the topic content (meta-data matches are returned as lines of the format %META:\w+{.*}%)

• \%option - reference to an options hash

• type - if regex will perform a egrep-syntax RE search (default '')

• files_without_match - true to return files only (default false). If files_without_match is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).

The return value is a reference to a hash which maps each matching topic

getWorkArea( $pluginName ) -> $directorypath

Gets a private directory for Plugin use. The Plugin is entirely responsible

readFile( $filename ) -> $text

Read file, low level. Used for Plugin workarea.

saveFile( $filename, $text )

Save file, low level. Used for Plugin workarea.

General Utilities

getRegularExpression( $name ) -> $expr

Retrieves a TWiki predefined regular expression or character class.

normalizeWebTopicName($web, $topic) -> ($web, $topic)

Parse a web and topic name, supplying defaults as appropriate.

buildWikiWord( $text ) -> $text

Converts arbitrary text to a WikiWord.

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

Spaces out a wiki word by inserting a string (default: one space) between each word component.

writeWarning( $text )

Log Warning that may require admin intervention to data/warning.txt

writeDebug( $text )

Log debug message to data/debug.txt

formatTime( $time, $format, $timezone ) -> $text

Format the time in seconds into the desired time string

isTrue( $value, $default ) -> $boolean

Returns 1 if $value is true, and 0 otherwise. "true" means set to

isValidWikiWord ( $text ) -> $boolean

Check for a valid WikiWord or WikiName

extractParameters($attr ) -> %params

Extract all parameters from a variable string and returns a hash of parameters

extractNameValuePair( $attr, $name ) -> $value

Extract a named or unnamed value from a variable parameter string

Deprecated functions

From time-to-time, the TWiki developers will add new functions to the interface (either to TWikiFuncDotPm, or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable. When this happens, the deprecated functions will be supported in the interface for at least one more TWiki release, and probably longer, though this cannot be guaranteed.

getScriptUrlPath( ) -> $path

Get script URL path

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

Compose fully qualified 'oops' dialog URL

permissionsSet( $web ) -> $boolean

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

getPublicWebList( ) -> @webs

DEPRECATED since 1.1 - use getListOfWebs instead.

formatGmTime( $time, $format ) -> $text

DEPRECATED since 1.1 - use formatTime instead.

getDataDir( ) -> $dir

DEPRECATED since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead

getPubDir( ) -> $dir

DEPRECATED since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead

checkDependencies( $moduleName, $dependenciesRef ) -> $error

DEPRECATED since 1.1 - use TWiki:Plugins.BuildContrib and define DEPENDENCIES that can be statically

TWiki API History

TWiki-2001-09-01 (Athens Release)