Set and get variables and JSON objects in topics, optionally persistently across topic views

Introduction

Use %SET{}% to store a JSON object or arbitrary text in a named variable, and reuse it with %GET{}% later on within the topic or an included topic. By default, variables live only during topic rendering time, e.g. they do not persist between topic views. It is also possible to make variables persist, e.g. to remember them between topic views.

%SET{}% and %GET{}% can be nested inside other TWiki variables and get handled as expected, e.g. inside out, and left to right.

Alternatives to this plugin:

TWiki preferences settings: Can be defined on a site level (TWikiPreferences), web level (WebPreferences) and topic level. Preferences settings persist until changed.

SpreadSheetPlugin variables: Variables can be set with %CALCULATE{$SET(some_name, any value)}% and retrieved with $GET(). These variables persist during page rendering time.

Syntax Rules

SET{"name" value="..."} -- set a variable

Set a named variable that can be retrieved later with %GET{}%. No output is shown, e.g. %SET{}% resolves to an empty string. It is also possible to set a JSON object using a JSON path.

Name of variable. Alphanumeric characters, dashes and underscores can be used.

(required)

value="..."

Value of variable. Escape double quotes with backslash.

(required, may be empty)

remember="1"

If set, the variable will be stored persistently so that it can be used later in any TWiki topic. Alternatively use the store parameter. See important notes.

"0"

store="..."

Specify a store name to persistently store the variable, such as store="Parts". Use alphanumeric characters, dashes and underscores for the name. For better performance, store is preferred over the remember parameter if you need to store a large dataset. See important notes.

""

Example: %SET{"lunch" value="Sushi"}%

JSON Syntax: %SET{ name = { ... } remember="1" }%

An optional remember="1" or store="..." parameter can be appended. If specified, the JSON object will be stored persistently so that it can be used later in any TWiki topic.

Use descriptive variable names: Keep in mind that the remember option sets a variable with TWiki-global scope, e.g. for all pages and all users. To avoid name clashes, use a descriptive variable name which might include web & topic name and user or group name. For example, instead of variable name "campaign", use a more descriptive name "Marketing-Europe-2020-Campaign".

Do not store confidential content: The remembered variables are not aware of access control. If a user stores access controlled content in a variable, anyone who knows the variable name or uses the SETGETDUMP variable can read the content.

Variables are not version controlled, e.g. you do not get the audit trail available elsewhere in TWiki (topics, attachments, meta data, etc). Consider storing content in TWiki form fields if you need an audit trail.

GET{"name"} -- get a variable

Name of variable, such as menu. May optionally contain a JSON path, such as menu.File.Open.

(required)

format="..."

Format with supported variables: • $name for variable name • $value for variable value • $isdefined expanding to 1 or 0 depending if variable is defined or not • $isset expanding to 1 or 0 depending if variable is logically true or false • $ispersistent expanding to 1 or 0 depending if variable is persistent or not • all FormatTokens such as $dollar, $n, $percnt.

"$value"

default="..."

Text shown if variable is not defined, e.g. not found. This parameter overrides the format parameter.

"" (empty string)

store="..."

Specify a store name that holds the persistent variable. This assumes the variable was previously set with the same store name.

""

Example: %GET{"lunch"}% returns Sushi if the following has been previously set:%SET{ "lunch" value="Sushi" }%

JSON Syntax: %GET{ name }%

Example to set a JSON object and to get a JSON object with a JSON path:

JSON Objects

JSON (JavaScript Object Notation) is a lightweight data-interchange format based on a subset of the JavaScript Programming Language. It is easy for humans to read and write, and easy for machines to parse and generate.

Setting a JSON object returns an empty string. In case of a parse error, the named variable contains the error message starting with ERROR:

An optional remember="1" or store="some_name" parameter can be added. Use one or the other, not both. If specified, the JSON object will be stored persistently so that it can be used later in any TWiki topic. The remember="1" option stores the JSON object in the default store; with store="..." you can specify a store name to save the JSON object.

GET a JSON Object

The syntax to get a JSON object is %GET{ name }% to get the full object, or %GET{ name.path }% to get a sub-part of the object using a JSON path.

Search and save result

A SEARCH result can be assigned to a variable for later use. This can be useful for performance reasons if you need the result multiple times. The result can also be post-processed, such as with a $LISTMAP() of the SpreadSheetPlugin.

REST Interface

Variables can also be set and retrieved by invoking a REST (REpresentational State Transfer) request on the TWiki server using the rest script. To persistently remember the state of interactive browser-based JavaScript applications, you can set and get variables using this REST interface via Ajax calls.

The rest script requires authentication, e.g. the user agent is prompted to authenticate if needed.

rest/SetGetPlugin/set -- set a variable

To set a variable call %SCRIPTURL{rest}%/SetGetPlugin/set. It accepts the following URL parameters:

name - name of variable (required)

value - value of variable (required, may be empty)

remember - persistently remember if set to 1 (optional)

store - specify a store name to persistently store the variable (optional)