NOTE: This is a HistoricalDocument topic. It used to be distributed in an earlier TWiki release, but is no longer part of the official TWiki distribution. Post questions, error notes, and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

Note: This is the old TWiki 01-Sep-2004 API; the latest TWiki 4.0 API documentation is at TWikiFuncDotPm.

TWiki::Func Module Documentation

Official list of stable TWiki functions for Plugin developers

Description

This module defines official funtions that Plugins and add-on scripts can use to interact with the TWiki engine and content.

Plugins should only use functions published in this module. If you use functions in other TWiki libraries you might impose a security hole and you will likely need to change your Plugin when you upgrade TWiki.

The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.025. This can be shown by the %PLUGINVERSION{}% variable. The "Since" field in the function documentation refers to the VERSION number and the date that the function was addded.

Functions: CGI Environment

getSessionValue( $key ) ==> $value

setSessionValue( $key, $value ) ==> $result

getSkin( ) ==> $skin

getUrlHost( ) ==> $host

getScriptUrl( $web, $topic, $script ) ==> $url

getScriptUrlPath( ) ==> $path

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

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

getPubUrlPath( ) ==> $path

getCgiQuery( ) ==> $query

writeHeader( $query )

redirectCgiQuery( $query, $url )

Functions: Preferences

extractParameters( $attr ) ==> %params

• Example:
  • Variable: %TEST{ "nameless" name1="val1" name2="val2" }%
  • First extract text between {...} to get: "nameless" name1="val1" name2="val2"
  • Then call this on the text:
    my %params = TWiki::Func::extractParameters( $text );
  • The %params hash contains now:
    _DEFAULT => "nameless"
name1 => "val1"
name2 => "val2"

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

• Example:
  • Variable: %TEST{ "nameless" name1="val1" name2="val2" }%
  • First extract text between {...} to get: "nameless" name1="val1" name2="val2"
  • Then call this on the text:
    my $noname = TWiki::Func::extractNameValuePair( $text );
my $val1  = TWiki::Func::extractNameValuePair( $text, "name1" );
my $val2  = TWiki::Func::extractNameValuePair( $text, "name2" );

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

• Example for Plugin setting:
  • MyPlugin topic has: * Set COLOR = red
  • Use "MYPLUGIN_COLOR" for $key
  • my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );

• Example for preferences setting:
  • WebPreferences topic has: * Set WEBBGCOLOR = #FFFFC0
  • my $webColor = TWiki::Func::getPreferencesValue( "WEBBGCOLOR", "Sandbox" );

getPluginPreferencesValue( $key ) ==> $value

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

• Example for Plugin setting:
  • MyPlugin topic has: * Set SHOWHELP = off
  • Use "MYPLUGIN_SHOWHELP" for $key
  • my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );

getPluginPreferencesFlag( $key ) ==> $flag

getWikiToolName( ) ==> $name

getMainWebname( ) ==> $name

getTwikiWebname( ) ==> $name

Functions: User Handling and Access Control

getDefaultUserName( ) ==> $loginName

getWikiName( ) ==> $wikiName

getWikiUserName( $text ) ==> $wikiName

wikiToUserName( $wikiName ) ==> $loginName

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

isGuest( ) ==> $flag

permissionsSet( $web ) ==> $flag

checkAccessPermission( $type, $wikiName, $text, $topic, $web ) ==> $flag

Functions: Content Handling

webExists( $web ) ==> $flag

topicExists( $web, $topic ) ==> $flag

getRevisionInfo($theWebName, $theTopic, $theRev, $attachment ) ==> ( $date, $user, $rev, $comment )

checkTopicEditLock( $web, $topic ) ==> ( $oopsUrl, $loginName, $unlockTime )

setTopicEditLock( $web, $topic, $lock ) ==> $oopsUrl

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

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

• Example:
  my $oopsUrl = TWiki::Func::setTopicEditLock( $web, $topic, 1 );
if( $oopsUrl ) {
    TWiki::Func::redirectCgiQuery( $query, $oopsUrl );   # assuming valid query
    return;
}
my $text = TWiki::Func::readTopicText( $web, $topic );        # read topic text
# check for oops URL in case of error:
if( $text =~ /^http.*?\/oops/ ) {
    TWiki::Func::redirectCgiQuery( $query, $text );
    return;
}
# do topic text manipulation like:
$text =~ s/old/new/g;
# do meta data manipulation like:
$text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
$oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
TWiki::Func::setTopicEditLock( $web, $topic, 0 );             # unlock topic
if( $oopsUrl ) {
    TWiki::Func::redirectCgiQuery( $query, $oopsUrl );
    return;
}

getPublicWebList( ) ==> @webs

getTopicList( $web ) ==> @topics

Functions: Rendering

expandCommonVariables( $text, $topic, $web ) ==> $text

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

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

search text( $text ) ==> $text

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

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

Functions: File I/O

getDataDir( ) ==> $dir

getPubDir( ) ==> $dir

readTopic( $web, $topic ) ==> ( $meta, $text )