| TWiki.Tukro . TWiki . TWikiFuncModule |
| 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 |
| 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 |
| 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 |
| Description: | Get protocol, domain and optional port of script URL |
Return: $host | URL host, e.g. "http://example.com:80" |
| 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" |
| Description: | Get script URL path |
Return: $path | URL path of TWiki scripts, e.g. "/cgi-bin" |
| 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" |
| 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" |
| Description: | Get pub URL path |
Return: $path | URL path of pub directory, e.g. "/pub" |
| 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 |
| Description: | Prints a basic content-type HTML header for text/html to standard out |
Parameter: $query | CGI query object |
| Return: | none |
| Description: | Redirect to URL |
Parameter: $query | CGI query object |
Parameter: $url | URL to redirect to |
| Return: | none, never returns |
| Description: | Extract a named or unnamed value from a variable parameter string |
Parameter: $attr | Attribute string |
Parameter: $name | Name, optional |
Return: $value | Extracted value |
%TEST{ "nameless" name1="val1" name2="val2" }%
{...} to get: "nameless" name1="val1" name2="val2"
my $noname = TWiki::Func::extractNameValuePair( $text ); my $name1 = TWiki::Func::extractNameValuePair( $text, "name1" ); my $name2 = 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 |
* 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 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") |
* Set SHOWHELP = off
"MYPLUGIN_SHOWHELP" for $key
my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );
| Description: | Get toolname as defined in TWiki.cfg |
Return: $name | Name of tool, e.g. "TWiki" |
| Description: | Get name of Main web as defined in TWiki.cfg |
Return: $name | Name, e.g. "Main" |
| Description: | Get name of TWiki documentation web as defined in TWiki.cfg |
Return: $name | Name, e.g. "TWiki" |
| Description: | Get default user name as defined in TWiki.cfg's $defaultUserName |
Return: $loginName | Default user name, e.g. "guest" |
| Description: | Get Wiki name of logged in user |
Return: $wikiName | Wiki Name, e.g. "JohnDoe" |
| Description: | Get Wiki name of logged in user with web prefix |
Return: $wikiName | Wiki Name, e.g. "Main.JohnDoe" |
| 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" |
| 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" |
| Description: | Test if logged in user is a guest |
Return: $flag | "1" if yes, "0" if not |
| 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 |
| 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 |
| Description: | Test if web exists |
Parameter: $web | Web name, required, e.g. "Sandbox" |
Return: $flag | "1" if web exists, "0" if not |
| 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 |
| Description: | Get revision info of a topic |
Parameter: $web | Web name, optional, e.g. "Main" |
Parameter: $topic | Topic name, required, e.g. "TokyoOffice" |
Return: ( $date, $loginName, $rev ) | List with: ( last update date, login name of last user, minor part of top revision number ), e.g. ( "01 Jan 2003", "phoeny", "5" ) |
| 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. |
| 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 |
| 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 |
| 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 |
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" ) |
| 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" ) |
| 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" |
| 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>" |
| 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>" |
| 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 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 |
| Description: | Get data directory (topic file root) |
Return: $dir | Data directory, e.g. "/twiki/data" |
| Description: | Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName |
Return: $dir | Pub directory, e.g. "/htdocs/twiki/pub" |
| 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 |
| Description: | Read text file, low level. NOTE: For topics use readTopicText() |
Parameter: $filename | Full path name of file |
Return: $text | Content of file |
| 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 |
| Description: | Log Warning that may require admin intervention to data/warning.txt |
Parameter: $text | Text to write; timestamp gets added |
| Return: | none |
| Description: | Log debug message to data/debug.txt |
Parameter: $text | Text to write; timestamp gets added |
| Return: | none |
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
----- Revision r1.3 - 02 Feb 2003 - 01:02 - PeterThoeny
|