SetVariablePlugin

Flexible handling of topic variables

The main purpose of this plugin is to allow to set topic variables when saving a topic. Url parameters posted to save will be parsed and stored into the current topic.

Parameters must have the form:

http://....?[Local|Set|Unset|Default]+<key>=<value>

Which means:

• Local+<key>=<value> will create a local topic variable called key with value =value
• Set+<key>=<value> will create a normal topic variable called key with value =value (note if stored in a user topic these take effect on all of the site for this user; see the Foswiki documentation for a more in depth explanation)
• Unset+<key>=<value> will remove a topic variable called key from the topic
• Default+<key>=<value> defines the default values for a variable key; if key is set to this value, it will actually be remove from the topic as it is being set to a default value

In addition to setting topic variables via url parameters of a save action, this plugin provides means to read and write topic variables in WikiApplications. Among other use cases these can be used to create appropriate html forms for topic variables as far as the function is not provided by standard TML part of the Foswiki core.

When SETVAR and UNSERVAR are parsed during the discourse of creating the current page they don't set the topic variable immediately. Instead they create a definition rule. All definition rules are collected and applied to the topic at the end of the parsing process. That way multiple SETVAR and UNSERVAR - that potentially contradict each other - stack up. The last rule on the stack wins and decides wether a variable is set or deleted. This allows to create more extensive rule sets.

Syntax Rules

SETVAR

%SETVAR{
  "<key>"
  format="<value>"
  field="<fieldname>"
  regex="<pattern>"
}%

This sets topic variable key to value value if the formfield fieldname of the current topic matches pattern. This allows to set topic variables based on the value of a formfield value. For example, that's useful to create access control settings automatically.

The format string may contain the standard escape parameters

• $percnt,
• $dollar,
• $nop and
• $n as well as
• $value - the value of the current variable
• $name - the name of the current variable
• $title - the title and the
• $type - which is Set, Local, Web, Session or Global depending on the type and scope of the variable

UNSETVAR

%UNSETVAR{
  "<key>"
  field="<fieldname>"
  regex="<pattern>"
}%

This unsets topic variable key when formfield formfield fieldname of the current topic matches pattern

GETVAR

%GETVAR{
  "<key|pattern>"
  web="<web>"
  topic="<topic>"
  format="<format>"
  header="<header>"
  footer="<footer>"
  separator="<separator>"
  type="PREFERENCE|FIELD|TOPICINFO|..."
  sort="on|off"
  default="<default>"
  scope="topic|web|user|session|global"
}%

This displays a variable key as stored in topic web.topic and formats it using the given format. It's type can be any of the known Foswiki meta data specifies like PREFERENCE, FIELD, TOPICINFO etc. When no definition of key was found the default value is returned. Instead of extracting a variable from web.topic it can also be extracted from a specific scope.

Normally all scopes are layered above each other and only the value defined in the scope with highest precedence is returned. So when ever a variable is set in a topic, it will potentially override its definition on web level or user level. You may use the scope parameter to bypass this logic and extract a specific value from the given scope specifier.

Multiple variables can be returned by one call if you use a pattern instead of a key holding a regular expression. GETVAR will return all variable values of the given type where the pattern matches on the variable name. The list of variables will be displayed using format preceded by header and appended by footer. The header and footer will be omitted when no matching variable was found.

The format string may contain the standard escape parameters

• $percnt,
• $dollar,
• $nop and
• $n as well as
• $value - the value of the current variable
• $name - the name of the current variable
• $title - the title and the
• $type - which is Set, Local, Web, Session or Global depending on the type and scope of the variable

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

None

Change History

22 Oct 2020:	allow to unset a variable using the special value undef; deprecated value in %SETVAR in favour of format; allow same escape parameters in format of %SETVAR as in %GETVAR
16 Aug 2018:	fixed some more perl errors
11 Jun 2018:	disable processsing SET url parameters on Foswiki engines that support this feature on their own
05 Mar 2018:	fixed some perl rookie errors
09 Sep 2016:	add compatibility with different Foswiki engines
12 Dec 2013:	still perform an beforeSaveHandler even on newer foswikies
17 Dec 2012:	work around performance problem in common Foswiki engines reading templates repeatedly
05 Nov 2012:	Module version string is incompatible with Foswiki extension installers before v1.1.6
26 Oct 2012:	view template without %TEXT% gets processed during save, ignores topic text (Jan Krüger)
01 Oct 2012:	fixed reading a variable from a web scope, then fallback to global scope
10 Apr 2012:	fixing scope="web"; fixing reading the view template yet again
27 Feb 2012:	added scope="global"; fixed reading view templates when there is none
02 Dec 2011:	improving save times, thanks to Foswiki:Main.PaulHarvey
28 Sep 2011:	implement setting variables via view_templates
17 Nov 2009:	SETVAR has higher priority than urlparams; fixed use in persistent perl envs
23 Jun 2009:	initial release