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.
saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $oopsUrlSave 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.
$oopsUrl Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case of error
This method is a lot less efficient and much more dangerous than 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 )
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 )Get revision info of a topic or attachment
( $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" )
NOTE: if you are trying to get revision info for a topic, use
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 ) -> $revGet the revision number of a topic at a specific time.
Since: TWiki::Plugins::VERSION 1.1
readTopic( $web, $topic, $rev ) -> ( $meta, $text )Read topic text and meta data, regardless of access permissions.
( $meta, $text ) Meta data object and topic text
This method ignores topic access permissions. You should be careful to use Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $textRead topic text, including meta data
$text Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
This method is more efficient than Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
attachmentExists( $web, $topic, $attachment ) -> $booleanTest if attachment exists
normalizeWebTopicName .
Since: TWiki::Plugins::VERSION 1.1
readAttachment( $web, $topic, $name, $rev ) -> $data
readTopic . If the attachment does not exist, or cannot be read, undef
will be returned. If the revision is not specified, the latest version will
be returned.
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 current user.
my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic ); my @attachments = $meta->find( 'FILEATTACHMENT' ); foreach my $a ( @attachments ) { try { my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} ); ... } catch TWiki::AccessControlException with { }; } Since: TWiki::Plugins::VERSION 1.1
saveAttachment( $web, $topic, $attachment, $opts )
$opts may include:
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 )
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 ) -> $textRead a template or skin. Embedded template directives get expanded
$text Template text
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
loadTemplate ( $name, $skin, $web ) -> $text
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 ) -> $stringDo a , only expanding the template (not expanding any variables other than %TMPL)
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
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
redirectCgiQuery( $query, $url, $passthru )Redirect to URL
Return: none Print output to STDOUT that will cause a 302 redirect to a new URL. Nothing more should be printed to STDOUT after this method has been called.
The
Note that if my $query = TWiki::Func::getCgiQuery(); $query->param(-name => 'text', -value => 'Different text'); TWiki::Func::redirectCgiQuery( undef, TWiki::Func::getScriptUrl($web, $topic, 'edit'), 1); $passthru does nothing if $url does not point to a script in the current
TWiki installation.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
addToHEAD( $id, $header )
Adds
All TWiki variables present in
Note that this is not the same as the HTTP header, which is modified through the Plugins 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
$text Expanded text, e.g. 'Current user is TWikiGuest'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002) See also: expandVariablesOnTopicCreation
renderText( $text, $web ) -> $textRender text from TWiki markup into XHTML as defined in TWiki.TextFormattingRules
$text XHTML text, e.g. '<b>bold</b> and <code>fixed font</code>'
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
$text XHTML anchor, e.g. '<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
sendEmail ( $text, $retries ) -> $error
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. PeasantLeave a blank line between the last header field and the message body. Since: TWiki::Plugins::VERSION 1.1
wikiToEmail( $wikiName ) -> $email
Since: TWiki::Plugins::VERSION 1.1
Creating New Topics
expandVariablesOnTopicCreation ( $text ) -> $textExpand the limited set of variables that are always expanded during topic creation
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:
See also: expandVariables
Special handlersSpecial handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.
registerTagHandler( $var, \&fn, $syntax )Should only be called from initPlugin.
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
Since: TWiki::Plugins::VERSION 1.1 The variable handler function must be of the form: sub handler(\%session, \%params, $topic, $web)where:
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; } }would let you do this: %EXEC{"ps -Af" silent="on"}%
Registered tags differ from tags implemented using the old TWiki approach (text substitution in
registerRESTHandler( $alias, \&fn, )Should only be called from initPlugin. Adds a function to the dispatch table of the REST interface
Since: TWiki::Plugins::VERSION 1.1 The handler function must be of the form: sub handler(\%session)where:
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
note that the URL
(ie, with the name of the function instead of the alias) will not work.
Searching
searchInWebContent($searchString, $web, \@topics, \%options ) -> \%mapSearch for a string in the content of a web. The search is over all content, including meta-data. Meta-data matches will be returned as formatted lines within the topic content (meta-data matches are returned as lines of the format %META:\w+{.*}%)
\%options hash may contain the following options:
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 ) -> $directorypathGets 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 ) -> $textRead file, low level. Used for Plugin workarea.
$text Content of file, empty if not found
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.
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 ) -> $exprRetrieves a TWiki predefined regular expression or character class.
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]+/;Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example: 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.
Since: TWiki::Plugins::VERSION 1.1
Note that hierarchical web names (SubWeb? ) are only available if hierarchical webs are enabled in The symbols %USERSWEB%, %SYSTEMWEB%, %DOCWEB%, %MAINWEB% and %TWIKIWEB% can be used in the input to represent the web names set in $cfg{UsersWebName} and $cfg{SystemWebName}. For example:
writeWarning( $text )Log Warning that may require admin intervention to data/warning.txt
Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
writeDebug( $text )Log debug message to data/debug.txt
Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
formatTime( $time, $format, $timezone ) -> $textFormat the time in seconds into the desired time string
$text Formatted time string
Since: TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
isValidWikiWord ( $text ) -> $booleanCheck for a valid WikiWord or WikiName
Since: TWiki::Plugins::VERSION 1.100 (Dec 2005)
extractParameters($attr ) -> %paramsExtract all parameters from a variable string and returns a hash of parameters
%params Hash containing all parameters. The nameless parameter is stored in key _DEFAULT
Since: TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
extractNameValuePair( $attr, $name ) -> $valueExtract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters
$value Extracted value
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
Deprecated functionsFrom 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 package TWiki::Plugins::SinkPlugin; use vars qw( %TWikiCompatibility ); $TWikiCompatibility{endRenderingHandler} = 1.1;If the currently-running TWiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. TWiki with versions of TWiki::Plugins before 1.1 will still call the handler as required.
The following functions are retained for compatibility only. You should stop using them as soon as possible.
getScriptUrlPath( ) -> $pathGet script URL path
DEPRECATED since 1.1 - use
Return: 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
Get list of all public webs, e.g. all webs that do not have the
Return: Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
formatGmTime( $time, $format ) -> $text
DEPRECATED since 1.1 - use Format the time to GM time
$text Formatted time string
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
getDataDir( ) -> $dirDEPRECATED since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead Get data directory (topic file root)
Return: This function violates store encapsulation and is therefore deprecated. Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
getPubDir( ) -> $dirDEPRECATED since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead
Get pub directory (file attachment root). Attachments are in
Return: This function violates store encapsulation and is therefore deprecated.
Use Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
checkDependencies( $moduleName, $dependenciesRef ) -> $errorDEPRECATED 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)
|
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||