Difference: SetGetPlugin (1 vs. 6)

Revision 62015-07-09 - TWikiContributor

 

SetGetPlugin 

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
Changed:
<
<
>
>
 
Page contents
Set and get variables and JSON objects in topics, optionally persistently across topic views

Introduction

Changed:
<
<		Use %SET{}% to store arbitrary text in a named variable, and reuse it with %GET{}% later on within the topic or an included topics. By default, variables live only during topic rendering time, e.g. they do not persist between topic views. It is also possible to remember the variables between topic views, however they are not version controlled like other content in TWiki.
>
>		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.
Changed:
<
<		Alternatives to this plugin are:
>
>		Alternatives to this plugin:
 
Changed:
<
<
  • 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 %CALC{$SET(some_name, anything)}% and retrieved with $GET(). These variables persist during page rendering time. A limitation of %CALC{} is that it does not follow the standard TWiki variable evaluation order (nesting inside out, left to right).
>
>
  • 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.
  • Syntax: %SET{ "name" value="..." remember="1" }%
  • Parameters:
    Parameter Description Default
    "name" 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.
  • Example to set, modify and get a JSON object:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","F"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.File.Open[1] = "T" }% - modify a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.Edit.Cut = [ "cut", "T" ] }% - add to a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"],"Cut":["cut","T"]}}
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SETGETDUMP, SpreadSheetPlugin#FuncSET

Changed:
<
<		ALERT! Important notes when using the remember option:
  • 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 named "campaign", use a more descriptive name "Marketing-Europe-2025-Campaign".
>
>		ALERT! Important notes when using the remember or store option:
  • 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-2025-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.
Changed:
<
<
  • Variables are not version controlled, e.g. you do not get the audit trail you have elsewhere in TWiki (topics, attachments, meta data, etc). Consider storing content in TWiki form fields if you need an audit trail.
>
>
  • 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

  • Get the value of a named variable, previously set with %SET{}%.
  • Syntax: %GET{ "name" default="..." }%
  • Parameters:
    Parameter Description Default
    "name" 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:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu.File.Open }% - returns: ["open","F"]
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: IF, SET, SETGETDUMP, SpreadSheetPlugin#FuncGET

SETGETDUMP{...} -- dump variables

  • Dump volatile or persistent name/values previously set with %SET{}%.
  • Syntax: %SETGETDUMP{ remember="1" format="..." separator="..." }%
  • Parameters:
    Parameter Description Default
    remember="1" Dump all persistent variables (volatile variables)
    store="..." Dump variables of a specific store (volatile variables)
    format="..." Format output using variables $name and $value "name: $name, value: $value <br />"
    separator="..." String used for separating entries "\n"
  • Example: %SETGETDUMP{"| $name | $value |" separator="$n"}%
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SET, SpreadSheetPlugin#FuncSET
Added:
>
>

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.

A JSON object can contain:

  • { "key1": "value1", "key2": "value2", ... } - hash with key/value pairs; the value can be another JSON object
  • [ "va1", "val2", "val3", ... ] - array with values; the value can be another JSON object
  • "String" - text string enclosed in double quotes

A JSON object can be nested to any depth.

Using SET and GET it is possible to store and retrieve JSON objects, and parts thereof using a JSON path. A JSON path describes the path to an object within a JSON object.

JSON objects are useful in advanced TWiki applications that use JavaScript and Ajax calls. This plugin makes it easy to store and manipulate JSON objects.

Note: The CPAN:JSON module needs to be installed on the TWiki server.

SET a JSON Object

The syntax to set a JSON object is %SET{ name = object }% or %SET{ name.path = object }%.

  • name - variable name, such as: menu
    • supported characters: alphanumeric, dash and underscore
  • .path - JSON path, such as: .File.Open[1] in menu.File.Open[1]
    • JSON path fragment for a hash object is .hashName, such as: .File
      • supported characters for hash object name: alphanumeric, dash, underscore and dollar sign
    • JSON path fragment for an array object is [n], such as: [1]
      • supported characters for array index: non-negative integers
  • object - JSON object, simple (hash, array, string) or nested, such as:
    • { "Breakfast": "cereal", "Lunch": "salad", "Dinner": "Sushi" } - hash with key/value pairs; the value can be another JSON object
    • [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ] - array with values; the value can be another JSON object
    • "Sushi" - text string enclosed in double quotes

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.

  • name - variable name, such as: menu
    • supported characters: alphanumeric, dash and underscore
  • .path - JSON path, such as: .File.Open[1] in menu.File.Open[1]
    • JSON path fragment for a hash object is .hashName, such as: .File
      • supported characters for hash object name: alphanumeric, dash, underscore and dollar sign
    • JSON path fragment for an array object is [n], such as: [1]
      • supported characters for array index: non-negative integers [0]...[9999] and asterisk [*]
      • use an [*] asterisk wildcard to indicate all array items (only one wildcard can be used in a JSON path)

GET returns the JSON object or an object within it. The format depends on the type of object:

  • hash object: {"key1":"value1","key2":"value2"} - hash with key/value pairs; space trimmed; nondeterministic sequence; the value can be another JSON object
  • array object: ["va1","val2","val3"] - array with values; space trimmed; the value can be another JSON object
  • string object: String - text string, without enclosing double quotes

JSON Examples

Example to set, modify and get a JSON object:

  • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
  • %GET{ menu }% - get the JSON object, returns: {"File":{"New":["new","F"],"Open":["open","F"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
  • %GET{ menu.File.Open }% - get a JSON object using JSON path, returns: ["open","F"]
  • %SET{ menu.File.Open[1] = "T" }% - modify a JSON object
  • %GET{ menu }% - get the JSON object, returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
  • %SET{ menu.Edit.Cut = [ "cut", "T" ] }% - add to a JSON object
  • %GET{ menu }% - get the JSON object, returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"],"Cut":["cut","T"]}}

Example to set and get a JSON array of hashes object, using JSON path with [*] wildcard:

  • %SET{ projects = [ { "name": "Prj A", "key": "PrjA", "owner": { "name": "Aaron", "id": 1 } }, { "name": "Prj B", "key": "PrjB", "owner": { "name": "Boris", "id": 2 } }, { "name": "Prj C", "key": "PrjC", "owner": { "name": "Charlie", "id": 3 } } ] }% - set a JSON array of hashes object
  • %GET{ projects[1] }% - get the second array item of the JSON object using JSON path, returns: {"owner":{"name":"Boris"},"name":"Prj B","key":"PrjB"}
  • %GET{ projects[1].name }% - get the project name of the second array item, returns: Prj B
  • %GET{ projects[*].name }% - use wildcard to get all project names, returns: ["Prj A","Prj B","Prj C"]
  • %GET{ projects[*].owner }% - use wildcard to get all project owner objects, returns: [{"name":"Aaron"},{"name":"Boris"},{"name":"Charlie"}]
  • %GET{ projects[*].owner.name }% - use wildcard to get all project owner names, returns: ["Aaron","Boris","Charlie"]
 
Changed:
<
<

Examples

>
>

SET/GET Examples

 

Set several times

A variable can be set and used several times.

Raw text: 

   * Set "demo" to "uno": %SET{ "demo" value="uno" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "due": %SET{ "demo" value="due" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "tre": %SET{ "demo" value="tre" }%
   * Get "demo": %GET{ "demo" }%

  Rendered text:

  • Set "demo" to "uno":
  • Get "demo": uno
  • Set "demo" to "due":
  • Get "demo": due
  • Set "demo" to "tre":
  • Get "demo": tre

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.

Raw text: 

%SET{
 "result"
 value="%SEARCH{
  "."
  topic="*Skin"
  nonoise="on"
  format="$topic"
  separator=", "
 }%"
}%
   * Result: %GET{result}%
   * Again: %GET{result}%

  Rendered text:

Last topic view

Changed:
<
<		In a topic, set a variable with the remember flag set that stores the current time. Add also a GET before the SET, it will show the time the topic has last been viewed.
>
>		In a topic, set a variable to save the current using the remember flag. Add also a GET before the SET, it will show the time the topic has last been viewed.
 
Raw text: 

   * Last view: %GET{ "SetGetPlugin-lastview" }%
   * Now: %SET{ "SetGetPlugin-lastview" remember="1" 
      value="%SERVERTIME{$year-$mo-$day $hou:$min:$sec}%"
     }%
     %GET{ "SetGetPlugin-lastview" }%

  Rendered text:

  • Last view: 2025-06-06 19:41:26
  • Now: 2025-06-06 19:41:26

Remember my mood

This example shows how you can remember the mood of users. The form shows a picklist to select a mood. The mood is stored persistently per user, and shown.

Raw text: 

%IF{
 "defined 'mood'"
 then="$percntSET{
  \"SetGetPlugin-mood-%WIKINAME%\" remember=\"1\" 
  value=\"%URLPARAM{mood}%\"
 }$percnt"
}%
My current mood:
&nbsp; %GET{ "SetGetPlugin-mood-%WIKINAME%" }%
for %WIKIUSERNAME%

<form action="%SCRIPTURL{view}%/%WEB%/%TOPIC%#MyMood">
Change my mood: <select name="mood">
<option>%URLPARAM{mood}%</option>
<option>:-D</option> <option>:-)</option>
<option>:-I</option> <option>:-(</option>
<option>:mad:</option>
</select>
<input type="submit" value="Set" class="twikiSubmit" />
</form>

  Rendered text:

My current mood:   for TWikiGuest

Change my mood:

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)
Added:
>
>
  • store - specify a store name to persistently store the variable (optional)
  Example:
http://master-wiki.cloudapp.net/do/rest/SetGetPlugin/set?name=rest-test;value=This+is+REST;remember=1

rest/SetGetPlugin/get -- get a variable

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

  • name - name of variable (required)
  • default - default returned if variable is not found (optional)
Added:
>
>
  • store - specify a store name that holds a persistent variable (optional)
  Example:
http://master-wiki.cloudapp.net/do/rest/SetGetPlugin/get?name=rest-test;default=rest-test+variable+not+found
Deleted:
<
<

Plugin Settings

Show details toggleopen.gif Hide details toggleclose.gif 
<--/twistyPlugin twikiMakeVisibleInline-->
Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %NEWPLUGIN_SHORTDESCRIPTION%

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Set and get variables in topics, optionally persistently across topic views

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0 
<--/twistyPlugin-->
 

Plugin Installation Instructions

This plugin is pre-installed. TWiki administrators can upgrade the plugin as needed on the TWiki server.

Added:
>
>
 
Show details toggleopen.gif Hide details toggleclose.gif 
<--/twistyPlugin twikiMakeVisibleInline-->

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip SetGetPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/SetGetPlugin.txt Plugin topic
      data/TWiki/VarGET.txt GET documentation
      data/TWiki/VarSET.txt SET documentation
      data/TWiki/VarSETGETDUMP.txt SETGETDUMP documentation
      lib/TWiki/Plugins/SetGetPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/SetGetPlugin/Core.pm Core Perl module
Added:
>
>
lib/TWiki/Plugins/SetGetPlugin/Config.spec Configuration file
 
    • Set the ownership of the extracted directories and files to the webserver user.
Added:
>
>
  • Plugin dependencies:
    • Install the CPAN:JSON module in case JSON objects are used.
    • Install the CPAN:Clone module if JSON path with [*] wildcard array index is used.
 
  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Test if the installation was successful: The next bullet should show: Result: TWiki rocks!
      • Result: TWiki rocks! 
<--/twistyPlugin-->

Plugin Info

Added:
>
>
  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Set and get variables and JSON objects in topics, optionally persistently across topic views
 
Plugin Author: TWiki:Main.PeterThoeny
Changed:
<
<
Copyright: © 2010-2013 TWiki:Main.PeterThoeny
© 2010-2013 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public Licen:se)
Plugin Version: 2013-01-28
>
>
Copyright: © 2015 Alba Power Quality Solutions
© 2015 Wave Systems Corp.
© 2010-2015 TWiki:Main.PeterThoeny
© 2010-2015 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Sponsor: Wave Systems Corp.
Added:
>
>
Plugin Version: 2015-07-09
 
Show Change History toggleopen.gif Hide Change History toggleclose.gif 
<--/twistyPlugin twikiMakeVisibleInline-->
Added:
>
>
2015-07-09: TWikibug:Item7675: GET with support for JSON path using [*] wildcard array index
2015-06-17: TWikibug:Item7639: Document CPAN:JSON dependency
2015-04-09: TWikibug:Item7639: Use file locking for persistent store files to prevent corruption of store
2015-04-09: TWikibug:Item7635: SETGETDUMP can now dump volatile variables
2015-04-09: TWikibug:Item7636: Init variables at plugin init time (was not the case in a mod_perl environment)
2015-04-07: TWikibug:Item7635: Ability to specify store name to persistently store variables
2015-03-31: TWikibug:Item7611: Small doc fix
2015-03-27: TWikibug:Item7611: Support for JSON objects and JSON path
2015-03-25: TWikibug:Item7611: Switch debug flag from preferences setting to configure setting
2015-01-15: TWikibug:Item7604: Switch from GPL v2 to v3
 
2013-01-28: TWikibug:Item7091: Use TWISTY in installation instructions and change history
2012-11-12: TWikibug:Item7032: GET variable with format parameter
2012-11-12: TWikibug:Item7020: Categorize TWiki Variable SET, GET, SETGETDUMP
2012-10-11: TWikibug:Item6978: SetGetPlugin::Core::_savePersistentVar() may fail at Data::Dumper->Dump(). "require Data::Dumper;" line added before that. -- TWiki:Main.HideyoImazu
2012-09-25: TWikibug:Item6943: Add REST interface
2012-01-06: TWikibug:Item6828: Removing write to persistent if already exists, and adding data dump -- TWiki:Main.AaronLWalker
2011-07-09: TWikibug:Item6725: Change global package variables from "use vars" to "our"
2011-04-04: TWikibug:Item6638: Small doc improvements
2011-03-26: TWikibug:Item6670: Make variables persistent across topic invocations
2010-10-17: TWikibug:Item6597: Initial version 
<--/twistyPlugin-->
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
Changed:
<
<
CPAN Dependencies: none
>
>
CPAN Dependencies: CPAN:JSON - optional, required if JSON objects are used;
CPAN:Clone - optional, required if JSON path with [*] wildcard array index is used
 
Other Dependencies: none
Perl Version: 5.005
Benchmarks: GoodStyle 100%, FormattedSearch 99%, SetGetPlugin 99%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/SetGetPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginAppraisal
Changed:
<
<		Related Topics: VarSET, VarGET, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences, SpreadSheetPlugin
>
>		Related Topics: VarSET, VarGET, VarSETGETDUMP, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences, SpreadSheetPlugin
 

Revision 52013-01-29 - TWikiContributor

 

SetGetPlugin 

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
Set and get variables and JSON objects in topics, optionally persistently across topic views

Introduction

Use %SET{}% to store arbitrary text in a named variable, and reuse it with %GET{}% later on within the topic or an included topics. By default, variables live only during topic rendering time, e.g. they do not persist between topic views. It is also possible to remember the variables between topic views, however they are not version controlled like other content in TWiki.

%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 are:

  • 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 %CALC{$SET(some_name, anything)}% and retrieved with $GET(). These variables persist during page rendering time. A limitation of %CALC{} is that it does not follow the standard TWiki variable evaluation order (nesting inside out, left to right).

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.
  • Syntax: %SET{ "name" value="..." remember="1" }%
  • Parameters:
    Parameter Description Default
    "name" 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.
  • Example to set, modify and get a JSON object:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","F"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.File.Open[1] = "T" }% - modify a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.Edit.Cut = [ "cut", "T" ] }% - add to a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"],"Cut":["cut","T"]}}
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SETGETDUMP, SpreadSheetPlugin#FuncSET

ALERT! Important notes when using the remember option:

  • 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 named "campaign", use a more descriptive name "Marketing-Europe-2025-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 you have 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

  • Get the value of a named variable, previously set with %SET{}%.
  • Syntax: %GET{ "name" default="..." }%
  • Parameters:
    Parameter Description Default
    "name" 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:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu.File.Open }% - returns: ["open","F"]
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: IF, SET, SETGETDUMP, SpreadSheetPlugin#FuncGET

SETGETDUMP{...} -- dump variables

  • Dump volatile or persistent name/values previously set with %SET{}%.
  • Syntax: %SETGETDUMP{ remember="1" format="..." separator="..." }%
  • Parameters:
    Parameter Description Default
    remember="1" Dump all persistent variables (volatile variables)
    store="..." Dump variables of a specific store (volatile variables)
    format="..." Format output using variables $name and $value "name: $name, value: $value <br />"
    separator="..." String used for separating entries "\n"
  • Example: %SETGETDUMP{"| $name | $value |" separator="$n"}%
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SET, SpreadSheetPlugin#FuncSET

Examples

Set several times

A variable can be set and used several times.

Raw text: 

   * Set "demo" to "uno": %SET{ "demo" value="uno" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "due": %SET{ "demo" value="due" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "tre": %SET{ "demo" value="tre" }%
   * Get "demo": %GET{ "demo" }%

  Rendered text:

  • Set "demo" to "uno":
  • Get "demo": uno
  • Set "demo" to "due":
  • Get "demo": due
  • Set "demo" to "tre":
  • Get "demo": tre

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.

Raw text: 

%SET{
 "result"
 value="%SEARCH{
  "."
  topic="*Skin"
  nonoise="on"
  format="$topic"
  separator=", "
 }%"
}%
   * Result: %GET{result}%
   * Again: %GET{result}%

  Rendered text:

Last topic view

In a topic, set a variable with the remember flag set that stores the current time. Add also a GET before the SET, it will show the time the topic has last been viewed.

Raw text: 

   * Last view: %GET{ "SetGetPlugin-lastview" }%
   * Now: %SET{ "SetGetPlugin-lastview" remember="1" 
      value="%SERVERTIME{$year-$mo-$day $hou:$min:$sec}%"
     }%
     %GET{ "SetGetPlugin-lastview" }%

  Rendered text:

  • Last view: 2025-06-06 19:41:26
  • Now: 2025-06-06 19:41:27

Remember my mood

This example shows how you can remember the mood of users. The form shows a picklist to select a mood. The mood is stored persistently per user, and shown.

Raw text: 

%IF{
 "defined 'mood'"
 then="$percntSET{
  \"SetGetPlugin-mood-%WIKINAME%\" remember=\"1\" 
  value=\"%URLPARAM{mood}%\"
 }$percnt"
}%
My current mood:
&nbsp; %GET{ "SetGetPlugin-mood-%WIKINAME%" }%
for %WIKIUSERNAME%

<form action="%SCRIPTURL{view}%/%WEB%/%TOPIC%#MyMood">
Change my mood: <select name="mood">
<option>%URLPARAM{mood}%</option>
<option>:-D</option> <option>:-)</option>
<option>:-I</option> <option>:-(</option>
<option>:mad:</option>
</select>
<input type="submit" value="Set" class="twikiSubmit" />
</form>

  Rendered text:

My current mood:   for TWikiGuest

Change my mood:

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)

Example:
http://master-wiki.cloudapp.net/do/rest/SetGetPlugin/set?name=rest-test;value=This+is+REST;remember=1

rest/SetGetPlugin/get -- get a variable

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

  • name - name of variable (required)
  • default - default returned if variable is not found (optional)

Example:
http://master-wiki.cloudapp.net/do/rest/SetGetPlugin/get?name=rest-test;default=rest-test+variable+not+found

Plugin Settings

Added:
>
>
Show details toggleopen.gif Hide details toggleclose.gif 
<--/twistyPlugin twikiMakeVisibleInline-->
 Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %NEWPLUGIN_SHORTDESCRIPTION%

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Set and get variables in topics, optionally persistently across topic views

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0
Added:
>
>		 
<--/twistyPlugin-->
 

Plugin Installation Instructions

Changed:
<
<		Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.
>
>		This plugin is pre-installed. TWiki administrators can upgrade the plugin as needed on the TWiki server.
Added:
>
>
Show details toggleopen.gif Hide details toggleclose.gif 
<--/twistyPlugin twikiMakeVisibleInline-->
 
  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip SetGetPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/SetGetPlugin.txt Plugin topic
      data/TWiki/VarGET.txt GET documentation
      data/TWiki/VarSET.txt SET documentation
      data/TWiki/VarSETGETDUMP.txt SETGETDUMP documentation
      lib/TWiki/Plugins/SetGetPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/SetGetPlugin/Core.pm Core Perl module
    • Set the ownership of the extracted directories and files to the webserver user.

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Test if the installation was successful: The next bullet should show: Result: TWiki rocks!
      • Result: TWiki rocks!
Added:
>
>		 
<--/twistyPlugin-->
 

Plugin Info

Added:
>
>
 
Plugin Author: TWiki:Main.PeterThoeny
Changed:
<
<
Copyright: © 2010-2012 TWiki:Main.PeterThoeny
© 2010-2012 TWiki:TWiki.TWikiContributor
>
>
Copyright: © 2010-2013 TWiki:Main.PeterThoeny
© 2010-2013 TWiki:TWiki.TWikiContributor
 
License: GPL (GNU General Public Licen:se)
Changed:
<
<
Plugin Version: 2012-11-12
Change History: 
<-- versions below in reverse order -->
 
>
>
Plugin Version: 2013-01-28
%TWISTY{
Added:
>
>		 mode="div" showlink="Show Change History http://master-wiki.cloudapp.net/twiki/pub/TWiki/TWikiDocGraphics/toggleopen.gif" hidelink="Hide Change History toggleclose.gif " }%
2013-01-28: TWikibug:Item7091: Use TWISTY in installation instructions and change history
 
2012-11-12: TWikibug:Item7032: GET variable with format parameter
2012-11-12: TWikibug:Item7020: Categorize TWiki Variable SET, GET, SETGETDUMP
2012-10-11: TWikibug:Item6978: SetGetPlugin::Core::_savePersistentVar() may fail at Data::Dumper->Dump(). "require Data::Dumper;" line added before that. -- TWiki:Main.HideyoImazu
2012-09-25: TWikibug:Item6943: Add REST interface
2012-01-06: TWikibug:Item6828: Removing write to persistent if already exists, and adding data dump -- TWiki:Main.AaronLWalker
2011-07-09: TWikibug:Item6725: Change global package variables from "use vars" to "our"
2011-04-04: TWikibug:Item6638: Small doc improvements
2011-03-26: TWikibug:Item6670: Make variables persistent across topic invocations
2010-10-17: TWikibug:Item6597: Initial version
Added:
>
>		</> 
<--/twistyPlugin-->
 
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Benchmarks: GoodStyle 100%, FormattedSearch 99%, SetGetPlugin 99%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/SetGetPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginAppraisal

Related Topics: VarSET, VarGET, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences, SpreadSheetPlugin

Revision 42012-11-13 - TWikiContributor

 

SetGetPlugin 

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
Set and get variables and JSON objects in topics, optionally persistently across topic views

Introduction

Use %SET{}% to store arbitrary text in a named variable, and reuse it with %GET{}% later on within the topic or an included topics. By default, variables live only during topic rendering time, e.g. they do not persist between topic views. It is also possible to remember the variables between topic views, however they are not version controlled like other content in TWiki.

%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 are:

  • 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 %CALC{$SET(some_name, anything)}% and retrieved with $GET(). These variables persist during page rendering time. A limitation of %CALC{} is that it does not follow the standard TWiki variable evaluation order (nesting inside out, left to right).

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.
  • Syntax: %SET{ "name" value="..." remember="1" }%
  • Parameters:
    Parameter Description Default
    "name" 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.
  • Example to set, modify and get a JSON object:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","F"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.File.Open[1] = "T" }% - modify a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.Edit.Cut = [ "cut", "T" ] }% - add to a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"],"Cut":["cut","T"]}}
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SETGETDUMP, SpreadSheetPlugin#FuncSET

ALERT! Important notes when using the remember option:

  • 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 named "campaign", use a more descriptive name "Marketing-Europe-2025-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 you have 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

  • Get the value of a named variable, previously set with %SET{}%.
  • Syntax: %GET{ "name" default="..." }%
  • Parameters:
    Parameter Description Default
    "name" 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:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu.File.Open }% - returns: ["open","F"]
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: IF, SET, SETGETDUMP, SpreadSheetPlugin#FuncGET

SETGETDUMP{...} -- dump variables

  • Dump volatile or persistent name/values previously set with %SET{}%.
  • Syntax: %SETGETDUMP{ remember="1" format="..." separator="..." }%
  • Parameters:
    Parameter Description Default
    remember="1" Dump all persistent variables (volatile variables)
    store="..." Dump variables of a specific store (volatile variables)
    format="..." Format output using variables $name and $value "name: $name, value: $value <br />"
    separator="..." String used for separating entries "\n"
  • Example: %SETGETDUMP{"| $name | $value |" separator="$n"}%
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SET, SpreadSheetPlugin#FuncSET

Examples

Set several times

A variable can be set and used several times.

Raw text: 

   * Set "demo" to "uno": %SET{ "demo" value="uno" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "due": %SET{ "demo" value="due" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "tre": %SET{ "demo" value="tre" }%
   * Get "demo": %GET{ "demo" }%

  Rendered text:

  • Set "demo" to "uno":
  • Get "demo": uno
  • Set "demo" to "due":
  • Get "demo": due
  • Set "demo" to "tre":
  • Get "demo": tre

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.

Raw text: 

%SET{
 "result"
 value="%SEARCH{
  "."
  topic="*Skin"
  nonoise="on"
  format="$topic"
  separator=", "
 }%"
}%
   * Result: %GET{result}%
   * Again: %GET{result}%

  Rendered text:

Last topic view

In a topic, set a variable with the remember flag set that stores the current time. Add also a GET before the SET, it will show the time the topic has last been viewed.

Raw text: 

   * Last view: %GET{ "SetGetPlugin-lastview" }%
   * Now: %SET{ "SetGetPlugin-lastview" remember="1" 
      value="%SERVERTIME{$year-$mo-$day $hou:$min:$sec}%"
     }%
     %GET{ "SetGetPlugin-lastview" }%

  Rendered text:

  • Last view: 2025-06-06 19:41:27
  • Now: 2025-06-06 19:41:28

Remember my mood

This example shows how you can remember the mood of users. The form shows a picklist to select a mood. The mood is stored persistently per user, and shown.

Raw text: 

%IF{
 "defined 'mood'"
 then="$percntSET{
  \"SetGetPlugin-mood-%WIKINAME%\" remember=\"1\" 
  value=\"%URLPARAM{mood}%\"
 }$percnt"
}%
My current mood:
&nbsp; %GET{ "SetGetPlugin-mood-%WIKINAME%" }%
for %WIKIUSERNAME%

<form action="%SCRIPTURL{view}%/%WEB%/%TOPIC%#MyMood">
Change my mood: <select name="mood">
<option>%URLPARAM{mood}%</option>
<option>:-D</option> <option>:-)</option>
<option>:-I</option> <option>:-(</option>
<option>:mad:</option>
</select>
<input type="submit" value="Set" class="twikiSubmit" />
</form>

  Rendered text:

My current mood:   for TWikiGuest

Change my mood:

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)

Example:
http://master-wiki.cloudapp.net/do/rest/SetGetPlugin/set?name=rest-test;value=This+is+REST;remember=1

rest/SetGetPlugin/get -- get a variable

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

  • name - name of variable (required)
  • default - default returned if variable is not found (optional)

Example:
http://master-wiki.cloudapp.net/do/rest/SetGetPlugin/get?name=rest-test;default=rest-test+variable+not+found

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %NEWPLUGIN_SHORTDESCRIPTION%

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Set and get variables in topics, optionally persistently across topic views

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip SetGetPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/SetGetPlugin.txt Plugin topic
      data/TWiki/VarGET.txt GET documentation
      data/TWiki/VarSET.txt SET documentation
      data/TWiki/VarSETGETDUMP.txt SETGETDUMP documentation
      lib/TWiki/Plugins/SetGetPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/SetGetPlugin/Core.pm Core Perl module
    • Set the ownership of the extracted directories and files to the webserver user.

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Test if the installation was successful: The next bullet should show: Result: TWiki rocks!
      • Result: TWiki rocks!

Plugin Info

Plugin Author: TWiki:Main.PeterThoeny
Copyright: © 2010-2012 TWiki:Main.PeterThoeny
© 2010-2012 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public Licen:se)
Changed:
<
<
Plugin Version: 2012-09-25
>
>
Plugin Version: 2012-11-12
 
Change History: 
<-- versions below in reverse order -->
 
Added:
>
>
2012-11-12: TWikibug:Item7032: GET variable with format parameter
2012-11-12: TWikibug:Item7020: Categorize TWiki Variable SET, GET, SETGETDUMP
2012-10-11: TWikibug:Item6978: SetGetPlugin::Core::_savePersistentVar() may fail at Data::Dumper->Dump(). "require Data::Dumper;" line added before that. -- TWiki:Main.HideyoImazu
 
2012-09-25: TWikibug:Item6943: Add REST interface
2012-01-06: TWikibug:Item6828: Removing write to persistent if already exists, and adding data dump -- TWiki:Main.AaronLWalker
2011-07-09: TWikibug:Item6725: Change global package variables from "use vars" to "our"
2011-04-04: TWikibug:Item6638: Small doc improvements
2011-03-26: TWikibug:Item6670: Make variables persistent across topic invocations
2010-10-17: TWikibug:Item6597: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Benchmarks: GoodStyle 100%, FormattedSearch 99%, SetGetPlugin 99%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/SetGetPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginAppraisal

Related Topics: VarSET, VarGET, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences, SpreadSheetPlugin

Revision 32012-09-26 - TWikiContributor

 

SetGetPlugin 

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
Set and get variables and JSON objects in topics, optionally persistently across topic views

Introduction

Use %SET{}% to store arbitrary text in a named variable, and reuse it with %GET{}% later on within the topic or an included topics. By default, variables live only during topic rendering time, e.g. they do not persist between topic views. It is also possible to remember the variables between topic views, however they are not version controlled like other content in TWiki.

%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 are:

  • 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 %CALC{$SET(some_name, anything)}% and retrieved with $GET(). These variables persist during page rendering time. A limitation of %CALC{} is that it does not follow the standard TWiki variable evaluation order (nesting inside out, left to right).

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.
  • Syntax: %SET{ "name" value="..." remember="1" }%
  • Parameters:
    Parameter Description Default
    "name" 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.
  • Example to set, modify and get a JSON object:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","F"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.File.Open[1] = "T" }% - modify a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.Edit.Cut = [ "cut", "T" ] }% - add to a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"],"Cut":["cut","T"]}}
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SETGETDUMP, SpreadSheetPlugin#FuncSET

ALERT! Important notes when using the remember option:

  • 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 named "campaign", use a more descriptive name "Marketing-Europe-2025-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 you have 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

  • Get the value of a named variable, previously set with %SET{}%.
  • Syntax: %GET{ "name" default="..." }%
  • Parameters:
    Parameter Description Default
    "name" 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:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu.File.Open }% - returns: ["open","F"]
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: IF, SET, SETGETDUMP, SpreadSheetPlugin#FuncGET

SETGETDUMP{...} -- dump variables

  • Dump volatile or persistent name/values previously set with %SET{}%.
  • Syntax: %SETGETDUMP{ remember="1" format="..." separator="..." }%
  • Parameters:
    Parameter Description Default
    remember="1" Dump all persistent variables (volatile variables)
    store="..." Dump variables of a specific store (volatile variables)
    format="..." Format output using variables $name and $value "name: $name, value: $value <br />"
    separator="..." String used for separating entries "\n"
  • Example: %SETGETDUMP{"| $name | $value |" separator="$n"}%
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SET, SpreadSheetPlugin#FuncSET

Examples

Set several times

A variable can be set and used several times.

Raw text: 

   * Set "demo" to "uno": %SET{ "demo" value="uno" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "due": %SET{ "demo" value="due" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "tre": %SET{ "demo" value="tre" }%
   * Get "demo": %GET{ "demo" }%

  Rendered text:

  • Set "demo" to "uno":
  • Get "demo": uno
  • Set "demo" to "due":
  • Get "demo": due
  • Set "demo" to "tre":
  • Get "demo": tre

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.

Raw text: 

%SET{
 "result"
 value="%SEARCH{
  "."
  topic="*Skin"
  nonoise="on"
  format="$topic"
  separator=", "
 }%"
}%
   * Result: %GET{result}%
   * Again: %GET{result}%

  Rendered text:

Last topic view

In a topic, set a variable with the remember flag set that stores the current time. Add also a GET before the SET, it will show the time the topic has last been viewed.

Raw text: 

   * Last view: %GET{ "SetGetPlugin-lastview" }%
   * Now: %SET{ "SetGetPlugin-lastview" remember="1" 
      value="%SERVERTIME{$year-$mo-$day $hou:$min:$sec}%"
     }%
     %GET{ "SetGetPlugin-lastview" }%

  Rendered text:

  • Last view: 2025-06-06 19:41:28
  • Now: 2025-06-06 19:41:28

Remember my mood

This example shows how you can remember the mood of users. The form shows a picklist to select a mood. The mood is stored persistently per user, and shown.

Raw text: 

%IF{
 "defined 'mood'"
 then="$percntSET{
  \"SetGetPlugin-mood-%WIKINAME%\" remember=\"1\" 
  value=\"%URLPARAM{mood}%\"
 }$percnt"
}%
My current mood:
&nbsp; %GET{ "SetGetPlugin-mood-%WIKINAME%" }%
for %WIKIUSERNAME%

<form action="%SCRIPTURL{view}%/%WEB%/%TOPIC%#MyMood">
Change my mood: <select name="mood">
<option>%URLPARAM{mood}%</option>
<option>:-D</option> <option>:-)</option>
<option>:-I</option> <option>:-(</option>
<option>:mad:</option>
</select>
<input type="submit" value="Set" class="twikiSubmit" />
</form>

  Rendered text:

My current mood:   for TWikiGuest

Change my mood:
Added:
>
>

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)

Example:
http://master-wiki.cloudapp.net/do/rest/SetGetPlugin/set?name=rest-test;value=This+is+REST;remember=1

rest/SetGetPlugin/get -- get a variable

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

  • name - name of variable (required)
  • default - default returned if variable is not found (optional)

Example:
http://master-wiki.cloudapp.net/do/rest/SetGetPlugin/get?name=rest-test;default=rest-test+variable+not+found

 

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %NEWPLUGIN_SHORTDESCRIPTION%

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Set and get variables in topics, optionally persistently across topic views

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip SetGetPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/SetGetPlugin.txt Plugin topic
      data/TWiki/VarGET.txt GET documentation
      data/TWiki/VarSET.txt SET documentation
      data/TWiki/VarSETGETDUMP.txt SETGETDUMP documentation
      lib/TWiki/Plugins/SetGetPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/SetGetPlugin/Core.pm Core Perl module
    • Set the ownership of the extracted directories and files to the webserver user.

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
Changed:
<
<
    • Test if the installation was successful: The next bullet should show: Result: Yes, it works!
>
>
    • Test if the installation was successful: The next bullet should show: Result: TWiki rocks!
 
      • Result: TWiki rocks!

Plugin Info

Plugin Author: TWiki:Main.PeterThoeny
Copyright: © 2010-2012 TWiki:Main.PeterThoeny
© 2010-2012 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public Licen:se)
Changed:
<
<
Plugin Version: 2012-01-06
>
>
Plugin Version: 2012-09-25
 
Change History: 
<-- versions below in reverse order -->
 
Added:
>
>
2012-09-25: TWikibug:Item6943: Add REST interface
 
2012-01-06: TWikibug:Item6828: Removing write to persistent if already exists, and adding data dump -- TWiki:Main.AaronLWalker
2011-07-09: TWikibug:Item6725: Change global package variables from "use vars" to "our"
2011-04-04: TWikibug:Item6638: Small doc improvements
2011-03-26: TWikibug:Item6670: Make variables persistent across topic invocations
2010-10-17: TWikibug:Item6597: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Benchmarks: GoodStyle 100%, FormattedSearch 99%, SetGetPlugin 99%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/SetGetPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginAppraisal

Related Topics: VarSET, VarGET, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences, SpreadSheetPlugin

Revision 22012-01-15 - TWikiContributor

 

SetGetPlugin 

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
Set and get variables and JSON objects in topics, optionally persistently across topic views

Introduction

Use %SET{}% to store arbitrary text in a named variable, and reuse it with %GET{}% later on within the topic or an included topics. By default, variables live only during topic rendering time, e.g. they do not persist between topic views. It is also possible to remember the variables between topic views, however they are not version controlled like other content in TWiki.

%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 are:

  • 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 %CALC{$SET(some_name, anything)}% and retrieved with $GET(). These variables persist during page rendering time. A limitation of %CALC{} is that it does not follow the standard TWiki variable evaluation order (nesting inside out, left to right).

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.
  • Syntax: %SET{ "name" value="..." remember="1" }%
  • Parameters:
    Parameter Description Default
    "name" 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.
  • Example to set, modify and get a JSON object:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","F"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.File.Open[1] = "T" }% - modify a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.Edit.Cut = [ "cut", "T" ] }% - add to a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"],"Cut":["cut","T"]}}
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SETGETDUMP, SpreadSheetPlugin#FuncSET

ALERT! Important notes when using the remember option:

  • 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 named "campaign", use a more descriptive name "Marketing-Europe-2025-Campaign".
Changed:
<
<
  • 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 can read the content.
>
>
  • 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 you have 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

  • Get the value of a named variable, previously set with %SET{}%.
  • Syntax: %GET{ "name" default="..." }%
  • Parameters:
    Parameter Description Default
    "name" 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:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu.File.Open }% - returns: ["open","F"]
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: IF, SET, SETGETDUMP, SpreadSheetPlugin#FuncGET
Added:
>
>

SETGETDUMP{...} -- dump variables

  • Dump volatile or persistent name/values previously set with %SET{}%.
  • Syntax: %SETGETDUMP{ remember="1" format="..." separator="..." }%
  • Parameters:
    Parameter Description Default
    remember="1" Dump all persistent variables (volatile variables)
    store="..." Dump variables of a specific store (volatile variables)
    format="..." Format output using variables $name and $value "name: $name, value: $value <br />"
    separator="..." String used for separating entries "\n"
  • Example: %SETGETDUMP{"| $name | $value |" separator="$n"}%
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SET, SpreadSheetPlugin#FuncSET
 

Examples

Set several times

A variable can be set and used several times.

Raw text: 

   * Set "demo" to "uno": %SET{ "demo" value="uno" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "due": %SET{ "demo" value="due" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "tre": %SET{ "demo" value="tre" }%
   * Get "demo": %GET{ "demo" }%

  Rendered text:

  • Set "demo" to "uno":
  • Get "demo": uno
  • Set "demo" to "due":
  • Get "demo": due
  • Set "demo" to "tre":
  • Get "demo": tre

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.

Raw text: 

%SET{
 "result"
 value="%SEARCH{
  "."
  topic="*Skin"
  nonoise="on"
  format="$topic"
  separator=", "
 }%"
}%
   * Result: %GET{result}%
   * Again: %GET{result}%

  Rendered text:

Last topic view

In a topic, set a variable with the remember flag set that stores the current time. Add also a GET before the SET, it will show the time the topic has last been viewed.

Raw text: 

   * Last view: %GET{ "SetGetPlugin-lastview" }%
   * Now: %SET{ "SetGetPlugin-lastview" remember="1" 
      value="%SERVERTIME{$year-$mo-$day $hou:$min:$sec}%"
     }%
     %GET{ "SetGetPlugin-lastview" }%

  Rendered text:

  • Last view: 2025-06-06 19:41:29
  • Now: 2025-06-06 19:41:29

Remember my mood

This example shows how you can remember the mood of users. The form shows a picklist to select a mood. The mood is stored persistently per user, and shown.

Raw text: 

%IF{
 "defined 'mood'"
 then="$percntSET{
  \"SetGetPlugin-mood-%WIKINAME%\" remember=\"1\" 
  value=\"%URLPARAM{mood}%\"
 }$percnt"
}%
My current mood:
&nbsp; %GET{ "SetGetPlugin-mood-%WIKINAME%" }%
for %WIKIUSERNAME%

<form action="%SCRIPTURL{view}%/%WEB%/%TOPIC%#MyMood">
Change my mood: <select name="mood">
<option>%URLPARAM{mood}%</option>
<option>:-D</option> <option>:-)</option>
<option>:-I</option> <option>:-(</option>
<option>:mad:</option>
</select>
<input type="submit" value="Set" class="twikiSubmit" />
</form>

  Rendered text:

My current mood:   for TWikiGuest

Change my mood:

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %NEWPLUGIN_SHORTDESCRIPTION%

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Set and get variables in topics, optionally persistently across topic views

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip SetGetPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/SetGetPlugin.txt Plugin topic
      data/TWiki/VarGET.txt GET documentation
      data/TWiki/VarSET.txt SET documentation
Added:
>
>
data/TWiki/VarSETGETDUMP.txt SETGETDUMP documentation
 
lib/TWiki/Plugins/SetGetPlugin.pm Plugin Perl module
lib/TWiki/Plugins/SetGetPlugin/Core.pm Core Perl module
    • Set the ownership of the extracted directories and files to the webserver user.

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Test if the installation was successful: The next bullet should show: Result: Yes, it works!
      • Result: Yes, it works!

Plugin Info

Plugin Author: TWiki:Main.PeterThoeny
Changed:
<
<
Copyright: © 2010-2011 TWiki:Main.PeterThoeny
© 2010-2011 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Plugin Version: 2011-07-09
>
>
Copyright: © 2010-2012 TWiki:Main.PeterThoeny
© 2010-2012 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public Licen:se)
Plugin Version: 2012-01-06
 
Change History: 
<-- versions below in reverse order -->
 
Added:
>
>
2012-01-06: TWikibug:Item6828: Removing write to persistent if already exists, and adding data dump -- TWiki:Main.AaronLWalker
 
2011-07-09: TWikibug:Item6725: Change global package variables from "use vars" to "our"
2011-04-04: TWikibug:Item6638: Small doc improvements
2011-03-26: TWikibug:Item6670: Make variables persistent across topic invocations
2010-10-17: TWikibug:Item6597: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Benchmarks: GoodStyle 100%, FormattedSearch 99%, SetGetPlugin 99%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/SetGetPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginAppraisal

Related Topics: VarSET, VarGET, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences, SpreadSheetPlugin

Revision 12011-07-10 - TWikiContributor

 

SetGetPlugin 

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/SetGetPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
Set and get variables and JSON objects in topics, optionally persistently across topic views

Introduction

Use %SET{}% to store arbitrary text in a named variable, and reuse it with %GET{}% later on within the topic or an included topics. By default, variables live only during topic rendering time, e.g. they do not persist between topic views. It is also possible to remember the variables between topic views, however they are not version controlled like other content in TWiki.

%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 are:

  • 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 %CALC{$SET(some_name, anything)}% and retrieved with $GET(). These variables persist during page rendering time. A limitation of %CALC{} is that it does not follow the standard TWiki variable evaluation order (nesting inside out, left to right).

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.
  • Syntax: %SET{ "name" value="..." remember="1" }%
  • Parameters:
    Parameter Description Default
    "name" 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.
  • Example to set, modify and get a JSON object:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","F"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.File.Open[1] = "T" }% - modify a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"]}}
    • %SET{ menu.Edit.Cut = [ "cut", "T" ] }% - add to a JSON object
    • %GET{ menu }% - returns: {"File":{"New":["new","F"],"Open":["open","T"]},"Edit":{"Copy":["cpy","F"],"Paste":["pst","F"],"Cut":["cut","T"]}}
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: GET, IF, SETGETDUMP, SpreadSheetPlugin#FuncSET

ALERT! Important notes when using the remember option:

  • 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 named "campaign", use a more descriptive name "Marketing-Europe-2025-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 can read the content.
  • Variables are not version controlled, e.g. you do not get the audit trail you have 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

  • Get the value of a named variable, previously set with %SET{}%.
  • Syntax: %GET{ "name" default="..." }%
  • Parameters:
    Parameter Description Default
    "name" 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:
    • %SET{ menu = { "File": { "New": [ "new", "F" ], "Open": [ "open", "F" ] }, "Edit": { "Copy": [ "cpy", "F" ], "Paste": [ "pst", "F" ] } } }% - set a JSON object
    • %GET{ menu.File.Open }% - returns: ["open","F"]
  • Category: ApplicationsAndComponentsVariables, DevelopmentVariables
  • Related: IF, SET, SETGETDUMP, SpreadSheetPlugin#FuncGET

Examples

Set several times

A variable can be set and used several times.

Raw text: 

   * Set "demo" to "uno": %SET{ "demo" value="uno" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "due": %SET{ "demo" value="due" }%
   * Get "demo": %GET{ "demo" }%
   * Set "demo" to "tre": %SET{ "demo" value="tre" }%
   * Get "demo": %GET{ "demo" }%

  Rendered text:

  • Set "demo" to "uno":
  • Get "demo": uno
  • Set "demo" to "due":
  • Get "demo": due
  • Set "demo" to "tre":
  • Get "demo": tre

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.

Raw text: 

%SET{
 "result"
 value="%SEARCH{
  "."
  topic="*Skin"
  nonoise="on"
  format="$topic"
  separator=", "
 }%"
}%
   * Result: %GET{result}%
   * Again: %GET{result}%

  Rendered text:

Last topic view

In a topic, set a variable with the remember flag set that stores the current time. Add also a GET before the SET, it will show the time the topic has last been viewed.

Raw text: 

   * Last view: %GET{ "SetGetPlugin-lastview" }%
   * Now: %SET{ "SetGetPlugin-lastview" remember="1" 
      value="%SERVERTIME{$year-$mo-$day $hou:$min:$sec}%"
     }%
     %GET{ "SetGetPlugin-lastview" }%

  Rendered text:

  • Last view: 2025-06-06 19:41:29
  • Now: 2025-06-06 19:41:29

Remember my mood

This example shows how you can remember the mood of users. The form shows a picklist to select a mood. The mood is stored persistently per user, and shown.

Raw text: 

%IF{
 "defined 'mood'"
 then="$percntSET{
  \"SetGetPlugin-mood-%WIKINAME%\" remember=\"1\" 
  value=\"%URLPARAM{mood}%\"
 }$percnt"
}%
My current mood:
&nbsp; %GET{ "SetGetPlugin-mood-%WIKINAME%" }%
for %WIKIUSERNAME%

<form action="%SCRIPTURL{view}%/%WEB%/%TOPIC%#MyMood">
Change my mood: <select name="mood">
<option>%URLPARAM{mood}%</option>
<option>:-D</option> <option>:-)</option>
<option>:-I</option> <option>:-(</option>
<option>:mad:</option>
</select>
<input type="submit" value="Set" class="twikiSubmit" />
</form>

  Rendered text:

My current mood:   for TWikiGuest

Change my mood:

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %NEWPLUGIN_SHORTDESCRIPTION%

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Set and get variables in topics, optionally persistently across topic views

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip SetGetPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/SetGetPlugin.txt Plugin topic
      data/TWiki/VarGET.txt GET documentation
      data/TWiki/VarSET.txt SET documentation
      lib/TWiki/Plugins/SetGetPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/SetGetPlugin/Core.pm Core Perl module
    • Set the ownership of the extracted directories and files to the webserver user.

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Test if the installation was successful: The next bullet should show: Result: Yes, it works!
      • Result: Yes, it works!

Plugin Info

Plugin Author: TWiki:Main.PeterThoeny
Copyright: © 2010-2011 TWiki:Main.PeterThoeny
© 2010-2011 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Plugin Version: 2011-07-09
Change History: 
<-- versions below in reverse order -->
 
2011-07-09: TWikibug:Item6725: Change global package variables from "use vars" to "our"
2011-04-04: TWikibug:Item6638: Small doc improvements
2011-03-26: TWikibug:Item6670: Make variables persistent across topic invocations
2010-10-17: TWikibug:Item6597: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Benchmarks: GoodStyle 100%, FormattedSearch 99%, SetGetPlugin 99%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/SetGetPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/SetGetPluginAppraisal

Related Topics: VarSET, VarGET, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences, SpreadSheetPlugin

View topic | History: r6 < r5 < r4 < r3 | More topic actions...
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright &© 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.SetGetPlugin.