Package TWiki::Func
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 6.02. This can be shown
by the
%PLUGINVERSION%
TWiki variable, and accessed in code using
$TWiki::Plugins::VERSION
. The 'Since' field in the function
documentation refers to
$TWiki::Plugins::VERSION
.
Notes on use of
$TWiki::Plugins::VERSION
(from 1.2 forwards):
- If the major version (e.g.
1.
) is the same then any plugin coded to use any earlier revision of the 1.
API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to require plugins to be recoded.
- If the minor version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, deprecation of functions in the interface trigger a minor version increment. Note that deprecated functions are not removed, they are merely frozen, and plugin authors are recommended to stop using them.
- Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.
-
TWiki::Plugins::VERSION
also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of TWiki::Plugins::VERSION
it relates to.
A full history of the changes to this API can be found at the end of this
topic.
On this page:
- Environment
- Preferences
- User Handling and Access Control
- Webs, Topics and Attachments
- getListOfWebs( $filter ) -> @webs
- webExists( $web ) -> $boolean
- createWeb( $newWeb, $baseWeb, $opts )
- moveWeb( $oldName, $newName )
- eachChangeSince($web, $time) -> $iterator
- getTopicList( $web ) -> @topics
- topicExists( $web, $topic ) -> $boolean
- checkTopicEditLock( $web, $topic, $script ) -> ( $oopsUrl, $loginName, $unlockTime )
- setTopicEditLock( $web, $topic, $lock )
- saveTopic( $web, $topic, $meta, $text, $options ) -> $error
- saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $oopsUrl
- moveTopic( $web, $topic, $newWeb, $newTopic )
- getRevisionInfo($web, $topic, $rev, $attachment ) -> ( $date, $user, $rev, $comment )
- getRevisionAtTime( $web, $topic, $time ) -> $rev
- readTopic( $web, $topic, $rev ) -> ( $meta, $text )
- readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $text
- attachmentExists( $web, $topic, $attachment ) -> $boolean
- readAttachment( $web, $topic, $name, $rev ) -> $data
- saveAttachment( $web, $topic, $attachment, $opts )
- moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )
- Assembling Pages
- readTemplate( $name, $skin ) -> $text
- loadTemplate ( $name, $skin, $web ) -> $text
- expandTemplate( $def ) -> $string
- writeHeader( $query, $contentLength )
- redirectCgiQuery( $query, $url, $passthru )
- addToHEAD( $id, $header )
- expandCommonVariables( $text, $topic, $web, $meta ) -> $text
- renderText( $text, $web ) -> $text
- internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text
- E-mail
- Creating New Topics
- Special handlers
- Searching
- Plugin-specific file handling
- General Utilities
- StaticMethod sanitizeAttachmentName ($fname) -> ($fileName,$origName)
- Deprecated functions
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: