Line: 1 to 1 | ||||||||
---|---|---|---|---|---|---|---|---|
Package
| ||||||||
Line: 487 to 488 | ||||||||
isGuest( ) -> $boolean | ||||||||
Changed: | ||||||||
< < | Test if logged in user is a guest (TWikiGuest) | |||||||
> > | Trash/Test if logged in user is a guest (TWikiGuest) | |||||||
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002) | ||||||||
Line: 642 to 643 | ||||||||
webExists( $web ) -> $boolean | ||||||||
Changed: | ||||||||
< < | Test if web exists | |||||||
> > | Trash/Test if web exists | |||||||
| ||||||||
Line: 740 to 741 | ||||||||
topicExists( $web, $topic ) -> $boolean | ||||||||
Changed: | ||||||||
< < | Test if topic exists | |||||||
> > | Trash/Test if topic exists | |||||||
| ||||||||
Line: 935 to 936 | ||||||||
attachmentExists( $web, $topic, $attachment ) -> $boolean | ||||||||
Changed: | ||||||||
< < | Test if attachment exists | |||||||
> > | Trash/Test if attachment exists | |||||||
| ||||||||
Line: 1717 to 1718 | ||||||||
permissionsSet( $web ) -> $boolean | ||||||||
Changed: | ||||||||
< < | Test if any access restrictions are set for this web, ignoring settings on | |||||||
> > | Trash/Test if any access restrictions are set for this web, ignoring settings on | |||||||
individual pages
|
Line: 1 to 1 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Added: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
> > | Package
|
code() |
message() |
header($field) |
content() |
is_error() |
is_redirect() |
require LWP
.
is_error()
will return
true, code()
will return a valid HTTP status code
as specified in RFC 2616 and RFC 2518, and message()
will return the
message that was received from
the server. In the event of a client-side error (e.g. an unparseable URL)
then is_error()
will return true and message()
will return an explanatory
message. code()
will return 400 (BAD REQUEST).
Note: Callers can easily check the availability of other HTTP::Response methods
as follows:
my $response = TWiki::Func::getExternalResource($url); if (!$response->is_error() && $response->isa('HTTP::Response')) { ... other methods of HTTP::Response may be called } else { ... only the methods listed above may be called }Since: TWiki::Plugins::VERSION 1.2
$query
CGI query object; or 0 if script is called as a shell script
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
setSessionValue
and
getSessionValue
.
Since: TWiki::Plugins::VERSION 1.2
$key
- Session key
$value
Value associated with key; empty string if not set
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 200)
$key
- Session key
$value
- Value associated with key
setSessionValue
. $key
- name of value stored in session to be cleared. Note that you cannot clear AUTHUSER
.
sub initPlugin { TWiki::Func::getContext()->{'MyID'} = 1; ...This can be used in SecondPlugin.pm like this:
sub initPlugin { if( TWiki::Func::getContext()->{'MyID'} ) { ... } ...or in a template, like this:
%TMPL:DEF{"ON"}% Not off %TMPL:END% %TMPL:DEF{"OFF"}% Not on %TMPL:END% %TMPL:P{context="MyID" then="ON" else="OFF"}%or in a topic:
%IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%Note: all plugins have an automatically generated context identifier if they are installed and initialised. For example, if the FirstPlugin is working, the context ID 'FirstPlugin' will be set. Since: TWiki::Plugins::VERSION 1.1
$web
- new web
$topic
- new topic
$web.$topic
from now on. All the preferences will be reset to those of the new topic.
Note that if the new topic is not readable by the logged in user due to
access control considerations, there will not be an exception. It is the
duty of the caller to check access permissions before changing the topic.
It is the duty of the caller to restore the original context by calling
popTopicContext
.
Note that this call does not re-initialise plugins, so if you have used
global variables to remember the web and topic in initPlugin
, then those
values will be unchanged.
Since: TWiki::Plugins::VERSION 1.2
pushTopicContext
was called.
Since: TWiki::Plugins::VERSION 1.2
$key
- Preferences key
$web
- Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
$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' );
$NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
$key
- Plugin Preferences key w/o PLUGINNAME_ prefix.
$value
Preferences value; empty string if not set
Note: This function will will only work when called from the Plugin.pm file itself. it will not work if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)
Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
NOTE: As of TWiki4.1, if $NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
$key
- Preferences key
$web
- Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
$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" );
$NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
$key
- Plugin Preferences key w/o PLUGINNAME_ prefix.
"off"
, "no"
and "0"
, or values not set at all. True otherwise.
Note: This function will will only work when called from the Plugin.pm file itself. it will not work if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)
Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
NOTE: As of TWiki4.1, if $NO_PREFS_IN_TOPIC
is enabled in the plugin, then
preferences set in the plugin topic will be ignored.
%$name%
will expand to the preference when used in
future variable expansions.
The preference only persists for the rest of this request. Finalised
preferences cannot be redefined using this function.
Returns 1 if the preference was defined, and 0 otherwise.
$name
Name of tool, e.g. 'TWiki'
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$name
Name, e.g. 'Main'
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$name
Name, e.g. 'TWiki'
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
DefaultUserLogin
Return: $loginName
Default user name, e.g. 'guest'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$user
can be a login, wikiname or web.wikiname
$cUID
, an internal unique and portable escaped identifier for
registered users. This may be autogenerated for an authenticated but
unregistered user.
Since: TWiki::Plugins::VERSION 1.2
$wikiName
Wiki Name, e.g. 'JohnDoe'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$wikiName
Wiki Name, e.g. "Main.JohnDoe"
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$id
- Wiki name, e.g. 'Main.JohnDoe'
or 'JohnDoe'
. Since TWiki 4.2.1, $id may also be a login name. This will normally be transparent, but should be borne in mind if you have login names that are also legal wiki names.
$loginName
Login name of user, e.g. 'jdoe'
, or undef if not
matched.
Note that it is possible for several login names to map to the same wikiname.
This function will only return the first login name that maps to the
wikiname.
returns undef if the WikiName is not found.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$loginName
- Login name, e.g. 'jdoe'
. Since TWiki 4.2.1 this may also be a wiki name. This will normally be transparent, but may be relevant if you have login names that are also valid wiki names.
$dontAddWeb
- Do not add web prefix if "1"
$wikiName
Wiki name of user, e.g. 'Main.JohnDoe'
or 'JohnDoe'
userToWikiName will always return a name. If the user does not
exist in the mapping, the $loginName parameter is returned. (backward compatibility)
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$email
- email address to look up
$dontAddWeb
- Do not add web prefix if "1"
$user
- wikiname of user to look up
if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) { ... }If
$user
is undef
, it defaults to the currently logged-in user.
my $iterator = TWiki::Func::eachUser(); while ($it->hasNext()) { my $user = $it->next(); # $user is a wikiname }WARNING on large sites, this could be a long list! Since: TWiki::Plugins::VERSION 1.2
$id
- WikiName or login name of the user. If $id
is undef
, defaults to the currently logged-in user.
my $iterator = TWiki::Func::eachGroup(); while ($it->hasNext()) { my $group = $it->next(); # $group is a group name e.g. TWikiAdminGroup }WARNING on large sites, this could be a long list! Since: TWiki::Plugins::VERSION 1.2
$group
is the name of a group known to TWiki.
my $iterator = TWiki::Func::eachGroupMember('RadioheadGroup'); while ($it->hasNext()) { my $user = $it->next(); # $user is a wiki name e.g. 'TomYorke', 'PhilSelway' }WARNING on large sites, this could be a long list! Since: TWiki::Plugins::VERSION 1.2
$type
- Access type, required, e.g. 'VIEW'
, 'CHANGE'
.
$id
- WikiName of remote user, required, e.g. "PeterThoeny"
. From TWiki 4.2.1, $id may also be a login name. If $id
is '', 0 or undef
then access is always permitted.
$text
- Topic text, optional. If 'perl false' (undef, 0 or ''), topic $web.$topic
is consulted. $text
may optionally contain embedded %META:PREFERENCE
tags. Provide this parameter if: $meta
parameter.
$topic
- Topic name, required, e.g. 'PrivateStuff'
$web
- Web name, required, e.g. 'Sandbox'
$meta
- Meta-data object, as returned by readTopic
. Optional. If undef
, but $text
is defined, then access controls will be parsed from $text
. If defined, then metadata embedded in $text
will be ignored. This parameter is always ignored if $text
is undefined. Settings in $meta
override Set
settings in $text.
ThatWeb.ThisTopic
, then a call to checkAccessPermission('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)
will return true
.
Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
$filter
- spec of web types to recover
$filter
may also contain the word 'public' which will further filter
out webs that have NOSEARCHALL set on them.
'allowed' filters out webs the current user can't read.
For example, the deprecated getPublicWebList function can be duplicated
as follows:
my @webs = TWiki::Func::getListOfWebs( "user,public" );Since: TWiki::Plugins::VERSION 1.1
$web
- Web name, required, e.g. 'Sandbox'
$newWeb
is the name of the new web.
$baseWeb
is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.
$opts
is a ref to a hash that contains settings to be modified in
use Error qw( :try ); use TWiki::AccessControlException; try { TWiki::Func::createWeb( "Newweb" ); } 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 { ... };Since: TWiki::Plugins::VERSION 1.1
use Error qw( :try ); use TWiki::AccessControlException; try { TWiki::Func::moveWeb( "Oldweb", "Newweb" ); } 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 { ... };To delete a web, move it to a subweb of
Trash
TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );Since: TWiki::Plugins::VERSION 1.1
$time
and now. $time is a time in seconds since 1st Jan 1970, and is not
guaranteed to return any changes that occurred before (now -
{Store}{RememberChangesFor}). {Store}{RememberChangesFor}) is a
setting in configure
. Changes are returned in most-recent-first
order.
Use it as follows:
my $iterator = TWiki::Func::eachChangeSince( $web, time() - 7 * 24 * 60 * 60); # the last 7 days while ($iterator->hasNext()) { my $change = $iterator->next(); # $change is a perl hash that contains the following fields: # topic => topic name # user => wikiname - wikiname of user who made the change # time => time of the change # revision => revision number *after* the change # more => more info about the change (e.g. 'minor') }
$web
- Web name, required, e.g. 'Sandbox'
@topics
Topic list, e.g. ( 'WebChanges', 'WebHome', 'WebIndex', 'WebNotify' )
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, optional, e.g. 'Main'
.
$topic
- Topic name, required, e.g. 'TokyoOffice'
, or "Main.TokyoOffice"
normalizeWebTopicName
.
Specifically, the Main is used if $web is not specified and $topic has no web specifier.
To get an expected behaviour it is recommened to specify the current web for $web; don't leave it empty.
Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
$web
Web name, e.g. "Main"
, or empty
$topic
Topic name, e.g. "MyTopic"
, or "Main.MyTopic"
( $oopsUrl, $loginName, $unlockTime )
- The $oopsUrl
for calling redirectCgiQuery(), user's $loginName
, and estimated $unlockTime
in minutes, or ( '', '', 0 ) if no lease exists. $script
The script to invoke when continuing with the edit
$web
Web name, e.g. "Main"
, or empty
$topic
Topic name, e.g. "MyTopic"
, or "Main.MyTopic"
$lock
1 to lease the topic, 0 to clear an existing lease
edit
script
always takes out a lease.
It is impossible to fully lock a topic. Concurrent changes will be
merged.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
$web
- web for the topic
$topic
- topic name
$meta
- reference to TWiki::Meta object
$text
- text of the topic (without embedded meta-data!!!
\%options
- ref to hash of save options \%options
may include: dontlog | don't log this change in twiki log |
forcenewrevision | force the save to increment the revision counter |
minor | True if this is a minor change, and is not to be notified |
my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic ) $text =~ s/APPLE/ORANGE/g; TWiki::Func::saveTopic( $web, $topic, $meta, $text, { forcenewrevision => 1 } );Note: Plugins handlers ( e.g.
beforeSaveHandler
) will be called as
appropriate.
$web
- Web name, e.g. 'Main'
, or empty
$topic
- Topic name, e.g. 'MyTopic'
, or "Main.MyTopic"
$text
- Topic text to save, assumed to include meta data
$ignorePermissions
- Set to "1"
if checkAccessPermission() is already performed and OK
$dontNotify
- Set to "1"
if not to notify users of the change
$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 saveTopic
.
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
$web
source web - required
$topic
source topic - required
$newWeb
dest web
$newTopic
dest topic
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 { ... };
$web
- Web name, optional, e.g. 'Main'
$topic
- Topic name, required, e.g. 'TokyoOffice'
$rev
- revsion number, or tag name (can be in the format 1.2, or just the minor number)
$attachment
-attachment filename
( $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 | Wiki name of the author (not login name) |
$rev | actual rev number |
$comment | WHAT COMMENT? |
$meta->getRevisionInfo
instead if you can - it is significantly
more efficient.
Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
$web
- web for topic
$topic
- topic
$time
- time (in epoch secs) for the rev
$web
- Web name, required, e.g. 'Main'
$topic
- Topic name, required, e.g. 'TokyoOffice'
$rev
- revision to read (default latest)
( $meta, $text )
Meta data object and topic text
$meta
is a perl 'object' of class TWiki::Meta
. This class is
fully documented in the source code documentation shipped with the
release, or can be inspected in the lib/TWiki/Meta.pm
file.
This method ignores topic access permissions. You should be careful to use
checkAccessPermission
to ensure the current user has read access to the
topic.
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, e.g. 'Main'
, or empty
$topic
- Topic name, e.g. 'MyTopic'
, or "Main.MyTopic"
$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.
$ignorePermissions
- Set to "1"
if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
$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 readTopic
, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer.
Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
$web
- Web name, optional, e.g. Main
.
$topic
- Topic name, required, e.g. TokyoOffice
, or Main.TokyoOffice
$attachment
- attachment name, e.g.=logo.gif=
normalizeWebTopicName
.
Since: TWiki::Plugins::VERSION 1.1
$web
- web for topic
$topic
- topic
$name
- attachment name
$rev
- revision to read (default latest)
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
$web
- web for topic
$topic
- topic to atach to
$attachment
- name of the attachment
$opts
- Ref to hash of options
$opts
may include:
dontlog |
don't log this change in twiki log |
comment |
comment for save |
hide |
if the attachment is to be hidden in normal topic view |
stream |
Stream of file to upload |
file |
Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. |
filepath |
Client path to file |
filesize |
Size of uploaded data |
filedate |
Date |
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
$web
source web - required
$topic
source topic - required
$attachment
source attachment - required
$newWeb
dest web
$newTopic
dest topic
$newAttachment
dest attachment
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
$name
- Template name, e.g. 'view'
$skin
- Comma-separated list of skin names, optional, e.g. 'print'
$text
Template text
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$name
- template file name
$skin
- comma-separated list of skins to use (default: current skin)
$web
- the web to look in for topics that contain templates (default: current web)
$def
- template name
$query
and $contentLength
parameters. Both were marked "you should not pass this parameter".
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$query
- CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
$url
- URL to redirect to
$passthru
- enable passthrough.
$passthru
parameter allows you to pass the parameters that were passed
to the current query on to the target URL, as long as it is another URL on the
same TWiki installation. If $passthru
is set to a true value, then TWiki
will save the current URL parameters, and then try to restore them on the
other side of the redirect. Parameters are stored on the server in a cache
file.
Note that if $passthru
is set, then any parameters in $url
will be lost
when the old parameters are restored. if you want to change any parameter
values, you will need to do that in the current CGI query before redirecting
e.g.
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)
$header
to the HTML header (the tag).
This is useful for Plugins that want to include some javascript custom css. $id
- Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN_JSCALENDAR)
$header
- the HTML to be added to the section. The HTML must be valid in a HEAD tag - no checks are performed.
requires
optional, comma-separated list of id's of other head blocks this one depends on.
$header
will be expanded before being inserted into the
section.
Note that this is not the same as the HTTP header, which is modified through the Plugins modifyHeaderHandler
.
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" />');
%VARIABLES%
$text
- Text with variables to expand, e.g. 'Current user is %WIKIUSER%'
$topic
- Current topic name, e.g. 'WebNotify'
$web
- Web name, optional, e.g. 'Main'
. The current web is taken if missing
$meta
- topic meta-data to use while expanding (Since TWiki::Plugins::VERSION 1.2)
$text
Expanded text, e.g. 'Current user is TWikiGuest'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
See also: expandVariablesOnTopicCreation
$text
- Text to render, e.g. '*bold* text and =fixed font='
$web
- Web name, optional, e.g. 'Main'
. The current web is taken if missing
$text
XHTML text, e.g. '<b>bold</b> and <code>fixed font</code>'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
renderText()
$pre
- Text occuring before the TWiki link syntax, optional
$web
- Web name, required, e.g. 'Main'
$topic
- Topic name to link to, required, e.g. 'WebNotify'
$label
- Link label, required. Usually the same as $topic
, e.g. 'notify'
$anchor
- Anchor, optional, e.g. '#Jump'
$createLink
- Set to '1'
to add question linked mark after topic name if topic does not exist;'0'
to suppress link for non-existing topics
$text
XHTML anchor, e.g. '<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$text
- text of the mail, including MIME headers
$retries
- number of times to retry the send (default 1)
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
$wikiname
- wiki name of the user
$text
- the text to process
%DATE%
Signature-format date
%SERVERTIME%
See TWikiVariables
%GMTIME%
See TWikiVariables
%USERNAME%
Base login name
%WIKINAME%
Wiki name
%WIKIUSERNAME%
Wiki name with prepended web
%URLPARAM{...}%
- Parameters to the current CGI query
%NOP%
No-op
commonTagsHandler
. $var
- The name of the variable, i.e. the 'MYVAR' part of %MYVAR%. The variable name must match /^[A-Z][A-Z0-9_]*$/ or it won't work.
\&fn
- Reference to the handler function.
$syntax
can be 'classic' (the default) or 'context-free'. 'classic' syntax is appropriate where you want the variable to support classic TWiki syntax i.e. to accept the standard %MYVAR{ "unnamed" param1="value1" param2="value2" }%
syntax, as well as an unquoted default parameter, such as %MYVAR{unquoted parameter}%
. If your variable will only use named parameters, you can use 'context-free' syntax, which supports a more relaxed syntax. For example, %MYVAR{param1=value1, value 2, param3="value 3", param4='value 5"}%
sub handler(\%session, \%params, $topic, $web)where:
\%session
- a reference to the TWiki session object (may be ignored)
\%params
- a reference to a TWiki::Attrs object containing parameters. This can be used as a simple hash that maps parameter names to values, with _DEFAULT being the name for the default parameter.
$topic
- name of the topic in the query
$web
- name of the web in the query
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 commonTagsHandler
) in the following ways: commonTagsHandler
is only called later, when all system tags have already been expanded (though they are expanded again after commonTagsHandler
returns).
FRED
defines both %FRED{...}%
and also %FRED%
.
return '%SERVERTIME%';
). It won't work.
$alias
- The name .
\&fn
- Reference to the function.
sub handler(\%session)where:
\%session
- a reference to the TWiki session object (may be ignored)
TWiki::Func::registerRESTHandler('example', \&restExample);This adds the
restExample
function to the REST dispatch table
for the EmptyPlugin under the 'example' alias, and allows it
to be invoked using the URL
http://server:port/bin/rest/EmptyPlugin/example
note that the URL
http://server:port/bin/rest/EmptyPlugin/restExample
(ie, with the name of the function instead of the alias) will not work.
format
parameters that are used to block evaluation of paramater strings.
For example, if you were to write
%MYTAG{format="%WURBLE%"}%
then %WURBLE would be expanded before %MYTAG is evaluated. To avoid
this TWiki uses escapes in the format string. For example:
%MYTAG{format="$percntWURBLE$percnt"}%
This lets you enter arbitrary strings into parameters without worrying that
TWiki will expand them before your plugin gets a chance to deal with them
properly. Once you have processed your tag, you will want to expand these
tokens to their proper value. That's what this function does.
Escape: | Expands To: |
---|---|
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". |
$quot |
Double quote (" ) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$searchString
- the search string, in egrep format
$web
- The web to search in
\@topics
- reference to a list of topics to search
\%option
- reference to an options hash
\%options
hash may contain the following options: type
- if regex
will perform a egrep-syntax RE search (default '')
casesensitive
- false to ignore case (defaulkt true)
files_without_match
- true to return files only (default false). If files_without_match
is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).
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}} ) { ...etcSince: TWiki::Plugins::VERSION 1.1
$filename
- Full path name of file
$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)
$filename
- Full path name of file
$text
- Text to save
$name
- Name of the expression to retrieve. See notes below
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/ );
Name | Matches | Type |
---|---|---|
upperAlpha | Upper case characters | String |
upperAlphaNum | Upper case characters and digits | String |
lowerAlpha | Lower case characters | String |
lowerAlphaNum | Lower case characters and digits | String |
numeric | Digits | String |
mixedAlpha | Alphabetic characters | String |
mixedAlphaNum | Alphanumeric characters | String |
wikiWordRegex | WikiWords | RE |
webNameRegex | User web names | RE |
anchorRegex | #AnchorNames | RE |
abbrevRegex | Abbreviations e.g. GOV, IRS | RE |
emailAddrRegex | email@address.com | RE |
tagNameRegex | Standard variable names e.g. %THIS_BIT% (THIS_BIT only) | RE |
$web
- Web name, identifying variable, or empty string
$topic
- Topic name, may be a web.topic string, required.
Input | Return |
---|---|
( 'Web', 'Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Topic' ) | ( 'Main', 'Topic' ) |
( '', '' ) | ( 'Main', 'WebHome' ) |
( '', 'Web/Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Web/Subweb/Topic' ) | ( 'Web/Subweb', 'Topic' ) |
( '', 'Web.Topic' ) | ( 'Web', 'Topic' ) |
( '', 'Web.Subweb.Topic' ) | ( 'Web/Subweb', 'Topic' ) |
( 'Web1', 'Web2.Topic' ) | ( 'Web2', 'Topic' ) |
configure
.
The symbols %USERSWEB%, %SYSTEMWEB% and %DOCWEB% can be used in the input to represent the web names set in $cfg{UsersWebName} and $cfg{SystemWebName}. For example:
Input | Return |
---|---|
( '%USERSWEB%', 'Topic' ) | ( 'Main', 'Topic' ) |
( '%SYSTEMWEB%', 'Topic' ) | ( 'TWiki', 'Topic' ) |
( '', '%DOCWEB%.Topic' ) | ( 'TWiki', 'Topic' ) |
$pre
- Arbitrary Text
$text
Since: TWiki::Plugins::VERSION 1.3 (18 Jan 2010)
$text
- Text to write; timestamp gets added
$text
- Text to write; timestamp gets added
$time
- Time in epoc seconds
$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'
), or any string with tokens '$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz'
for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively
$timezone
- either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
$text
Formatted time string
Note: | if you used the removed formatGmTime, add a third parameter 'gmtime' |
$value
is true, and 0 otherwise. "true" means set to
something with a Perl true value, with the special cases that "off",
"false" and "no" (case insensitive) are forced to false. Leading and
trailing spaces in $value
are ignored.
If the value is undef, then $default
is returned. If $default
is
not specified it is taken as 0.
Since: $TWiki::Plugins::VERSION 1.2
$text
- Word to test
$attr
- Attribute string
%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"
%params
hash contains now: _DEFAULT => 'nameless'
name1 => "val1"
name2 => "val2"
$attr
- Attribute string
$name
- Name, optional
$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" );
TWiki::Plugins
version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler
for compatibility with TWiki::Plugins
versions before 1.1, we would add this to the plugin:
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.
getScriptUrl
instead.
Return: $path
URL path of TWiki scripts, e.g. "/cgi-bin"
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)
$web
- Web name, e.g. 'Main'
. The current web is taken if empty
$topic
- Topic name, e.g. 'WebNotify'
$template
- Oops template name, e.g. 'oopsmistake'
. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
$param1
... $param4
- Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
$url
URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked¶m1=joe"
DEPRECATED since 1.1, the recommended approach is to throw an oops exception.
use Error qw( :try ); throw TWiki::OopsException( 'toestuckerror', web => $web, topic => $topic, params => [ 'I got my toe stuck' ]);(this example will use the
oopstoestuckerror
template.)
If this is not possible (e.g. in a REST handler that does not trap the exception)
then you can use getScriptUrl
instead:
my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops', template => 'oopstoestuckerror', param1 => 'I got my toe stuck'); TWiki::Func::redirectCgiQuery( undef, $url ); return 0;Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$web
- Web name, required, e.g. 'Sandbox'
getPreferencesValue
instead to determine
what permissions are set on the web, for example:
foreach my $type qw( ALLOW DENY ) { foreach my $action qw( CHANGE VIEW ) { my $pref = $type . 'WEB' . $action; my $val = getPreferencesValue( $pref, $web ) || ''; if( $val =~ /\S/ ) { print "$pref is set to $val on $web\n"; } } }
getListOfWebs
instead.
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 (07 Dec 2002)
formatTime
instead.
Format the time to GM time $time
- Time in epoc seconds
$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'
)
$text
Formatted time string
Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
$dir
Data directory, e.g. '/twiki/data'
This function violates store encapsulation and is therefore deprecated.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
$dir/Web/TopicName
Return: $dir
Pub directory, e.g. '/htdocs/twiki/pub'
This function violates store encapsulation and is therefore deprecated.
Use readAttachment
and saveAttachment
instead.
Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
commonTagsHandler($text, $topic, $web)
endRenderingHandler($text)
outsidePREHandler($text)
insidePREHandler($text)
startRenderingHandler($text, $web)
checkAccessPermission($type, $login, $topicText, $topicName, $webName) -> $boolean
expandCommonVariables($text, $topic, $web) -> $text
extractNameValuePair($attrs, $name) -> $value
formatGmTime($time) -> $text
getCgiQuery() -> $query
getDataDir() -> $dir
getDefaultUserName() -> $loginName
getMainWebname() -> $name
getOopsUrl($web, $topic, $template, @theParams) -> $url
getPreferencesFlag($key) -> $boolean
getPreferencesValue($key, $web) -> $value
getPublicWebList() -> @webs
getPubDir() -> $dir
getPubUrlPath() -> $path
getRevisionInfo($webName, $topic, $rev, $attachment) -> ($date, $user, $rev, $comment)
getScriptUrl($web, $topic, $script) -> $url
getScriptUrlPath() -> $path
getSessionValue($key) -> $value
getSkin() -> $skin
getTopicList($web) -> @topics
getTwikiWebname() -> $name
getUrlHost() -> $host
getViewUrl($web, $topic) -> $url
getWikiName() -> $wikiName
getWikiUserName($text) -> $wikiName
getWikiToolName() -> $name
internalLink($preamble, $web, $topic, $linkText, $anchor, $createLink) -> $text
isGuest() -> $boolean
permissionsSet($web) -> $boolean
readFile($filename) -> $text
readTemplate($name, $skin) -> $text
readTopic($webName, $topic) -> ($meta, $text)
redirectCgiQuery($query, $url)
renderText($text, $web) -> $text
saveFile($filename, $text)
setSessionValue($key, $value)
topicExists($web, $topic) -> $boolean
userToWikiName($user, $dontAddWeb) -> $wikiName
webExists($web) -> $boolean
wikiToUserName($wiki) -> $loginName
writeDebug($text)
writeHeader()
writeWarning($text)
afterEditHandler($text, $topic, $web)
beforeEditHandler($text, $topic, $web)
beforeSaveHandler($text, $topic, $web)
initializeUserHandler($loginName, $url, $pathInfo)
redirectCgiQueryHandler($query, $url)
registrationHandler($web, $wikiName, $loginName)
writeHeaderHandler($query)
checkTopicEditLock($web, $topic) ->($oopsUrl, $loginName, $unlockTime)
readTopicText($web, $topic, $rev, $ignorePermissions) -> $text
saveTopicText($web, $topic, $text, $ignorePermissions, $dontNotify) -> $oopsUrl
setTopicEditLock($web, $topic, $lock) -> $oopsUrl
afterCommonTagsHandler($text, $topic, $web)
afterSaveHandler($text, $topic, $web, $error)
beforeCommonTagsHandler($text, $topic, $web)
earlyInitPlugin()
afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error)
beforeAttachmentSaveHandler(\%attrHash, $topic, $web)
checkDependencies($moduleName, $dependenciesRef) -> $error
extractParameters($attr) -> %params
formatTime($time, $format, $timezone) -> $text
getPluginPreferencesFlag($key) -> $boolean
getPluginPreferencesValue($key) -> $value
getRegularExpression($regexName) -> $pattern
mergeHandler($diff, $old, $new, \%info) -> $text
modifyHeaderHandler(\%headers, $query)
postRenderingHandler($text)
preRenderingHandler($text, \%map)
renderFormFieldForEditHandler($name, $type, $size, $value, $attributes, $possibleValues) -> $html
renderWikiWordHandler($linkText, $hasExplicitLinkLabel, $web, $topic) -> $linkText
endRenderingHandler($text)
startRenderingHandler($text, $web)
addToHEAD($id, $header)
attachmentExists($web, $topic, $attachment) -> $boolean
clearSessionValue($key) -> $boolean
checkDependencies($moduleName, $dependenciesRef) -> $error
createWeb($newWeb, $baseWeb, $opts)
expandTemplate($def ) -> $string
expandVariablesOnTopicCreation($text) -> $text
getContext() -> \%hash
getListOfWebs($filter) -> @webs
getScriptUrl($web, $topic, $script, @params) -> $url
getRevisionAtTime($web, $topic, $time) -> $rev
getWorkArea($pluginName) -> $directorypath
isValidWikiWord($text) -> $boolean
loadTemplate($name, $skin, $web) -> $text
moveAttachment($web, $topic, $attachment, $newWeb, $newTopic, $newAttachment)
moveTopic($web, $topic, $newWeb, $newTopic)
moveWeb($oldName, $newName)
normalizeWebTopicName($web, $topic) ->($web, $topic)
readAttachment($web, $topic, $name, $rev) -> $data
registerRESTHandler($alias, \&fn,)
registerTagHandler($var, \&fn, $syntax)
saveAttachment($web, $topic, $attachment, $opts)
saveTopic($web, $topic, $meta, $text, $options) -> $error
searchInWebContent($searchString, $web, \@topics, \%options) -> \%map
sendEmail($text, $retries) -> $error
wikiToEmail($wikiName) -> $email
writeHeader($query, $contentLength)
checkDependencies($moduleName, $dependenciesRef) -> $error
formatGmTime($time, $format) -> $text
getDataDir() -> $dir
getOopsUrl( $web, $topic, $template, @params ) -> $url
getPubDir() -> $dir
getPublicWebList() -> @webs
getScriptUrlPath() -> $path
afterSaveHandler($text, $topic, $web, $error, $meta)
beforeSaveHandler($text, $topic, $web, $meta)
afterRenameHandler($oldWeb, $oldTopic, $oldAttachment, $newWeb, $newTopic, $newAttachment)
afterCommonTagsHandler($text, $topic, $web, $meta)
beforeCommonTagsHandler($text, $topic, $web, $meta)
commonTagsHandler($text, $topic, $web, $included, $meta)
decodeFormatTokens($str) -> $unencodedString
eachChangeSince($web, $time) -> $iterator
eachGroup() -> $iterator
eachGroupMember($group) -> $iterator
eachMembership($wikiname) -> $iterator
eachUser() -> $iterator
emailToWikiNames($email, $dontAddWeb) -> @wikiNames
expandCommonVariables($text, $topic, $web, $meta) -> $text
getCanonicalUserID( $user ) -> $cUID
getExternalResource($url) -> $response
getSessionKeys() -> @keys
isAnAdmin($login) -> $boolean
isGroup($group) -> $boolean
isGroupMember($group, $login) -> $boolean
isTrue($value, $default) -> $boolean
popTopicContext()
pushTopicContext($web, $topic)
sanitizeAttachmentName($fname) -> ($fileName, $origName)
setPreferencesValue($name, $val)
spaceOutWikiWord($word, $sep) -> $text
wikiNameToEmails($wikiname) -> @emails
permissionsSet($web) -> $boolean
getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
buildWikiWord( $text ) -> $text