Package TWiki::Func

<-- STARTINCLUDE required for huge TWikiDocumentation topic -->

Official list of stable TWiki functions for Plugin developers

This module defines official functions that Plugins can use to interact with the TWiki engine and content.

Refer to EmptyPlugin and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.

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

Deprecated functions will still work in older code, though they should not be called in new Plugins and should be replaced in older Plugins as soon as possible.

The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.11. 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.

Note: Beware! These methods should only ever be called from the context of a TWiki Plugin. They require a Plugins SESSION context to be established before they are called, and will not work if simply called from another TWiki module. For example,

use TWiki;
print TWiki::Func::getSkin(),"\n";

If you want to call the methods outside the context of a plugin, you can create a Plugins SESSION object. For example, the script:

use TWiki:
$TWiki::Plugins::SESSION = new TWiki();
print TWiki::Func::getSkin(),"\n";

Environment

getSkin( ) -> $skin

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

Return: $skin Comma-separated list of skins, e.g. 'gnu,tartan'. Empty string if none.

Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

getUrlHost( ) -> $host

Get protocol, domain and optional port of script URL

Return: $host URL host, e.g. "http://example.com:80"

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

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

Compose fully qualified URL

• $web - Web name, e.g. 'Main'
• $topic - Topic name, e.g. 'WebNotify'
• $script - Script name, e.g. 'view'

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

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

Compose fully qualified view URL

• $web - Web name, e.g. 'Main'. The current web is taken if empty
• $topic - Topic name, e.g. 'WebNotify'

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

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

This might be used like this:

   my $url = TWiki::Func::getOopsUrl($web, $topic, 'oopsmistake', 'I made a boo-boo');
   TWiki::Func::redirectCgiQuery( undef, $url );
   return 0;

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

Since TWiki::Plugins::VERSION 1.1, the recommended approach is to throw an oops exception.

   use Error qw( :try );

   throw TWiki::OopsException($web, $topic, undef, 0, [ 'I made a boo-boo' ]);

getPubUrlPath( ) -> $path

Get pub URL path

Return: $path URL path of pub directory, e.g. "/pub"

Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

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

Return: $query CGI query object; or 0 if script is called as a shell script

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

getSessionValue( $key ) -> $value

Get a session value from the client session module

• $key - Session key

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

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

Set a session value via the client session module

• $key - Session key
• $value - Value associated with key

Since: TWiki::Plugins::VERSION 1.000 (17 Aug 2001)

clearSessionValue( $key ) -> $boolean

Clear a session value via the client session module

• $key - Session key

Since: TWiki::Plugins::VERSION 1.1

getContext() -> \%hash

The context is a set of identifiers that are set during specific phases of TWiki processing. For example, each of the standard scripts in the 'bin' directory each has a context identifier - the view script has 'view', the edit script has 'edit' etc. So you can easily tell what 'type' of script your Plugin is being called within. The core context identifiers are listed in the TWikiTemplates topic. Please be careful not to overwrite any of these identifiers!

Context identifiers can be used to communicate between Plugins, and between Plugins and templates. For example, in FirstPlugin? .pm, you might write:

sub initPlugin {
   TWiki::Func::getContext()->{'MyID'} = 1;
   ...

sub initPlugin {
   if( TWiki::Func::getContext()->{'MyID'} ) {
      ...
   }
   ...

%TMPL:DEF{"ON"}% Not off %TMPL:END%
%TMPL:DEF{"OFF"}% Not on %TMPL:END%
%TMPL:P{context="MyID" then="ON" else="OFF"}%

%IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%

Since: TWiki::Plugins::VERSION 1.1

Preferences

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

Get a preferences value from TWiki or from a Plugin

• $key - Preferences key
• $web - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics

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

• 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

Get a preferences value from your Plugin

• $key - Plugin Preferences key w/o PLUGINNAME_ prefix.

Note: This function will will only work when called from the Plugin.pm file itself. it will not work if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)

Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)

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

Get a preferences flag from TWiki or from a Plugin

• $key - Preferences key
• $web - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics

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

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

getPluginPreferencesFlag( $key ) -> $boolean

Get a preferences flag from your Plugin

• $key - Plugin Preferences key w/o PLUGINNAME_ prefix.

Note: This function will will only work when called from the Plugin.pm file itself. it will not work if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)

Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)

getWikiToolName( ) -> $name

Get toolname as defined in TWiki.cfg

Return: $name Name of tool, e.g. 'TWiki'

Synonymous with TWiki::Func::getPreferencesValue('WIKITOOLNAME');

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

getMainWebname( ) -> $name

Get name of Main web as defined in TWiki.cfg

Return: $name Name, e.g. 'Main'

Synonymous with TWiki::Func::getPreferencesValue('MAINWEB');

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

getTwikiWebname( ) -> $name

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

Return: $name Name, e.g. 'TWiki'

Synonymous with TWiki::Func::getPreferencesValue('TWIKIWEB');

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

User Handling and Access Control

getDefaultUserName( ) -> $loginName

Get default user name as defined in the configuration as DefaultUserLogin

Return: $loginName Default user name, e.g. 'guest'

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

getWikiName( ) -> $wikiName

Get Wiki name of logged in user

Return: $wikiName Wiki Name, e.g. 'JohnDoe'

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

getWikiUserName( ) -> $wikiName

Get Wiki name of logged in user with web prefix

Return: $wikiName Wiki Name, e.g. "Main.JohnDoe"

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

wikiToUserName( $wikiName ) -> $loginName

Translate a Wiki name to a login name based on Main.TWikiUsers topic

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

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

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

Translate a login name to a Wiki name based on Main.TWikiUsers topic

• $loginName - Login name, e.g. 'jdoe'
• $dontAddWeb - Do not add web prefix if "1"

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

isGuest( ) -> $boolean

Test if logged in user is a guest (TWikiGuest? )

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)

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

Check access permission for a topic based on the TWiki.TWikiAccessControl rules

• $type - Access type, e.g. 'VIEW', 'CHANGE', 'CREATE'
• $wikiName - WikiName of remote user, i.e. "Main.PeterThoeny"
• $text - Topic text, optional. If empty, topic $web.$topic is consulted
• $topic - Topic name, required, e.g. 'PrivateStuff'
• $web - Web name, required, e.g. 'Sandbox'

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

Webs, Topics and Attachments

getListOfWebs( $filter ) -> @webs

• $filter - spec of web types to recover

1. 'user' (for only user webs)
2. 'template' (for only template webs i.e. those starting with "_")

For example, the deprecated getPublicWebList function can be duplicated as follows:

   my @webs = TWiki::Func::getListOfWebs( "user,public" );

Since: TWiki::Plugins::VERSION 1.1

webExists( $web ) -> $boolean

Test if web exists

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

Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

createWeb( $newWeb, $baseWeb, $opts )

• $newWeb is the name of the new web.
• $baseWeb is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.
• $opts is a ref to a hash that contains settings to be modified in

use Error qw( :try );
use TWiki::AccessControlException;

try {
    TWiki::Func::createWeb( "Newweb" );
} catch Error::Simple with {
    my $e = shift;
    # see documentation on Error::Simple
} catch TWiki::AccessControlException with {
    my $e = shift;
    # see documentation on TWiki::AccessControlException
} otherwise {
    ...
};

Since: TWiki::Plugins::VERSION 1.1

moveWeb( $oldName, $newName )

Move (rename) a web.

use Error qw( :try );
use TWiki::AccessControlException;

try {
    TWiki::Func::moveWeb( "Oldweb", "Newweb" );
} catch Error::Simple with {
    my $e = shift;
    # see documentation on Error::Simple
} catch TWiki::AccessControlException with {
    my $e = shift;
    # see documentation on TWiki::AccessControlException
} otherwise {
    ...
};

To delete a web, move it to a subweb of Trash

TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );

Since: TWiki::Plugins::VERSION 1.1

getTopicList( $web ) -> @topics

Get list of all topics in a web

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

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

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

Test if topic exists

• $web - Web name, optional, e.g. 'Main'.
• $topic - Topic name, required, e.g. 'TokyoOffice', or "Main.TokyoOffice"

Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

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

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

Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

setTopicEditLock( $web, $topic, $lock )

• $web Web name, e.g. "Main", or empty
• $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"
• $lock 1 to lease the topic, 0 to clear the lease=

Takes out a "lease" on the topic. The lease doesn't prevent anyone from editing and changing the topic, but it does redirect them to a warning screen, so this provides some protection. The edit script always takes out a lease.

It is impossible to fully lock a topic. Concurrent changes will be merged.

Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

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

• $web - web for the topic
• $topic - topic name
• $meta - reference to TWiki::Meta object
• $text - text of the topic (without embedded meta-data!!!
• \%options - ref to hash of save options \%options may include:

  dontlog	don't log this change in twiki log
  comment	comment for save
  minor	True if this is a minor change, and is not to be notified

Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

For example,

my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic )
$text =~ s/APPLE/ORANGE/g;
TWiki::Func::saveTopic( $web, $topic, $meta, $text, { comment => 'refruited' } );

Note: Plugins handlers ( e.g. beforeSaveHandler ) will be called as appropriate.

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.

• $web - Web name, e.g. 'Main', or empty
• $topic - Topic name, e.g. 'MyTopic', or "Main.MyTopic"
• $text - Topic text to save, assumed to include meta data
• $ignorePermissions - Set to "1" if checkAccessPermission() is already performed and OK
• $dontNotify - Set to "1" if not to notify users of the change

This method is a lot less efficient and much more dangerous than saveTopic.

Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

my $text = TWiki::Func::readTopicText( $web, $topic );

# 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

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

• $web source web - required
• $topic source topic - required
• $newWeb dest web
• $newTopic dest topic

The destination topic must not already exist.

Rename a topic to the $TWiki::cfg{TrashWebName} to delete it.

Since: TWiki::Plugins::VERSION 1.1

use Error qw( :try );

try {
    moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
} catch Error::Simple with {
    my $e = shift;
    # see documentation on Error::Simple
} catch TWiki::AccessControlException with {
    my $e = shift;
    # see documentation on TWiki::AccessControlException
} otherwise {
    ...
};

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

• $web - Web name, optional, e.g. 'Main'
• $topic - Topic name, required, e.g. 'TokyoOffice'
• $rev - revsion number, or tag name (can be in the format 1.2, or just the minor number)
• $attachment -attachment filename

NOTE: if you are trying to get revision info for a topic, use $meta->getRevisionInfo instead if you can - it is significantly more efficient, and returns a user object that contains other user information.

NOTE: prior versions of TWiki may under some circumstances have returned the login name of the user rather than the wiki name; the code documentation was totally unclear, and we have been unable to establish the intent. However the wikiname is obviously more useful, so that is what is returned.

Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

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

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

• $web - web for topic
• $topic - topic
• $time - time (in epoch secs) for the rev

Since: TWiki::Plugins::VERSION 1.1

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

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

• $web - Web name, required, e.g. 'Main'
• $topic - Topic name, required, e.g. 'TokyoOffice'
• $rev - revision to read (default latest)

$meta is a perl 'object' of class TWiki::Meta. This class is fully documented in the source code documentation shipped with the release, or can be inspected in the lib/TWiki/Meta.pm file.

This method ignores topic access permissions. You should be careful to use checkAccessPermissions to ensure the current user has read access to the topic.

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

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

Read topic text, including meta data

• $web - Web name, e.g. 'Main', or empty
• $topic - Topic name, e.g. 'MyTopic', or "Main.MyTopic"
• $rev - Topic revision to read, optional. Specify the minor part of the revision, e.g. "5", not "1.5"; the top revision is returned if omitted or empty.
• $ignorePermissions - Set to "1" if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission

This method is more efficient than readTopic, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer..

Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

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

Test if attachment exists

• $web - Web name, optional, e.g. Main.
• $topic - Topic name, required, e.g. TokyoOffice, or Main.TokyoOffice
• $attachment - attachment name, e.g.=logo.gif=

Since: TWiki::Plugins::VERSION 1.1

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

• $web - web for topic
• $topic - topic
• $name - attachment name
• $rev - revision to read (default latest)

View permission on the topic is required for the read to be successful. Access control violations are flagged by a TWiki::AccessControlException. Permissions are checked for the user passed in.

my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic );
my @attachments = $meta->find( 'FILEATTACHMENT' );
foreach my $a ( @attachments ) {
   try {
       my $data = TWiki::Func::readAttachment( $meta, $a->{name} );
       ...
   } catch TWiki::AccessControlException with {
   };
}

Since: TWiki::Plugins::VERSION 1.1

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

• $web - web for topic
• $topic - topic to atach to
• $attachment - name of the attachment
• $opts - Ref to hash of options

Save an attachment to the store for a topic. On success, returns undef. If there is an error, an exception will be thrown.

    try {
        TWiki::Func::saveAttachment( $web, $topic, 'image.gif',
                                     { file => 'image.gif',
                                       comment => 'Picture of Health',
                                       hide => 1 } );
   } catch Error::Simple with {
      # see documentation on Error
   } otherwise {
      ...
   };

Since: TWiki::Plugins::VERSION 1.1

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

• $web source web - required
• $topic source topic - required
• $attachment source attachment - required
• $newWeb dest web
• $newTopic dest topic
• $newAttachment dest attachment

The destination topic must already exist, but the destination attachment must not exist.

Rename an attachment to $TWiki::cfg{TrashWebName}.TrashAttament to delete it.

use Error qw( :try );

try {
   # move attachment between topics
   moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat",
                     "Countries", "France" );
   # Note destination attachment name is defaulted to the same as source
} catch TWiki::AccessControlException with {
   my $e = shift;
   # see documentation on TWiki::AccessControlException
} catch Error::Simple with {
   my $e = shift;
   # see documentation on Error::Simple
};

Since: TWiki::Plugins::VERSION 1.1

Assembling Pages

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

Read a template or skin. Embedded template directives get expanded

• $name - Template name, e.g. 'view'
• $skin - Comma-separated list of skin names, optional, e.g. 'print'

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

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

• $name - template file name
• $skin - comma-separated list of skins to use (default: current skin)
• $web - the web to look in for topics that contain templates (default: current web)

Since: TWiki::Plugins::VERSION 1.1

Reads a template and extracts template definitions, adding them to the list of loaded templates, overwriting any previous definition.

How TWiki searches for templates is described in TWikiTemplates.

If template text is found, extracts include statements and fully expands them.

expandTemplate( $def ) -> $string

• $def - template name

Since: TWiki::Plugins::VERSION 1.1

A template is defined using a %TMPL:DEF% statement in a template file. See the documentation on TWiki templates for more information.

writeHeader( $query, $contentLength )

Prints a basic content-type HTML header for text/html to standard out

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

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

redirectCgiQuery( $query, $url )

Redirect to URL

• $query - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
• $url - URL to redirect to

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

addToHEAD( $id, $header )

• $id - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN_JSCALENDAR)
• $header - the HTML to be added to the section. The HTML must be valid in a HEAD tag - no checks are performed.

All TWiki variables present in $header will be expanded before being inserted into the section.

Note that this is not the same as the HTTP header, which is modified through the Plugins modifyHeaderHandler.

Since: TWiki::Plugins::VERSION 1.1

example:

TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')

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

Expand all common %VARIABLES%

• $text - Text with variables to expand, e.g. 'Current user is %WIKIUSER%'
• $topic - Current topic name, e.g. 'WebNotify'
• $web - Web name, optional, e.g. 'Main'. The current web is taken if missing

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

See also: expandVariablesOnTopicCreation

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

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

• $text - Text to render, e.g. '*bold* text and =fixed font='
• $web - Web name, optional, e.g. 'Main'. The current web is taken if missing

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

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

• $pre - Text occuring before the TWiki link syntax, optional
• $web - Web name, required, e.g. 'Main'
• $topic - Topic name to link to, required, e.g. 'WebNotify'
• $label - Link label, required. Usually the same as $topic, e.g. 'notify'
• $anchor - Anchor, optional, e.g. '#Jump'
• $createLink - Set to '1' to add question linked mark after topic name if topic does not exist;
  set to '0' to suppress link for non-existing topics

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

E-mail

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

• $text - text of the mail, including MIME headers
• $retries - number of times to retry the send (default 1)

To: liz@windsor.gov.uk
From: serf@hovel.net
CC: george@whitehouse.gov
Subject: Revolution

Dear Liz,

Please abolish the monarchy (with King George's permission, of course)

Thanks,

A. Peasant

Since: TWiki::Plugins::VERSION 1.1

wikiToEmail( $wikiName ) -> $email

• $wikiName - wiki name of the user

Since: TWiki::Plugins::VERSION 1.1

Creating New Topics

expandVariablesOnTopicCreation ( $text ) -> $text

• $text - the text to process

Since: TWiki::Plugins::VERSION 1.1

Expands only the variables expected in templates that must be statically expanded in new content.

The expanded variables are:

• %DATE% Signature-format date
• %SERVERTIME% See TWikiVariables
• %GMTIME% See TWikiVariables
• %USERNAME% Base login name
• %WIKINAME% Wiki name
• %WIKIUSERNAME% Wiki name with prepended web
• %URLPARAM{...}% - Parameters to the current CGI query
• %NOP% No-op

See also: expandVariables

Special handlers

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

Register a function to handle a simple variable. Handles both %VAR% and %VAR{...}%. Registered variables are treated the same as TWiki internal variables, and are expanded at the same time. This is a lot more efficient than using the commonTagsHandler.

• $var - The name of the variable, i.e. the 'MYVAR' part of %MYVAR%. The variable name must match /^[A-Z][A-Z0-9_]*$/ or it won't work.
• \&fn - Reference to the handler function.
• $syntax can be 'classic' (the default) or 'context-free'. 'classic' syntax is appropriate where you want the variable to support classic TWiki syntax i.e. to accept the standard %MYVAR{ "unnamed" param1="value1" param2="value2" }% syntax, as well as an unquoted default parameter, such as %MYVAR{unquoted parameter}%. If your variable will only use named parameters, you can use 'context-free' syntax, which supports a more relaxed syntax. For example, %MYVAR{param1=value1, value 2, param3="value 3", param4='value 5"}%

Since: TWiki::Plugins::VERSION 1.1

The variable handler function must be of the form:

sub handler(\%session, \%params, $topic, $web)

• \%session - a reference to the TWiki session object (may be ignored)
• \%params - a reference to a TWiki::Attrs object containing parameters. This can be used as a simple hash that maps parameter names to values, with _DEFAULT being the name for the default parameter.
• $topic - name of the topic in the query
• $web - name of the web in the query

sub initPlugin{
   TWiki::Func::registerTagHandler('EXEC', \&boo);
}

sub boo {
    my( $session, $params, $topic, $web ) = @_;
    my $cmd = $params->{_DEFAULT};

    return "NO COMMAND SPECIFIED" unless $cmd;

    my $result = `$cmd 2>&1`;
    return $params->{silent} ? '' : $result;
}
}

registerRESTHandler( $alias, \&fn, )

Adds a function to the dispatch table of the REST interface

• $alias - The name .
• \&fn - Reference to the function.

Since: TWiki::Plugins::VERSION 1.1

The handler function must be of the form:

sub handler(\%session)

• \%session - a reference to the TWiki session object (may be ignored)

From the REST interface, the name of the plugin must be used as the subject of the invokation.

Example

The EmptyPlugin has the following call in the initPlugin handler:

   TWiki::Func::registerRESTHandler('example', \&restExample);

This adds the restExample function to the REST dispatch table for the EmptyPlugin under the 'example' alias, and allows it to be invoked using the URL

http://server:port/bin/rest/EmptyPlugin/example

note that the URL

http://server:port/bin/rest/EmptyPlugin/restExample

(ie, with the name of the function instead of the alias) will not work.

Searching

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

• $searchString - the search string, in egrep format
• $web - The web to search in
• \@topics - reference to a list of topics to search
• \%option - reference to an options hash

• type - if regex will perform a egrep-syntax RE search (default '')
• casesensitive - false to ignore case (defaulkt 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 name to a list of the lines in that topic that matched the search, as would be returned by 'grep'.

To iterate over the returned topics use:

my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics,
   { casesensitive => 0, files_without_match => 0 } );
foreach my $topic (keys %$result ) {
   foreach my $matching_line ( @{$result->{$topic}} ) {
      ...etc

Since: TWiki::Plugins::VERSION 1.1

Plugin-specific file handling

getWorkArea( $pluginName ) -> $directorypath

Gets a private directory for Plugin use. The Plugin is entirely responsible for managing this directory; TWiki will not read from it, or write to it.

The directory is guaranteed to exist, and to be writable by the webserver user. By default it will not be web accessible.

The directory and it's contents are permanent, so Plugins must be careful to keep their areas tidy.

Since: TWiki::Plugins::VERSION 1.1 (Dec 2005)

readFile( $filename ) -> $text

Read file, low level. Used for Plugin workarea.

• $filename - Full path name of file

NOTE: Use this function only for the Plugin workarea, not for topics and attachments. Use the appropriate functions to manipulate topics and attachments.

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

saveFile( $filename, $text )

Save file, low level. Used for Plugin workarea.

• $filename - Full path name of file
• $text - Text to save

NOTE: Use this function only for the Plugin workarea, not for topics and attachments. Use the appropriate functions to manipulate topics and attachments.

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

General Utilities

getRegularExpression( $name ) -> $expr

Retrieves a TWiki predefined regular expression or character class.

• $name - Name of the expression to retrieve. See notes below

Since: TWiki::Plugins::VERSION 1.020 (9 Feb 2004)

Note: TWiki internally precompiles several regular expressions to represent various string entities in an I18N? -compatible manner. Plugins authors 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.

In the table below, the expression marked type 'String' are intended for use within character classes (i.e. for use within square brackets inside a regular expression), for example:

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

   my $webRE = TWiki::Func::getRegularExpression('webNameRegex');
   my $isWebName = ( $s =~ m/$webRE/ );

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

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

• $web - Web name, identifying variable, or empty string
• $topic - Topic name, may be a web.topic string, required.

Since: TWiki::Plugins::VERSION 1.1

writeWarning( $text )

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

• $text - Text to write; timestamp gets added

Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)

writeDebug( $text )

Log debug message to data/debug.txt

• $text - Text to write; timestamp gets added

Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)

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

Format the time in seconds into the desired time string

• $time - Time in epoc seconds
• $format - Format type, optional. Default e.g. '31 Dec 2002 - 19:30'. Can be '$iso' (e.g. '2002-12-31T19:30Z'), '$rcs' (e.g. '2001/12/31 23:59:59', '$http' for HTTP header format (e.g. 'Thu, 23 Jul 1998 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
• $timezone - either not defined (uses the displaytime setting), 'gmtime', or 'servertime'

Since: TWiki::Plugins::VERSION 1.020 (26 Feb 2004)

isValidWikiWord ( $text ) -> $boolean

Check for a valid WikiWord or WikiName

• $text - Word to test

Since: TWiki::Plugins::VERSION 1.100 (Dec 2005)

extractParameters($attr ) -> %params

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

• $attr - Attribute string

Since: TWiki::Plugins::VERSION 1.025 (26 Aug 2004)

• 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:
    
• params = TWiki::Func::extractParameters( $text );=
  • The %params hash contains now:
    _DEFAULT => 'nameless'
name1 => "val1"
name2 => "val2"

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

Extract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters

• $attr - Attribute string
• $name - Name, optional

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

• 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" );

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.

Updated plugins may still need to define deprecated handlers for compatibility with old TWiki versions. In this case, the plugin package that defines old handlers can suppress the warnings in %FAILEDPLUGINS%.

This is done by defining a map from the handler name to the TWiki::Plugins version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler for compatibility with TWiki::Plugins versions before 1.1, we would add this to the plugin:

package TWiki::Plugins::SinkPlugin;
use vars qw( %TWikiCompatibility );
$TWikiCompatibility{endRenderingHandler} = 1.1;

The following functions are retained for compatibility only. You should stop using them as soon as possible.

getScriptUrlPath( ) -> $path

Get script URL path

DEPRECATED since 1.1 - use getScriptUrl instead.

Return: $path URL path of TWiki scripts, e.g. "/cgi-bin"

WARNING: you are strongly recommended not to use this function, as the {ScriptUrlPaths} URL rewriting rules will not apply to urls generated using it.

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

getPublicWebList( ) -> @webs

DEPRECATED since 1.1 - use getListOfWebs instead.

Get list of all public webs, e.g. all webs that do not have the NOSEARCHALL flag set in the WebPreferences

Return: @webs List of all public webs, e.g. ( 'Main',  'Know', 'TWiki' )

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

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

DEPRECATED since 1.1 - use formatTime instead.

Format the time to GM time

• $time - Time in epoc seconds
• $format - Format type, optional. Default e.g. '31 Dec 2002 - 19:30', can be 'iso' (e.g. '2002-12-31T19:30Z'), 'rcs' (e.g. '2001/12/31 23:59:59', 'http' for HTTP header format (e.g. 'Thu, 23 Jul 1998 07:21:56 GMT')

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

getDataDir( ) -> $dir

DEPRECATED since 1.1 - use the content handling functions to manipulate topics instead

Get data directory (topic file root)

Return: $dir Data directory, e.g. '/twiki/data'

This function violates store encapsulation and is therefore deprecated.

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

getPubDir( ) -> $dir

DEPRECATED since 1.1 - use the content handling functions to manipulateattachments instead

Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName

Return: $dir Pub directory, e.g. '/htdocs/twiki/pub'

This function violates store encapsulation and is therefore deprecated.

Use readAttachment and saveAttachment instead.

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

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

DEPRECATED since 1.1 - use TWiki:Plugins.BuildContrib and define DEPENDENCIES that can be statically evaluated at install time instead. It is a lot more efficient.

Since: TWiki::Plugins::VERSION 1.025 (01 Aug 2004)