Difference: TWikiFuncDotPm (10 vs. 11)

Revision 112011-05-04 - TWikiContributor

Line: 50 to 52
 
On this page:
Added:
>
>
 

Environment

Added:
>
>
 

getSkin( ) -> $skin

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

Line: 62 to 66
 Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
Added:
>
>
 

getUrlHost( ) -> $host

Get protocol, domain and optional port of script URL

Line: 71 to 76
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

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

Compose fully qualified URL

Line: 84 to 90
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

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

Compose fully qualified view URL

Line: 94 to 101
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

getPubUrlPath( ) -> $path

Get pub URL path

Line: 103 to 111
 Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
Added:
>
>
 

getExternalResource( $url ) -> $response

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

Line: 151 to 160
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

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

Line: 160 to 170
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

getSessionKeys() -> @keys

Get a list of all the names of session variables. The list is unsorted.
Line: 169 to 180
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

getSessionValue( $key ) -> $value

Get a session value from the client session module

Line: 178 to 190
 Since: TWiki::Plugins::VERSION 1.000 (27 Feb 200)
Added:
>
>
 

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

Set a session value.

Line: 188 to 201
 Since: TWiki::Plugins::VERSION 1.000 (17 Aug 2001)
Added:
>
>
 

clearSessionValue( $key ) -> $boolean

Clear a session value that was set using setSessionValue.

Line: 198 to 212
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

getContext() -> \%hash

Get a hash of context identifiers representing the currently active

Line: 244 to 259
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

pushTopicContext($web, $topic)

  • $web - new web
  • $topic - new topic
Line: 263 to 279
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

popTopicContext()

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

Line: 271 to 288
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

Preferences

Added:
>
>
 

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

Get a preferences value from TWiki or from a Plugin

Line: 296 to 315
 preferences set in the plugin topic will be ignored.
Added:
>
>
 

getPluginPreferencesValue( $key ) -> $value

Get a preferences value from your Plugin

Line: 310 to 330
 preferences set in the plugin topic will be ignored.
Added:
>
>
 

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

Get a preferences flag from TWiki or from a Plugin

Line: 328 to 349
 preferences set in the plugin topic will be ignored.
Added:
>
>
 

getPluginPreferencesFlag( $key ) -> $boolean

Get a preferences flag from your Plugin

Line: 342 to 364
 preferences set in the plugin topic will be ignored.
Added:
>
>
 

setPreferencesValue($name, $val)

Set the preferences value so that future calls to getPreferencesValue will

Line: 354 to 377
 Returns 1 if the preference was defined, and 0 otherwise.
Added:
>
>
 

getWikiToolName( ) -> $name

Get toolname as defined in TWiki.cfg

Line: 363 to 387
 Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
Added:
>
>
 

getMainWebname( ) -> $name

Get name of Main web as defined in TWiki.cfg

Line: 372 to 397
 Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
Added:
>
>
 

getTwikiWebname( ) -> $name

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

Line: 381 to 407
 Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
Added:
>
>
 

User Handling and Access Control

Added:
>
>
 

getDefaultUserName( ) -> $loginName

Get default user name as defined in the configuration as DefaultUserLogin
Line: 390 to 420
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

getCanonicalUserID( $user ) -> $cUID

  • $user can be a login, wikiname or web.wikiname
Return the cUID of the specified user. A cUID is a unique identifier which
Line: 408 to 439
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

getWikiName( $user ) -> $wikiName

return the WikiName of the specified user

Line: 420 to 452
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

getWikiUserName( $user ) -> $wikiName

return the userWeb.WikiName of the specified user

Line: 432 to 465
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

wikiToUserName( $id ) -> $loginName

Translate a Wiki name to a login name.
  • $id - Wiki name, e.g. 'Main.JohnDoe' or 'JohnDoe'.
Line: 451 to 485
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

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

Translate a login name to a Wiki name
  • $loginName - Login name, e.g. 'jdoe'. Since TWiki 4.2.1 this may
Line: 465 to 500
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

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

  • $email - email address to look up
  • $dontAddWeb - Do not add web prefix if "1"
Line: 475 to 511
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

wikinameToEmails( $user ) -> @emails

  • $user - wikiname of user to look up
Returns the registered email addresses of the named user. If $user is
Line: 485 to 522
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

isGuest( ) -> $boolean

Test if logged in user is a guest (TWikiGuest)

Line: 492 to 530
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

isAnAdmin( $id ) -> $boolean

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

Line: 501 to 540
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

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

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

Line: 516 to 556
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

eachUser() -> $iterator

Get an iterator over the list of all the registered users not including groups. The iterator will return each wiki name in turn (e.g. 'FredBloggs').
Line: 534 to 575
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

eachMembership($id) -> $iterator

  • $id - WikiName or login name of the user. If $id is undef, defaults to the currently logged-in user.
Line: 542 to 584
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

eachGroup() -> $iterator

Get an iterator over all groups.
Line: 559 to 602
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

isGroup( $group ) -> $boolean

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

Added:
>
>
 

eachGroupMember($group) -> $iterator

Get an iterator over all the members of the named group. Returns undef if $group is not a valid group.
Line: 582 to 627
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

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

Check access permission for a topic based on the

Line: 617 to 663
 Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
Added:
>
>
 

Webs, Topics and Attachments

Added:
>
>
 

getListOfWebs( $filter ) -> @webs

  • $filter - spec of web types to recover
Line: 640 to 688
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

webExists( $web ) -> $boolean

Test if web exists

Line: 648 to 697
 Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
Added:
>
>
 

createWeb( $newWeb, $baseWeb, $opts )

  • $newWeb is the name of the new web.
Line: 675 to 725
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

moveWeb( $oldName, $newName )

Move (rename) a web.

Line: 704 to 755
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

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

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

Line: 729 to 781
 
Added:
>
>
 

getTopicList( $web ) -> @topics

Get list of all topics in a web

Line: 738 to 791
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

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

Test if topic exists

Line: 751 to 805
 Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
Added:
>
>
 

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

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

Line: 762 to 817
 Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
Added:
>
>
 

setTopicEditLock( $web, $topic, $lock )

  • $web Web name, e.g. "Main", or empty
Line: 779 to 835
 Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
Added:
>
>
 

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

  • $web - web for the topic
Line: 805 to 862
 appropriate.
Added:
>
>
 

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.

Line: 835 to 893
 
Added:
>
>
 

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

  • $web source web - required
Line: 868 to 927
 
Added:
>
>
 

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

Get revision info of a topic or attachment

Line: 888 to 948
 Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
Added:
>
>
 

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

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

Line: 900 to 961
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

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

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

Line: 919 to 981
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

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

Read topic text, including meta data

Line: 933 to 996
 Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
Added:
>
>
 

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

Test if attachment exists

Line: 944 to 1008
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

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

  • $web - web for topic
Line: 975 to 1040
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

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

  • $web - web for topic
Line: 1009 to 1075
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

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

  • $web source web - required
Line: 1046 to 1113
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

Assembling Pages

Added:
>
>
 

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

Read a template or skin. Embedded template directives get expanded

Line: 1059 to 1128
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

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

  • $name - template file name
Line: 1076 to 1146
 If template text is found, extracts include statements and fully expands them.
Added:
>
>
 

expandTemplate( $def ) -> $string

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

Line: 1088 to 1159
 file. See the documentation on TWiki templates for more information.
Added:
>
>
 

writeHeader( )

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

Line: 1097 to 1169
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

redirectCgiQuery( $query, $url, $passthru )

Redirect to URL

Line: 1132 to 1205
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

addToHEAD( $id, $header, $requires )

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

Line: 1152 to 1226
 
Added:
>
>
 

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

Expand all common %VARIABLES%

Line: 1166 to 1241
 See also: expandVariablesOnTopicCreation
Added:
>
>
 

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

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

Line: 1176 to 1252
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

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()

Line: 1190 to 1267
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

E-mail

Added:
>
>
 

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

  • $text - text of the mail, including MIME headers
Line: 1218 to 1297
 Since: TWiki::Plugins::VERSION 1.1
Added:
>
>
 

wikiToEmail( $wikiName ) -> $email

  • $wikiname - wiki name of the user
Line: 1233 to 1313
 Since TWiki 4.2.1, $wikiName may also be a login name.
Added:
>
>
 

Creating New Topics

Added:
>
>
 

expandVariablesOnTopicCreation ( $text ) -> $text

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

Line: 1260 to 1342
 See also: expandVariables
Changed:
<
<

Special handlers

>
>

Special Handlers

  Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.
Added:
>
>
 

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

Should only be called from initPlugin.

Line: 1312 to 1396
 
  • registered tag handlers cannot return another tag as their only result (e.g. return '%SERVERTIME%';). It won't work.
Added:
>
>
 

registerRESTHandler( $alias, \&fn, )

Should only be called from initPlugin.

Line: 1353 to 1438
 (ie, with the name of the function instead of the alias) will not work.
Added:
>
>
 

decodeFormatTokens($str) -> $unencodedString

TWiki has an informal standard set of tokens used in format

Line: 1384 to 1470
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

Searching

Added:
>
>
 

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+{.*}%)

Line: 1396 to 1484
 
  • \%option - reference to an options hash
The \%options hash may contain the following options:
  • type - if regex will perform a egrep-syntax RE search (default '')
Changed:
<
<
  • casesensitive - false to ignore case (defaulkt true)
>
>
  • casesensitive - false to ignore case (default true)
 
  • 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

Line: 1415 to 1503
 Since: TWiki::Plugins::VERSION 1.1
Changed:
<
<

Plugin-specific file handling

>
>

Plugin-specific File Handling

 
Added:
>
>
 

getWorkArea( $pluginName ) -> $directorypath

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

Line: 1432 to 1522
 Since: TWiki::Plugins::VERSION 1.1 (Dec 2005)
Added:
>
>
 

readFile( $filename ) -> $text

Read file, low level. Used for Plugin workarea.

Line: 1443 to 1534
 Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
Added:
>
>
 

saveFile( $filename, $text )

Save file, low level. Used for Plugin workarea.

Line: 1455 to 1547
 Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
Added:
>
>
 

General Utilities

Added:
>
>
 

getRegularExpression( $name ) -> $expr

Retrieves a TWiki predefined regular expression or character class.

Line: 1502 to 1596
 
tagNameRegex Standard variable names e.g. %THIS_BIT% (THIS_BIT only) RE
Added:
>
>
 

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

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

Line: 1530 to 1625
 
( '', '%DOCWEB%.Topic' ) ( 'TWiki', 'Topic' )
Changed:
<
<

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

>
>

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

  Given a file namer, sanitise it according to the rules for transforming attachment names. Returns
Line: 1542 to 1638
 Since: TWiki::Plugins::VERSION 1.2
Changed:
<
<
>
>
 

buildWikiWord( $text ) -> $text

Converts arbitrary text to a WikiWord.

Line: 1552 to 1648
 Since: TWiki::Plugins::VERSION 1.3 (18 Jan 2010)
Added:
>
>
 

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

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

Line: 1560 to 1657
 Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
 

writeWarning( $text )

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

Line: 1569 to 1667
 Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
Added:
>
>
 

writeDebug( $text )

Log debug message to data/debug.txt

Line: 1578 to 1677
 Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
Added:
>
>
 

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

Format the time in seconds into the desired time string

Line: 1590 to 1690
 Since: TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
Added:
>
>
 

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

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

Line: 1603 to 1704
 Since: $TWiki::Plugins::VERSION 1.2
Added:
>
>
 

isValidWikiWord ( $text ) -> $boolean

Check for a valid WikiWord or WikiName

Line: 1611 to 1713
 Since: TWiki::Plugins::VERSION 1.100 (Dec 2005)
Added:
>
>
 

extractParameters($attr ) -> %params

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

Line: 1630 to 1733
  name2 => "val2"
Added:
>
>
 

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

Extract a named or unnamed value from a variable parameter string

Line: 1649 to 1753
  my $val2  = TWiki::Func::extractNameValuePair( $text, "name2" );
Added:
>
>
 

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.

Line: 1666 to 1771
 The following functions are retained for compatibility only. You should stop using them as soon as possible.
Added:
>
>
 

getScriptUrlPath( ) -> $path

Get script URL path

Line: 1681 to 1787
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

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

Compose fully qualified 'oops' dialog URL

Line: 1715 to 1822
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

permissionsSet( $web ) -> $boolean

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

Line: 1738 to 1846
 
Added:
>
>
 

getPublicWebList( ) -> @webs

DEPRECATED since 1.1 - use getListOfWebs instead.

Line: 1749 to 1858
 Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
Added:
>
>
 

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

DEPRECATED since 1.1 - use formatTime instead.

Line: 1761 to 1871
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Added:
>
>
 

getDataDir( ) -> $dir

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

Line: 1774 to 1885
 Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
Added:
>
>
 

getPubDir( ) -> $dir

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

Line: 1789 to 1901
 Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
Added:
>
>
 

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

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

Line: 1797 to 1910
 Since: TWiki::Plugins::VERSION 1.025 (01 Aug 2004)
Added:
>
>
 

TWiki API History

TWiki-2001-09-01 (Athens Release)

 
This site is powered by the TWiki collaboration platformCopyright © 1999-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiFuncDotPm.