%PLUGINVERSION{}%
variable. The "Since" field in the function documentation
refers to the VERSION number and the date that the function was addded.
Description: | Get a session value from the Session Plugin (if installed) |
Parameter: $key | Session key |
Return: $value | Value associated with key; empty string if not set; undef if session plugin is not installed |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
Description: | Set a session value via the Session Plugin (if installed) |
Parameter: $key | Session key |
Parameter: $value | Value associated with key |
Return: $result | "1" if success; undef if session plugin is not installed |
Since: | TWiki::Plugins::VERSION 1.000 (17 Aug 2001) |
Description: | Get the name of the skin, set by the SKIN preferences variable or the skin CGI parameter |
Return: $skin | Name of skin, e.g. "gnu" . Empty string if none |
Since: | TWiki::Plugins::VERSION 1.000 (29 Jul 2001) |
Description: | 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) |
Description: | Compose fully qualified URL |
Parameter: $web | Web name, e.g. "Main" |
Parameter: $topic | Topic name, e.g. "WebNotify" |
Parameter: $script | Script name, e.g. "view" |
Return: $url | URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Get script URL path |
Return: $path | URL path of TWiki scripts, e.g. "/cgi-bin" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Compose fully qualified view URL |
Parameter: $web | Web name, e.g. "Main" . The current web is taken if empty |
Parameter: $topic | Topic name, e.g. "WebNotify" |
Return: $url | URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Compose fully qualified "oops" dialog URL |
Parameter: $web | Web name, e.g. "Main" . The current web is taken if empty |
Parameter: $topic | Topic name, e.g. "WebNotify" |
Parameter: $template | Oops template name, e.g. "oopslocked" |
Parameter: $param1 ... $param4 | Parameter values for %PARAM1% ... %PARAM4% variables in template, optional |
Return: $url | URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked¶m1=joe" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Get pub URL path |
Return: $path | URL path of pub directory, e.g. "/pub" |
Since: | TWiki::Plugins::VERSION 1.000 (14 Jul 2001) |
Description: | 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) |
Description: | Prints a basic content-type HTML header for text/html to standard out |
Parameter: $query | CGI query object |
Return: | none |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Redirect to URL |
Parameter: $query | CGI query object |
Parameter: $url | URL to redirect to |
Return: | none, never returns |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Extract all parameters from a variable string and returns a hash of parameters |
Parameter: $attr | Attribute string |
Return: %params | Hash containing all parameters. The nameless parameter is stored in key _DEFAULT |
Since: | TWiki::Plugins::VERSION 1.025 (26 Aug 2004) |
%TEST{ "nameless" name1="val1" name2="val2" }%
{...}
to get: "nameless" name1="val1" name2="val2"
my %params = TWiki::Func::extractParameters( $text );
%params
hash contains now: _DEFAULT => "nameless"
name1 => "val1"
name2 => "val2"
Description: | Extract a named or unnamed value from a variable parameter string |
Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters |
Parameter: $attr | Attribute string |
Parameter: $name | Name, optional |
Return: $value | Extracted value |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
%TEST{ "nameless" name1="val1" name2="val2" }%
{...}
to get: "nameless" name1="val1" name2="val2"
my $noname = TWiki::Func::extractNameValuePair( $text );
my $val1 = TWiki::Func::extractNameValuePair( $text, "name1" );
my $val2 = TWiki::Func::extractNameValuePair( $text, "name2" );
Description: | Get a preferences value from TWiki or from a Plugin |
Parameter: $key | Preferences key |
Parameter: $web | Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics |
Return: $value | Preferences value; empty string if not set |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
* Set COLOR = red
"MYPLUGIN_COLOR"
for $key
my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );
* Set WEBBGCOLOR = #FFFFC0
my $webColor = TWiki::Func::getPreferencesValue( "WEBBGCOLOR", "Sandbox" );
Description: | Get a preferences value from your Plugin |
Parameter: $key | Plugin Preferences key w/o PLUGINNAME_ prefix. |
Return: $value | Preferences value; empty string if not set |
Since: | TWiki::Plugins::VERSION 1.021 (27 Mar 2004) |
Description: | Get a preferences flag from TWiki or from a Plugin |
Parameter: $key | Preferences key |
Parameter: $web | Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics |
Return: $value | Preferences flag "1" (if set), or "0" (for preferences values "off" , "no" and "0" ) |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
* Set SHOWHELP = off
"MYPLUGIN_SHOWHELP"
for $key
my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );
Description: | Get a preferences flag from your Plugin |
Parameter: $key | Plugin Preferences key w/o PLUGINNAME_ prefix. |
Return: $flag | Preferences flag "1" (if set), or "0" (for preferences values "off" , "no" and "0" , or values not set at all) |
Since: | TWiki::Plugins::VERSION 1.021 (27 Mar 2004) |
Description: | Get toolname as defined in TWiki.cfg |
Return: $name | Name of tool, e.g. "TWiki" |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
Description: | Get name of Main web as defined in TWiki.cfg |
Return: $name | Name, e.g. "Main" |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
Description: | Get name of TWiki documentation web as defined in TWiki.cfg |
Return: $name | Name, e.g. "TWiki" |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
Description: | Get default user name as defined in TWiki.cfg's $defaultUserName |
Return: $loginName | Default user name, e.g. "guest" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Get Wiki name of logged in user |
Return: $wikiName | Wiki Name, e.g. "JohnDoe" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | 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) |
Description: | Translate a Wiki name to a login name based on Main.TWikiUsers topic |
Parameter: $wikiName | Wiki name, e.g. "Main.JohnDoe" or "JohnDoe" |
Return: $loginName | Login name of user, e.g. "jdoe" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Translate a login name to a Wiki name based on Main.TWikiUsers topic |
Parameter: $loginName | Login name, e.g. "jdoe" |
Parameter: $dontAddWeb | Do not add web prefix if "1" |
Return: $wikiName | Wiki name of user, e.g. "Main.JohnDoe" or "JohnDoe" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Test if logged in user is a guest |
Return: $flag | "1" if yes, "0" if not |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Test if any access restrictions are set for this web, ignoring settings on individual pages |
Parameter: $web | Web name, required, e.g. "Sandbox" |
Return: $flag | "1" if yes, "0" if no |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
Description: | Check access permission for a topic based on the TWiki.TWikiAccessControl rules |
Parameter: $type | Access type, e.g. "VIEW" , "CHANGE" , "CREATE" |
Parameter: $wikiName | WikiName of remote user, i.e. "Main.PeterThoeny" |
Parameter: $text | Topic text, optional. If empty, topic $web.$topic is consulted |
Parameter: $topic | Topic name, required, e.g. "PrivateStuff" |
Parameter: $web | Web name, required, e.g. "Sandbox" |
Return: $flag | "1" if access may be granted, "0" if not |
Since: | TWiki::Plugins::VERSION 1.000 (27 Feb 2001) |
Description: | Test if web exists |
Parameter: $web | Web name, required, e.g. "Sandbox" |
Return: $flag | "1" if web exists, "0" if not |
Since: | TWiki::Plugins::VERSION 1.000 (14 Jul 2001) |
Description: | Test if topic exists |
Parameter: $web | Web name, optional, e.g. "Main" |
Parameter: $topic | Topic name, required, e.g. "TokyoOffice" , or "Main.TokyoOffice" |
Return: $flag | "1" if topic exists, "0" if not |
Since: | TWiki::Plugins::VERSION 1.000 (14 Jul 2001) |
Description: | Get revision info of a topic |
Parameter: $theWebName | Web name, optional, e.g. "Main" |
Parameter: $theTopic | Topic name, required, e.g. "TokyoOffice" |
Parameter: $theRev | revsion number, or tag name (can be in the format 1.2, or just the minor number) |
Parameter: $attachment | attachment filename |
Return: ( $date, $user, $rev, $comment ) | List with: ( last update date, login name of last user, minor part of top revision number ), e.g. ( 1234561, "phoeny", "5" ) |
$date | in epochSec |
$user | |
$rev | |
$comment | WHAT COMMENT? |
Since: | TWiki::Plugins::VERSION 1.000 (29 Jul 2001) |
Description: | Check if topic has an edit lock by a user |
Parameter: $web | Web name, e.g. "Main" , or empty |
Parameter: $topic | Topic name, e.g. "MyTopic" , or "Main.MyTopic" |
Return: ( $oopsUrl, $loginName, $unlockTime ) | The $oopsUrl for calling redirectCgiQuery(), user's $loginName , and estimated $unlockTime in minutes. The $oopsUrl and $loginName is empty if topic has no edit lock. |
Since: | TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
Description: | Lock topic for editing, or unlock when done |
Parameter: $web | Web name, e.g. "Main" , or empty |
Parameter: $topic | Topic name, e.g. "MyTopic" , or "Main.MyTopic" |
Parameter: $lock | Set to 1 to lock topic, 0 to unlock |
Return: $oopsUrl | Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case lock is already taken when trying to lock topic |
Since: | TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
Description: | Read topic text, including meta data |
Parameter: $web | Web name, e.g. "Main" , or empty |
Parameter: $topic | Topic name, e.g. "MyTopic" , or "Main.MyTopic" |
Parameter: $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. |
Parameter: $ignorePermissions | Set to "1" if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission |
Return: $text | Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error |
Since: | TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
Description: | 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. |
Parameter: $web | Web name, e.g. "Main" , or empty |
Parameter: $topic | Topic name, e.g. "MyTopic" , or "Main.MyTopic" |
Parameter: $text | Topic text to save, assumed to include meta data |
Parameter: $ignorePermissions | Set to "1" if checkAccessPermission() is already performed and OK |
Parameter: $dontNotify | Set to "1" if not to notify users of the change |
Return: $oopsUrl | Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case of error |
Since: | TWiki::Plugins::VERSION 1.010 (31 Dec 2002) |
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;
}
Description: | 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 (7 Dec 2002) |
Description: | Get list of all topics in a web |
Parameter: $web | Web name, required, e.g. "Sandbox" |
Return: @topics | Topic list, e.g. ( "WebChanges", "WebHome", "WebIndex", "WebNotify" ) |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Expand all common %VARIABLES% |
Parameter: $text | Text with variables to expand, e.g. "Current user is %WIKIUSER%" |
Parameter: $topic | Current topic name, e.g. "WebNotify" |
Parameter: $web | Web name, optional, e.g. "Main" . The current web is taken if missing |
Return: $text | Expanded text, e.g. "Current user is TWikiGuest" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Render text from TWiki markup into XHTML as defined in TWiki.TextFormattingRules |
Parameter: $text | Text to render, e.g. "*bold* text and =fixed font=" |
Parameter: $web | Web name, optional, e.g. "Main" . The current web is taken if missing |
Return: $text | XHTML text, e.g. "<b>bold</b> and <code>fixed font</code>" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | 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() |
Parameter: $pre | Text occuring before the TWiki link syntax, optional |
Parameter: $web | Web name, required, e.g. "Main" |
Parameter: $topic | Topic name to link to, required, e.g. "WebNotify" |
Parameter: $label | Link label, required. Usually the same as $topic , e.g. "notify" |
Parameter: $anchor | Anchor, optional, e.g. "#Jump" |
Parameter: $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 |
Return: $text | XHTML anchor, e.g. "<a href="/cgi-bin/view/Main/WebNotify#Jump">notify</a>" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | This is not a function, just a how-to note. Use: expandCommonVariables("%SEARCH{...}%" ); |
Parameter: $text | Search variable |
Return: $text | Search result in TWiki.FormattedSearch format |
Description: | Format the time in seconds into the desired time string |
Parameter: $time | Time in epoc seconds |
Parameter: $format | Format type, optional. Default e.g. " TWiki::Plugins::VERSION 1.010 (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" ) |
Parameter: $timezone | either not defined (uses the displaytime setting), "gmtime", or "servertime" |
Return: $text | Formatted time string |
Note: | if you used the removed formatGmTime, add a third parameter "gmtime" |
Since: | TWiki::Plugins::VERSION 1.020 (26 Feb 2004) |
NOTE: | This function is deprecated and should not be used. Use formatTime() instead |
Description: | Format the time to GM time |
Parameter: $time | Time in epoc seconds |
Parameter: $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" ) |
Return: $text | Formatted time string |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Get data directory (topic file root) |
Return: $dir | Data directory, e.g. "/twiki/data" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName |
Return: $dir | Pub directory, e.g. "/htdocs/twiki/pub" |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
NOTE: | The following function is deprecated and should not be used. Use readTopicText() instead |
Description: | Read topic text and meta data, regardless of access permissions. |
Parameter: $web | Web name, required, e.g. "Main" |
Parameter: $topic | Topic name, required, e.g. "TokyoOffice" |
Return: ( $meta, $text ) | Meta data object and topic text |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Read a template or skin file. Embedded template directives get expanded |
Parameter: $name | Template name, e.g. "view" |
Parameter: $skin | Skin name, optional, e.g. "print" |
Return: $text | Template text |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Read text file, low level. NOTE: For topics use readTopicText() |
Parameter: $filename | Full path name of file |
Return: $text | Content of file |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
Description: | Save text file, low level. NOTE: For topics use saveTopicText() |
Parameter: $filename | Full path name of file |
Parameter: $text | Text to save |
Return: | none |
Since: | TWiki::Plugins::VERSION 1.000 (7 Dec 2002) |
TODO: | This should return an error for the different failure modes. |
Description: | Log Warning that may require admin intervention to data/warning.txt |
Parameter: $text | Text to write; timestamp gets added |
Return: | none |
Since: | TWiki::Plugins::VERSION 1.020 (16 Feb 2004) |
Description: | Log debug message to data/debug.txt |
Parameter: $text | Text to write; timestamp gets added |
Return: | none |
Since: | TWiki::Plugins::VERSION 1.020 (16 Feb 2004) |
Description: | Retrieves a TWiki predefined regular expression |
Parameter: $regexName | Name of the regular expression to retrieve. See notes below |
Return: | String or precompiled regular expression matching as described below |
Since: | TWiki::Plugins::VERSION 1.020 (9 Feb 2004) |
Name | Matches | CC |
---|---|---|
upperAlpha | Upper case characters | Y |
lowerAlpha | Lower case characters | Y |
mixedAlpha | Alphabetic characters | Y |
mixedAlphaNum | Alphanumeric charactecs | Y |
wikiWordRegex | WikiWords | N |
my $upper = TWiki::Func::getRegularExpression("upperAlpha"); my $alpha = TWiki::Func::getRegularExpression("mixedAlpha"); my $capitalized = qr/[$upper][$alpha]+/;
Description: | Checks a list of Perl dependencies at runtime |
Parameter: $moduleName | Context description e.g. name of the module being checked |
Parameter: $dependenciesRef | Reference of list of hashes containing dependency information; see notes below |
Return: $error | undef if dependencies are OK, an error message otherwise |
Since: | TWiki::Plugins::VERSION 1.025 (01 Aug 2004) |
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 } }
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