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 )

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

readFile( $filename ) ==> $text

saveFile( $filename, $text )

writeWarning( $text )

writeDebug( $text )

Functions: System and I18N related

getRegularExpression( $regexName ) ==> $pattern

Notes: TWiki internally precompiles several regular expressions to represent various string entities in an I18N-compatible manner. Plugins are encouraged to use these in matching where appropriate. The following are guaranteed to be present; others may exist, but their use is unsupported and they may be removed in future TWiki versions. Those which are marked "CC" are for use within character classes and may not produce the desired results outside of them.

Example:

   my $upper = TWiki::Func::getRegularExpression("upperAlpha");
   my $alpha = TWiki::Func::getRegularExpression("mixedAlpha");
   my $capitalized = qr/[$upper][$alpha]+/;

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

The dependencies are expressed as a list of hashes. Each hash contains the name of a package and (optionally) a boolean constraint on the VERSION variable in that package. It is usually used from the initPlugin method like this:

   if( $TWiki::Plugins::VERSION >= 1.025 ) {
      my @deps = (
            { package => 'TWiki::Plugins::CalendarPlugin', constraint => '>= 5.030' },
            { package => 'Time::ParseDate' },
            { package => 'Apache::VMonitor' }
      );
      my $err = TWiki::Func::checkDependencies( $pluginName, \@deps );
      if( $err ) {
            TWiki::Func::writeWarning( $err );
            print STDERR $err; # print to webserver log file
            return 0; # plugin initialisation failed
      }
   }

Copyright and License

Copyright (C) 2000-2004 Peter Thoeny, Peter@Thoeny.com

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details, published at http://www.gnu.org/copyleft/gpl.html

NOTE: Above text is copied from the TWiki::Plugins/PerlDocPlugin output of TWiki::Func in twiki format. In case you want to get dynamically updated documentation based on the actual Perl module, install the PerlDocPlugin and replace above text with %PERLDOC{"TWiki::Func"}%.

-- PeterThoeny^? - 31 Dec 2002