Bookmaker for WebOrder
| Change book | Close bookmaker |
You can change the order/nesting of topics using drag and drop
Bookmaker for WebOrder
| Change book | Close bookmaker |
public package Foswiki::Func public package Foswiki::Func This module defines the main interfaces that extensions can use to interact with the Foswiki engine and content.
Refer tolib/Foswiki/Plugins/EmptyPlugin.pm for a template Plugin
and starter documentation on how to write a Plugin.
Plugins should only call methods in packages documented in
DevelopingPlugins. If you use
functions in other Foswiki libraries you risk creating a security hole, and
you will probably need to change your plugin when you upgrade Foswiki.
Since: date indicates where functions or parameters have been added since
the baseline of the API (Foswiki 1.0.0). The date indicates the
earliest date of a Foswiki release that will support that function or
parameter. See Foswiki:Download.ReleaseDates for version release dates.
Deprecated date indicates where a function or parameters has been
deprecated. Deprecated
functions will still work, though they should
not be called in new plugins and should be replaced in older plugins
as soon as possible. Deprecated parameters are simply ignored in Foswiki
releases after date.
Until date indicates where a function or parameter has been removed.
The date indicates the latest date at which Foswiki releases still supported
the function or parameter.
Note that the Foswiki::Func API should always be the first place extension
authors look for methods. Certain other lower-level APIs are also exposed
by the core, but those APIs should only be called if there is no alternative
available through Foswiki::Func. The APIs in question are documented in
DevelopingPlugins.
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.
Get protocol, domain and optional port of script URL
Return:$host URL host, e.g. "http://example.com:80"
$web - Web name, e.g. 'Main'
$topic - Topic name, e.g. 'WebNotify'
$script - Script name, e.g. 'view'
... - an arbitrary number of name=>value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2) will give .../view/x/y?a=1&b=2#XXX
$url URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
Examples:
my $url;
# $url eq 'http://wiki.example.org/url/to/bin'
$url = Foswiki::Func::getScriptUrl();
# $url eq 'http://wiki.example.org/url/to/bin/edit'
$url = Foswiki::Func::getScriptUrl(undef, undef, 'edit');
# $url eq 'http://wiki.example.org/url/to/bin/edit/Web/Topic'
$url = Foswiki::Func::getScriptUrl('Web', 'Topic', 'edit');
my $path;
# $path eq '/path/to/bin'
$path = Foswiki::Func::getScriptUrlPath();
# $path eq '/path/to/bin/edit'
$path = Foswiki::Func::getScriptUrlPath(undef, undef, 'edit');
# $path eq '/path/to/bin/edit/Web/Topic'
$path = Foswiki::Func::getScriptUrlPath('Web', 'Topic', 'edit');
Since: 19 Jan 2012 (when called without parameters, this function is
backwards-compatible with the old version which was deprecated 28 Nov 2008).
$web - Web name, e.g. 'Main'. The current web is taken if empty
$topic - Topic name, e.g. 'WebNotify'
$url URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
Get pub URL path/attachment URL
Return: with no parameters, returns the URL path of the root of all attachments.
Prior to Foswiki 2, URLs to attachments had to be constructed by the caller. For example,%PUBURL%/Main/JohnSmith/picture.gif
This method of constructing URLs causes many problems, and is
strongly discouraged.
Since Foswiki 2 this function accepts parameters as follows: $web - name of web
$topic - name of topic (ignored if web is not given)
$attachment - name of attachment (ignored if web or topic not given)
%options - additional options
topic_version - version of topic to retrieve attachment from
attachment_version - version of attachment to retrieve
absolute - requests an absolute URL (rather than a relative path)
$web is not given, $topic and $attachment are ignored.
If $topic is not given, $attachment is ignored.
If topic_version is not given, the most recent revision of the topic
will be linked. Similarly if attachment_version= is not given, the most recent
revision of the attachment will be assumed. If topic_version is specified
but attachment_version is not (or the specified attachment_version is not
present), then the most recent version of the attachment in that topic version
will be linked. Not all stores support retrieving old attachment versions
this way.
If absolute is not specified (or is 0), this function will generate
relative URLs. However if Foswiki is running in an absolute URL context
(the skin requires absolute URLs, such as print or rss, or Foswiki is
running from the command-line) then absolute will be ignored and
absolute URLs will always be generated.
https if the LWP CPAN module is
installed.
Note that the $url may have an optional user and password, as specified by
the relevant RFC. Any proxy set in configure is honoured.
The $response is an object that is known to implement the following subset of
the methods of LWP::Response. It may in fact be an LWP::Response object,
but it may also not be if LWP is not available, so callers may only assume
the following subset of methods is available:
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 = Foswiki::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
}
Foswiki::Request. The request
object can be used to get the parameters passed to the request, either
via CGI or on the command line (depending on how the script was called).
A Foswiki::Request object is largely compatible with a CPAN:CGI object.
Most of the time, documentation for that class applies directly to
Foswiki::Request objects as well.
Note that this method replaces getCgiQuery (which is a synonym for this
method). Code that is expected to run with pre-1.1 versions of Foswiki
can continue to call getCgiQuery for as long as necessary.
Caution: Direct use of the CGI parameters can introduce security vulnerabilities.
Any parameters from the URL should be carefully validated, and encoded for safety
before displaying the data back to the user.
Example:
my $query = Foswiki::Func::getRequestObject();
my $single = $query->param('parm1'); # Get a scalar value (Returns 1st value if multiple valued)
my @multi = $query->multi_param('parm2'); # Get multi-valued parameter
Since: 31 Mar 2009
setSessionValue and
getSessionValue.
$key - Session key
$value Value associated with key; empty string if not set
$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.
Get a hash of context identifiers representing the currently active context.
The context is a set of identifiers that are set during specific phases of processing. For example, each of the standard scripts in the 'bin' directory each has a context identifier - the view script has 'view', the edit script has 'edit' etc. So you can easily tell what 'type' of script your Plugin is being called within.
A comprehensive list of core context identifiers used by Foswiki is found in IfStatements Please be careful not to overwrite any of these identifiers! Context identifiers can be used to communicate between Plugins, and between Plugins and templates. For example, in FirstPlugin.pm, you might write:
sub initPlugin {
Foswiki::Func::getContext()->{'MyID'} = 1;
...
This can be used in SecondPlugin.pm like this:
sub initPlugin {
if( Foswiki::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.
$web - new web
$topic - new topic
$web.$topic onto the
preferences stack. Any preferences found in $web.$topic will be used
in place of preferences previously set in the stack, provided that they
were not finalized in a lower level. Preferences set in the prior
web.topic are not cleared. $web.$topic replaces and adds to
preferences but does not remove preferences that it does not set.
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.
All other errors will throw an exception.
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.
pushTopicContext was called.
Plugins work either by using handlers to manipulate the text being processed, or by registering extensions, such as new macros, scripts, or meta-data types.
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 internal macros, and are expanded at the same time. This is a lot more efficient than using thecommonTagsHandler. $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'. (context-free may be removed in future) 'classic' syntax is appropriate where you want the variable to support classic syntax
%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, $topicObject)where:
\%session - a reference to the session object (may be ignored)
\%params - a reference to a Foswiki::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
$topicObject - is the Foswiki::Meta object for the topic Since 2009-03-06
sub initPlugin{
Foswiki::Func::registerTagHandler('EXEC', \&boo);
}
sub boo {
my( $session, $params, $topic, $web, $topicObject ) = @_;
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 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.
Should only be called from initPlugin.
Adds a function to the dispatch table of the REST interface$alias - The name .
\&fn - Reference to the function.
%options - additional options affecting the handler
sub handler(\%session)where:
\%session - a reference to the Foswiki session object (may be ignored)
From the REST interface, the name of the plugin must be used as the subject of the invokation.
Additional options are set in the%options hash. These options are important
to ensuring that requests to your handler can't be used in cross-scripting
attacks, or used for phishing. authenticate - use this boolean option to require authentication for the handler. If this is set, then an authenticated session must be in place or the REST call will be rejected with a 401 (Unauthorized) status code. As of Foswiki 2, authenticate defaults to true. If the handler being registered is usable by guests, and does its own checking, pass authenticate => 0 to remove the requirement for an authenticated session.
validate - use this boolean option to require validation of any requests made to this handler. Validation is the process by which a secret key is passed to the server so it can identify the origin of the request. As of Foswiki 2, validate will default to true. If your handler is typically invoked multipe times on a page, or doesn not need protection from CSRF attacks, set validate => 0.
http_allow use this option to specify that the HTTP methods that can be used to invoke the handler. For example, http_allow=>'POST,GET' will constrain the handler to be invoked using POST and GET, but not other HTTP methods, such as DELETE. Normally you will use http_allow=>'POST'. Together with authentication this is an important security tool. Handlers that can be invoked using GET are vulnerable to being called in the src parameter of img tags, a common method for cross-site request forgery (CSRF) attacks. As of Foswiki 2, this option will default to http_allow => 'POST'. If your handler does not update, then explicitly set this to http_allow => 'GET,POST'
description => 'handler information' This is a completely optional short description of the handler function. It is displayed by the %RESTHANDLERS% macro used for extension diagnostics.
Foswiki::Func::registerRESTHandler('example', \&restExample,
authenticate => 1, # Set to 0 if handler should be useable by WikiGuest
validate => 1, # Set to 0 to disable StrikeOne CSRF protection
http_allow => 'POST', # Set to 'GET,POST' to allow use HTTP GET and POST
description => 'Example handler for Empty Plugin'
);
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.
rest script allows handlers to be invoked from the command line. The
script is invoked passing the parameters as described in CommandAndCGIScripts.
If the handler requires authentication ( authenticate=>1 ) then this can
be passed in the username and password parameters.
For example,
perl -wT rest /EmptyPlugin/example -username HughPugh -password trumpton
$key - Preference name
$web - Name of web, optional. If defined, we shortcircuit to WebPreferences (ignoring SitePreferences). This is really only useful for ACLs.
$value Preferences value; undefined if not set
* Set WEBBGCOLOR = #FFFFC0
my $webColor = Foswiki::Func::getPreferencesValue( 'WEBBGCOLOR', 'Sandbox' );
* Set COLOR = red
"MYPLUGIN_COLOR" for $key
my $color = Foswiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );
$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. Foswiki::Plugins::MyPlugin::MyModule)
NOTE: 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")
* Set SHOWHELP = off
"MYPLUGIN_SHOWHELP" for $key
my $showHelp = Foswiki::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. Foswiki::Plugins::MyPlugin::MyModule)
NOTE: 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.
DefaultUserLogin
Return: $loginName Default user name, e.g. 'guest'
$user can be a login, wikiname or web.wikiname
If $user is undefined, it assumes the currently logged-in user.
Return:$cUID, an internal unique and portable escaped identifier for
registered users. This may be autogenerated for an authenticated but
unregistered user.
$wikiName Wiki Name, e.g. 'JohnDoe'
return the userWeb.WikiName of the specified user if $user is undefined Get Wiki name of logged in user
$wikiName Wiki Name, e.g. "Main.JohnDoe"
$id - Wiki name, e.g. 'Main.JohnDoe' or 'JohnDoe'. $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.
$loginName - Login name, e.g. 'jdoe'. 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)
$email - email address to look up
$dontAddWeb - Do not add web prefix if "1"
$user - wikiname of user to look up
$user may also be a group.
Find out if $id is in the named group. The expand option controls whether or not nested groups are searched.
e.g. Is jordi in the HesperionXXGroup, and not in a nested group. e.g.
if( Foswiki::Func::isGroupMember( "HesperionXXGroup", "jordi", { expand => 0 } )) {
...
}
If $user is undef, it defaults to the currently logged-in user.
my $it = Foswiki::Func::eachUser();
while ($it->hasNext()) {
my $user = $it->next();
# $user is a wikiname
}
WARNING on large sites, this could be a long list!
$id - WikiName or login name of the user. If $id is undef, defaults to the currently logged-in user.
my $iterator = Foswiki::Func::eachGroup();
while ($it->hasNext()) {
my $group = $it->next();
# $group is a group name e.g. AdminGroup
}
WARNING on large sites, this could be a long list!
$group is the name of a user group.
my $iterator = Foswiki::Func::eachGroupMember('RadioheadGroup', {expand => 'false');
while ($it->hasNext()) {
my $user = $it->next();
# $user is a wiki name e.g. 'TomYorke', 'PhilSelway'
# With expand set to false, group names can also be returned.
# Users are not checked to exist.
}
WARNING on large sites, this could be a long list!
$type - Access type, required, e.g. 'VIEW', 'CHANGE'.
$id - WikiName of remote user, required, e.g. "RickShaw". $id may also be a login name. If $id is '', 0 or undef then access is always permitted. This is used by other functions if the caller should be able to bypass access checks.
$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, optional, e.g. 'PrivateStuff', '' or undef $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.
Example code:Tip: if you want, you can use this method to check your own access control types. For example, if you:
in
- Set ALLOWTOPICSPIN = IncyWincy
ThatWeb.ThisTopic, then a call tocheckAccessPermission('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)will returntrue.
use Error qw(:try);
use Foswiki::AccessControlException;
...
unless (
Foswiki::Func::checkAccessPermission(
"VIEW", $session->{user}, undef, $topic, $web
)
)
{
throw Foswiki::AccessControlException( "VIEW", $session->{user}, $web,
$topic, $Foswiki::Meta::reason );
}
$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. $web - (Since 2009-01-01) name of web to get list of subwebs for. Defaults to the root. note that if set, the list will not contain the web specified in $web
my @webs = Foswiki::Func::getListOfWebs( "user,public" );
Check for a valid web name. If $system is true, then system web names are considered valid (names starting with _) otherwise only user web names are valid
If $Foswiki::cfg{EnableHierarchicalWebs} is off, it will also return false when a nested web name is passed to it.
$web - Web name, required, e.g. 'Sandbox'
$web - Web name, required, e.g. 'Sandbox'
@topics Topic list, e.g. ( 'WebChanges', 'WebHome', 'WebIndex', 'WebNotify' )
$name - topic name
$allowNonWW - true to allow non-wikiwords
$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.
$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 Foswiki::Meta. This class is
fully documented in the source code documentation shipped with the
release, or can be inspected in the lib/Foswiki/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.
$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, comment of attachment if attachment ), e.g. ( 1234561, 'phoeny', "5", )
| $date | in epochSec |
| $user | Wiki name of the author (not login name) |
| $rev | actual rev number |
| $comment | comment given for uploaded attachment |
$meta->getRevisionInfo instead if you can - it is significantly
more efficient.
$web - web for topic
$topic - topic
$time - time (in epoch secs) for the rev
$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.
The attachment must exist in the store (it is not sufficient for it to be referenced in the object only)
$web - web for topic - must not be tainted
$topic - topic - must not be tainted
$name - attachment name - must not be tainted
$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
Foswiki::AccessControlException. Permissions are checked for the current user.
use Error qw(:try);
use Foswiki::AccessControlException ();
my( $meta, $text ) = Foswiki::Func::readTopic( $web, $topic );
my @attachments = $meta->find( 'FILEATTACHMENT' );
foreach my $a ( @attachments ) {
try {
my $data = Foswiki::Func::readAttachment( $web, $topic, $a->{name} );
...
} catch Foswiki::AccessControlException with {
};
}
This is the way 99% of extensions will access attachments.
See Foswiki::Meta::openAttachment for a lower level interface that does
not check access controls.
$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 Foswiki::AccessControlException ();
try {
Foswiki::Func::createWeb( "Newweb" );
} catch Foswiki::AccessControlException with {
my $e = shift;
# see documentation on Foswiki::AccessControlException
} catch Foswiki::OopsException with {
shift->throw(); # propagate
} catch Error with {
my $e = shift;
# see documentation on Error
} otherwise {
...
};
Move (rename) a web.
use Error qw( :try );
use Foswiki::AccessControlException ();
try {
Foswiki::Func::moveWeb( "Oldweb", "Newweb" );
} catch Foswiki::AccessControlException with {
my $e = shift;
# see documentation on Foswiki::AccessControlException
} catch Foswiki::OopsException with {
shift->throw(); # propagate
} catch Error with {
my $e = shift;
# see documentation on Error::Simple
} otherwise {
...
};
To delete a web, move it to a subweb of Trash
Foswiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );
$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.
$web - web for the topic
$topic - topic name
$meta - reference to Foswiki::Meta object (optional, set to undef to create a new topic containing just text, or to just change that topic's text)
$text - text of the topic (without embedded meta-data!!!
\%options - ref to hash of save options \%options may include: dontlog | mark this change so it doesn't appear in the statistics |
minor | True if this change is not to be notified |
forcenewrevision | force the save to increment the revision counter |
ignorepermissions | don't check acls |
use Error qw( :try );
use Foswiki::AccessControlException ();
my( $meta, $text );
if (Foswiki::Func::topicExists($web, $topic)) {
( $meta, $text ) = Foswiki::Func::readTopic( $web, $topic );
} else {
#if the topic doesn't exist, we can either leave $meta undefined
#or if we need to set more than just the topic text, we create a new Meta object and use it.
$meta = new Foswiki::Meta($Foswiki::Plugins::SESSION, $web, $topic );
$text = '';
}
$text =~ s/APPLE/ORANGE/g;
try {
Foswiki::Func::saveTopic( $web, $topic, $meta, $text );
} catch Foswiki::AccessControlException with {
my $e = shift;
# see documentation on Foswiki::AccessControlException
} catch Foswiki::OopsException with {
shift->throw(); # propagate
} catch Error with {
my $e = shift;
# see documentation on Error::Simple
} otherwise {
...
};
In the event of an error an exception will be thrown. Callers can elect
to trap the exceptions thrown, or allow them to propagate to the calling
environment. May throw Foswiki::OopsException or Error::Simple.
Note: The ignorepermissions option is only available in Foswiki 1.1 and
later.
$web source web - required
$topic source topic - required
$newWeb dest web
$newTopic dest topic
The destination topic must not already exist.
Rename a topic to the $Foswiki::cfg{TrashWebName} to delete it.
use Error qw( :try );
try {
moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
} catch Foswiki::AccessControlException with {
my $e = shift;
# see documentation on Foswiki::AccessControlException
} catch Foswiki::OopsException with {
shift->throw(); # propagate
} catch Error with {
my $e = shift;
# see documentation on Error::Simple
} otherwise {
...
};
$web - web for topic
$topic - topic to atach to
$attachment - name of the attachment
\%opts - Ref to hash of options
\%opts may include:
dontlog |
mark this change so it is not picked up in statistics |
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 |
createlink |
Set true to create a link at the end of the topic |
notopicchange |
Set to true to prevent this upload being recorded in the meta-data of the topic. |
try {
Foswiki::Func::saveAttachment( $web, $topic, 'image.gif',
{ file => 'image.gif',
comment => 'Picture of Health',
hide => 1 } );
} catch Foswiki::AccessControlException with {
# Topic CHANGE access denied
} catch Foswiki::OopsException with {
shift->throw(); # propagate
} catch Error with {
# see documentation on Error
} otherwise {
...
};
This is the way 99% of extensions will create new attachments. See
Foswiki::Meta::openAttachment for a much lower-level interface.
$web source web - required
$topic source topic - required
$attachment source attachment - required
$newWeb dest web
$newTopic dest topic
$newAttachment dest attachment
Rename an attachment to $Foswiki::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 Foswiki::AccessControlException with {
my $e = shift;
# see documentation on Foswiki::AccessControlException
} catch Foswiki::OopsException with {
shift->throw(); # propagate
} catch Error with {
my $e = shift;
# see documentation on Error
};
$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 {
# copy attachment between topics
copyAttachment( "Countries", "Germany", "AlsaceLorraine.dat",
"Countries", "France" );
# Note destination attachment name is defaulted to the same as source
} catch Foswiki::AccessControlException with {
my $e = shift;
# see documentation on Foswiki::AccessControlException
} catch Foswiki::OopsException with {
shift->throw(); # propagate
} catch Error with {
my $e = shift;
# see documentation on Error
};
Since: 19 Jul 2010
$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 = Foswiki::Func::eachChangeSince(
$web, time() - 7 * 24 * 60 * 60); # the last 7 days
while ($iterator->hasNext()) {
my $change = $iterator->next();
...
}
$change is a reference to a hash containing the following fields: verb - the action - one of update - a web, topic or attachment has been modified
insert - a web, topic or attachment is being inserted
remove - a topic or attachment is being removed
time - time of the change, in epoch-secs
cuid - canonical UID of the user who is making the change
revision - the revision of the topic that the change appears in
path - web.topic path for the affected
attachment - attachment name (optional)
oldpath - web.topic path for the origin of a move
oldattachment - origin of move
minor - boolean true if this change is flagged as minor
comment - descriptive text
more - formatted string indicating if the change was minor or not
topic - name of the topic the change occurred to
user - wikiname of the user who made the change
more, revision, time, topic and user
can be assumed.
$web, $topic - topic (required)
$orev - older rev (required)
$nrev - later rev (may be undef for the latest)
$tml - if true will generate renderable TML (i.e. HTML with NOPs. if false will generate a summary suitable for use in plain text (mail, for example)
$nochecks if true, will suppress access control checks. (Since 2.0)
If there is only one rev, a topic summary will be returned.
If$tml is not set, all HTML will be removed.
In non-tml, lines are truncated to 70 characters. Differences are shown using + and - to indicate added and removed text.
If access is denied to either revision, then it will be treated as blank text.
Since 2009-03-06$name - Template name, e.g. 'view'
$skin - Comma-separated list of skin names, optional, e.g. 'print'
$text Template text
$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)
Reads a template and extracts template definitions, adding them to the list of loaded templates, overwriting any previous definition.
How Foswiki searches for templates is described in SkinTemplates.If template text is found, extracts include statements and fully expands them.
%TMPL:P{$def}%, only expanding the template (not expanding any variables other than %TMPL%.) $def - template name or parameters (as a string)
%TMPL:DEF% statement in a template
file. See the documentation on Foswiki templates for more information.
eg:
#load the templates (relying on the system-wide skin path.)
Foswiki::Func::loadTemplate('linkedin');
#get the 'profile' DEF section
my $tml = Foswiki::Func::expandTemplate('profile');
#get the 'profile' DEF section expanding the inline Template macros (such as %USER% and %TYPE%)
#NOTE: when using it this way, it is important to use the double quotes "" to delineate the values of the parameters.
my $tml = Foswiki::Func::expandTemplate(
'"profile" USER="' . $user . '" TYPE="' . $type . '"' );
%VARIABLES% $text - Text with variables to expand, e.g. 'Current user is %WIKIUSER%'
$topic - Current topic name, optional, 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
$text Expanded text, e.g. 'Current user is WikiGuest'
See also: expandVariablesOnTopicCreation
Caution: This function needs all the installed plugins to have gone through initialization. Never call this function from within an initPlugin handler, bad things happen. Caution: This function ultimately calls the following handlers:beforeCommonTagsHandler
commonTagsHandler
registered macro handlers
afterCommonTagsHandler
It is possible to create an infinite loop if expandCommonVariables is called in any of these handlers.
It can be used, but care should be taken to ensure that the text being expanded does
not cause this function to be called recursively.
$text - the text to process
Expands only the variables expected in templates that must be statically expanded in new content.
The expanded variables are:%DATE% Signature-format date
%SERVERTIME% See Macros
%GMTIME% See Macros
%USERNAME% Base login name
%WIKINAME% Wiki name
%WIKIUSERNAME% Wiki name with prepended web
%URLPARAM{...}% - Parameters to the current CGI query
%NOP% No-op
See also: expandVariables
$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
$topic - topic name, optional, defaults to web home
$text XHTML text, e.g. '<b>bold</b> and <code>fixed font</code>'
NOTE: renderText expects that all %MACROS% have already been expanded - it does not expand them for you (call expandCommonVariables above).
renderText() $pre - Text occuring before the 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>'
$zone - name of the zone
$id - unique ID
$data - the content.
requires optional, comma-separated list of $id identifiers that should precede the content
$data will be expanded before being inserted into the <head> section.
Examples:addToZone()from a rendering or macro/tag-related plugin handler
Foswiki::Func::addToZone( 'head', 'PATTERN_STYLE', '<link rel="stylesheet" type="text/css" href="%PUBURL%/Foswiki/PatternSkin/layout.css" media="all" />'); Foswiki::Func::addToZone( 'script', 'MY_JQUERY', '<script type="text/javascript" src="%PUBURL%/Myweb/MyJQuery/myjquery.js"></scipt>', 'JQUERYPLUGIN::FOSWIKI');
Prints a basic content-type HTML header for text/html to standard out.
$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.
$status - HTTP status code (30x) to redirect with. Optional, defaults to 302. Since 2012-03-28
Return: none
Issue aLocation HTTP header that will cause a redirect to a new URL.
Nothing more should be printed to STDOUT after this method has been called.
The $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 installation. If $passthru is set to a true value, then Foswiki
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 = Foswiki::Func::getRequestObject(); $query->param(-name => 'text', -value => 'Different text'); Foswiki::Func::redirectCgiQuery( undef, Foswiki::Func::getScriptUrl($web, $topic, 'edit'), 1);
$passthru does nothing if $url does not point to a script in the current
Foswiki installation.
Gets a private directory for Plugin use. The Plugin is entirely responsible for managing this directory; Foswiki 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 its contents are permanent, so Plugins must be careful to keep their areas tidy.
For temporary file storage that only exists for the life of the transaction, use the PerlFile::Temp or related File::Spec functions.
$filename - Full path name of file
$unicode - Specify that file contains unicode text New with Foswiki 2.0
$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.
Foswiki 2.0 APIs generally all use UNICODE strings, and all data is properly decoded from/to utf-8 at the edge. This API is an exception!
Because this API can be used to retrieve data of any type including binary data, it is not decoded to unicode by default.
By default, data is read as raw bytes, without any encoding layer.
If you are using this API to read topic originated data, topic names, etc. then you should set the $unicode flag so that the data returned is a valid perl character string.
$filename - Full path name of file
$text - Text to save
$unicode - Flag indicates that $text string should be saved as utf-8. New with Foswiki 2.0
Return: none
NOTE: Use this function only for the Plugin workarea, not for topics and attachments. Use the appropriate functions to manipulate topics and attachments. Foswiki 2.0 APIs generally all use UNICODE strings, and all data is properly decoded from/to utf-8 at the edge. This API is an exception! Because this API can be used to save data of any type including binary data, it is not decoded to unicode by default. By default, data is written as raw bytes, without any encoding layer. If you are using this API to write topic data, topic names, etc. then you should set the$unicode flag so that the data returned as a valid perl character string.
Failure to set the $unicode flag when required will result in perl "Wide character in print" errors.
$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' ) |
| ( 'Web1', 'Web2.' ) | ( 'Web2', 'WebHome' ) |
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' ) | ( 'System', 'Topic' ) |
| ( '', '%DOCWEB%.Topic' ) | ( 'System', 'Topic' ) |
Query the topic data in the specified webs. A programatic interface to SEARCH results.
$searchString - the search string, as appropriate for the selected type
$topics - undef OR reference to a ResultSet, Iterator, or array containing the web.topics to be evaluated. if undef, then all the topics in the webs specified will be evaluated.
\%option - reference to an options hash
\%options hash may contain the following options: type - regex, keyword, query, ... defaults to query
web - The web/s to search in - string can have the same form as the web param of SEARCH (if not specified, defaults to BASEWEB)
casesensitive - false to ignore case (default 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
includeTopics - Seach only in this topic, a topic with asterisk wildcards, or a list of topics separated by comma
excludeTopics - Exclude search in this topic, a topic with asterisk wildcards, or a list of topics separated by comma
my $matches = Foswiki::Func::query( "Slimy Toad", undef,
{ web => 'Main,San*', casesensitive => 0, files_without_match => 0 } );
while ($matches->hasNext) {
my $webtopic = $matches->next;
my ($web, $topic) = Foswiki::Func::normalizeWebTopicName('', $webtopic);
...etc
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 Foswiki uses escapes in the format string. For example:
%MYTAG{format="$percentWURBLE$percent"}%
This lets you enter arbitrary strings into parameters without worrying that Foswiki 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.
The set of tokens that is expanded is described in FormatTokens.Given a file path, sanitise it according to the rules for transforming attachment names. Returns the sanitised name together with the basename before sanitisation.
Sanitation includes filtering illegal characters and mapping client file names to legal server names.
Avoid using this if you can; rewriting attachment names uses some very nasty heuristics that cannot be changed because of compatibility issues. It is much better use point-of-source validation to ensure only valid attachment names are uploaded.
Spaces out a wiki word by inserting a string (default: one space) between each word component. With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.
$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.
$text - Word to test
$attr - Attribute string
%params Hash containing all parameters. The nameless parameter is stored in key _DEFAULT
%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
%TEST{ 'nameless' name1="val1" name2="val2" }%
{...} to get: 'nameless' name1="val1" name2="val2"
my $noname = Foswiki::Func::extractNameValuePair( $text ); my $val1 = Foswiki::Func::extractNameValuePair( $text, "name1" ); my $val2 = Foswiki::Func::extractNameValuePair( $text, "name2" );
$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.
$action - name of the event (keep them unique!)
$extra - arbitrary extra information to add to the log.
eachEventSince function.
NOTE: Older plugins may use $Foswiki::cfg{LogFileName}. These
plugins must be modified to use writeEvent and eachEventSince instead.
To maintain compatibility with older Foswiki releases, you can write
conditional code as follows:
if (defined &Foswiki::Func::writeEvent) {
# use writeEvent and eachEventSince
} else {
# old code using {LogFileName}
}
Note that the ability to read/write $Foswiki::cfg{LogFileName} is
maintained for compatibility but is deprecated (should not be used
in new code intended to work only with Foswiki 1.1 and later) and will
not work with any installation that stores logs in a database.
data/warn*.txt) $text - Text to write; timestamp gets added
$text - Text to write; timestamp gets added
$time - a time in the past (seconds since the epoch)
$level - log level to return events for.
$time and now. Events are written to the event log using
writeEvent. The Foswiki core will write other events that will
also be returned.
If the chosen Logger does not support querying the logs, an empty
iterator will be returned. The supplied PlainFile and Compatibility loggers
will return events only if the log files have not been archived.
Events are returned in oldest-first order.
Each event is returned as a reference to an array. The elements are: writeEvent)
writeEvent)
my $it = Foswiki::Func::eachEventSince(Foswiki::Time::parseTime("1 Apr 2010"));
while ($it->hasNext()) {
my $entry = $it->next();
my $date = $entry->[0];
my $loginName = $entry->[1];
...
}
Foswiki::Func, 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 release, and probably longer, though this cannot be guaranteed.
Updated plugins may still need to define deprecated handlers for compatibility with old Foswiki 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 theFoswiki::Plugins version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler for compatibility with Foswiki::Plugins versions before 1.1, we would add this to the plugin:
package Foswiki::Plugins::SinkPlugin;
use vars qw( %FoswikiCompatibility );
$FoswikiCompatibility{endRenderingHandler} = 1.1;
If the currently-running code version is 1.1 or later, then the handler will not be called and the warning will not be issued. Wersions of Foswiki::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.
$Foswiki::regex{...} instead, it is directly
equivalent.
See DevelopingPlugins for more information
$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 28 Nov 2008, the recommended approach is to throw an oops exception.
use Error qw( :try );
throw Foswiki::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 = Foswiki::Func::getScriptUrl($web, $topic, 'oops',
template => 'oopstoestuckerror',
param1 => 'I got my toe stuck');
Foswiki::Func::redirectCgiQuery( undef, $url );
return 0;
$wikiname - wiki name of the user
$wikiName may also be a login name.
$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 = Foswiki::Func::getPreferencesValue( $pref, $web ) || '';
if( $val =~ m/\S/ ) {
print "$pref is set to $val on $web\n";
}
}
}
getListOfWebs instead.
Get list of all public webs, e.g. all webs and subwebs that do not have the NOSEARCHALL flag set in the WebPreferences
Return: @webs List of all public webs and subwebs
Foswiki::Time::formatTime instead (it has an identical interface).
Format the time in seconds into the desired time string $time - Time in epoch 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' |
Foswiki::Time::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
getRequestObject instead if you can. Code
that is expected to run with pre-1.1 versions of Foswiki will still need to
use this method, as getRequestObject will not be available.
$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
*Deprecated: 6 Aug 2009. Use readTopic instead.
This method returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. Use readTopic instead, which is a lot safer and supports the full set of read options.
$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
saveTopic supports embedded meta-data in the saved text, and also
supports the full set of save options.
Return: $oopsUrl Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case of error
my $text = Foswiki::Func::readTopicText( $web, $topic );
# check for oops URL in case of error:
if( $text =~ m/^http.*?\/oops/ ) {
Foswiki::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 = Foswiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
$data to the HTML header (the <head> tag).
Deprecated 26 Mar 2010 - use addZoZone('head', ...).
Note: Any calls using addToHEAD for javascript should be rewritten to use the
new script zone in addToZone as soon as possible.
Rewrite:
Foswiki::Func::addToHEAD("id", "<script>...</script>", "JQUERYPLUGIN");
To:
Foswiki::Func::addToZone("script", "id", "<script>...</script>", "JQUERYPLUGIN");
The reason is that all <script> markup should be added to a dedicated zone, script, and so any usage of ADDTOHEAD - which adds to the head zone - will be unable to satisfy ordering requirements when the requirements exist in another zone ( script ).
See Foswiki:Development/UpdatingExtensionsScriptZone for more details.query( ...).
WARNING: This function has been deprecated in foswiki 1.1.0 for scalability reasons
Search 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+{.*}%) $searchString - the search string, in egrep format
$web - The web/s to search in - string can have the same form as the web param of SEARCH
\@topics - reference to a list of topics to search (if undef, then the store will search all topics in the specified web/webs.)
\%option - reference to an options hash
\%options hash may contain the following options: type - regex, keyword, query - defaults to regex
casesensitive - false to ignore case (default 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).
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 $matches = Foswiki::Func::searchInWebContent( "Slimy Toad", $searchWeb, \@topics,
{ casesensitive => 0, files_without_match => 0 } );
foreach my $topic (keys(%$matches)) {
...etc
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.