TWiki . TWiki . TWikiFuncModule (edit)
	Change topic

%TOC% %STARTINCLUDE% ---# TWiki::Func Module Documentation _Official list of stable TWiki functions for Plugin developers_ <noautolink> ---++ Description This module defines official funtions that [[TWiki.TWikiPlugins][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. ---++ Functions: CGI Environment ---+++ getSessionValue( $key ) ==> $value | 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 | ---+++ setSessionValue( $key, $value ) ==> $result | 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 | ---+++ getSkin( ) ==> $skin | 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 | ---+++ getUrlHost( ) ==> $host | Description: | Get protocol, domain and optional port of script URL | | Return: =$host= | URL host, e.g. ="http://example.com:80"= | ---+++ getScriptUrl( $web, $topic, $script ) ==> $url | 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"= | ---+++ getScriptUrlPath( ) ==> $path | Description: | Get script URL path | | Return: =$path= | URL path of TWiki scripts, e.g. ="/cgi-bin"= | ---+++ getViewUrl( $web, $topic ) ==> $url | 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"= | ---+++ getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) ==> $url | 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 %<nop>PARAM1% ... %<nop>PARAM4% variables in template, optional | | Return: =$url= | URL, e.g. ="http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&amp;param1=joe"= | ---+++ getPubUrlPath( ) ==> $path | Description: | Get pub URL path | | Return: =$path= | URL path of pub directory, e.g. ="/pub"= | ---+++ getCgiQuery( ) ==> $query | 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 | ---+++ writeHeader( $query ) | Description: | Prints a basic content-type HTML header for text/html to standard out | | Parameter: =$query= | CGI query object | | Return: | none | ---+++ redirectCgiQuery( $query, $url ) | Description: | Redirect to URL | | Parameter: =$query= | CGI query object | | Parameter: =$url= | URL to redirect to | | Return: | none, never returns | ---++ Functions: Preferences ---+++ extractNameValuePair( $attr, $name ) ==> $value | Description: | Extract a named or unnamed value from a variable parameter string | | Parameter: =$attr= | Attribute string | | Parameter: =$name= | Name, optional | | Return: =$value= | Extracted value | * Example: * Variable: =%<nop>TEST{ "nameless" name1="val1" name2="val2" }%= * First extract text between ={...}= to get: ="nameless" name1="val1" name2="val2"= * Then call this on the text: <br /> =my $noname = TWiki::Func::extractNameValuePair( $text );= <br /> =my $name1 = TWiki::Func::extractNameValuePair( $text, "name1" );= <br /> =my $name2 = TWiki::Func::extractNameValuePair( $text, "name2" );= ---+++ getPreferencesValue( $key, $web ) ==> $value | 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 | * 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" );= ---+++ getPreferencesFlag( $key, $web ) ==> $value | 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"=) | * Example for Plugin setting: * MyPlugin topic has: =* Set SHOWHELP = off= * Use ="MYPLUGIN_SHOWHELP"= for =$key= * =my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );= ---+++ getWikiToolName( ) ==> $name | Description: | Get toolname as defined in TWiki.cfg | | Return: =$name= | Name of tool, e.g. ="TWiki"= | ---+++ getMainWebname( ) ==> $name | Description: | Get name of Main web as defined in TWiki.cfg | | Return: =$name= | Name, e.g. ="Main"= | ---+++ getTwikiWebname( ) ==> $name | Description: | Get name of TWiki documentation web as defined in TWiki.cfg | | Return: =$name= | Name, e.g. ="TWiki"= | ---++ Functions: User Handling and Access Control ---+++ getDefaultUserName( ) ==> $loginName | Description: | Get default user name as defined in TWiki.cfg's =$defaultUserName= | | Return: =$loginName= | Default user name, e.g. ="guest"= | ---+++ getWikiName( ) ==> $wikiName | Description: | Get Wiki name of logged in user | | Return: =$wikiName= | Wiki Name, e.g. ="JohnDoe"= | ---+++ getWikiUserName( $text ) ==> $wikiName | Description: | Get Wiki name of logged in user with web prefix | | Return: =$wikiName= | Wiki Name, e.g. ="Main.JohnDoe"= | ---+++ wikiToUserName( $wikiName ) ==> $loginName | 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"= | ---+++ userToWikiName( $loginName, $dontAddWeb ) ==> $wikiName | 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"= | ---+++ isGuest( ) ==> $flag | Description: | Test if logged in user is a guest | | Return: =$flag= | ="1"= if yes, ="0"= if not | ---+++ permissionsSet( $web ) ==> $flag | 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 | ---+++ checkAccessPermission( $type, $wikiName, $text, $topic, $web ) ==> $flag | 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 | ---++ Functions: Content Handling ---+++ webExists( $web ) ==> $flag | Description: | Test if web exists | | Parameter: =$web= | Web name, required, e.g. ="Sandbox"= | | Return: =$flag= | ="1"= if web exists, ="0"= if not | ---+++ topicExists( $web, $topic ) ==> $flag | 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 | ---+++ getRevisionInfo( $web, $topic ) ==> ( $date, $loginName, $rev ) | 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" )= | ---+++ checkTopicEditLock( $web, $topic ) ==> ( $oopsUrl, $loginName, $unlockTime ) | 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. | ---+++ setTopicEditLock( $web, $topic, $lock ) ==> $oopsUrl | 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 | ---+++ readTopicText( $web, $topic, $rev, $ignorePermissions ) ==> $text | 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 | ---+++ saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) ==> $oopsUrl | 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 | * Example: <br /> =my $oopsUrl = TWiki::Func::setTopicEditLock( $web, $topic, 1 );= <br /> =if( $oopsUrl ) {= <br /> =&nbsp; TWiki::Func::redirectCgiQuery( $query, $oopsUrl ); # assuming valid query= <br /> =&nbsp; return;= <br /> =}= <br /> =my $text = TWiki::Func::readTopicText( $web, $topic ); # read topic text= <br /> =# check for oops URL in case of error:= <br /> =if( $text =~ /^http.*?\/oops/ ) {= <br /> =&nbsp; TWiki::Func::redirectCgiQuery( $query, $text );= <br /> =&nbsp; return;= <br /> =}= <br /> =# do topic text manipulation like:= <br /> =$text =~ s/old/new/g;= <br /> =# do meta data manipulation like:= <br /> =$text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;= <br /> =$oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text= <br /> =TWiki::Func::setTopicEditLock( $web, $topic, 0 ); # unlock topic= <br /> =if( $oopsUrl ) {= <br /> =&nbsp; TWiki::Func::redirectCgiQuery( $query, $oopsUrl );= <br /> =&nbsp; return;= <br /> =}= ---+++ getPublicWebList( ) ==> @webs | 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" )= | ---+++ getTopicList( $web ) ==> @topics | 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" )= | ---++ Functions: Rendering ---+++ expandCommonVariables( $text, $topic, $web ) ==> $text | Description: | Expand all common =%<nop>VARIABLES%= | | Parameter: =$text= | Text with variables to expand, e.g. ="Current user is %<nop>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 <nop>TWikiGuest"= | ---+++ renderText( $text, $web ) ==> $text | 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. ="&lt;b>bold&lt;/b> and &lt;code>fixed font&lt;/code>"= | ---+++ internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) ==> $text | 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;<br /> set to ="0"= to suppress link for non-existing topics | | Return: =$text= | XHTML anchor, e.g. ="&lt;a href="/cgi-bin/view/Main/WebNotify#Jump">notify&lt;/a>"= | ---+++ search text( $text ) ==> $text | Description: | This is not a function, just a how-to note. Use: =expandCommonVariables("%<nop>SEARCH{...}%" );= | | Parameter: =$text= | Search variable | | Return: ="$text"= | Search result in [[TWiki.FormattedSearch]] format | ---+++ formatGmTime( $time, $format ) ==> $text | 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 | ---++ Functions: File I/O ---+++ getDataDir( ) ==> $dir | Description: | Get data directory (topic file root) | | Return: =$dir= | Data directory, e.g. ="/twiki/data"= | ---+++ getPubDir( ) ==> $dir | Description: | Get pub directory (file attachment root). Attachments are in =$dir/Web/TopicName= | | Return: =$dir= | Pub directory, e.g. ="/htdocs/twiki/pub"= | ---+++ readTemplate( $name, $skin ) ==> $text | Description: | Read a template or skin file. Embedded [[TWiki.TWikiTemplates][template directives]] get expanded | | Parameter: =$name= | Template name, e.g. ="view"= | | Parameter: =$skin= | Skin name, optional, e.g. ="print"= | | Return: =$text= | Template text | ---+++ readFile( $filename ) ==> $text | Description: | Read text file, low level. NOTE: For topics use readTopicText() | | Parameter: =$filename= | Full path name of file | | Return: =$text= | Content of file | ---+++ saveFile( $filename, $text ) | 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 | ---+++ writeWarning( $text ) | Description: | Log Warning that may require admin intervention to data/warning.txt | | Parameter: =$text= | Text to write; timestamp gets added | | Return: | none | ---+++ writeDebug( $text ) | Description: | Log debug message to data/debug.txt | | Parameter: =$text= | Text to write; timestamp gets added | | Return: | none | ---++ Copyright and License Copyright (C) 2000-2003 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 </noautolink> __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 <nop>PerlDocPlugin and replace above text with =%<nop>PERLDOC{"TWiki::Func"}%=. -- Main.PeterThoeny - 31 Dec 2002 %STOPINCLUDE%
Don't forget - if you change something, do it in GoodStyle and follow the TextFormattingRules.
-- Main.TWikiGuest - 22 Jan 2025   <== This is your signature for easy copy & paste operation

Topic TWikiFuncModule . { | Cancel edit }

Copyright © 1999-2003 by the contributing authors. All material on this collaboration platform is the property of the contributing authors. Ideas, requests, problems regarding TWiki? Send feedback.