Home | Gifts

SetGetPlugin

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:

Syntax Rules

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

ALERT! Important notes when using the remember or store option:

GET{"name"} -- get a variable

SETGETDUMP{...} -- dump variables

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:

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 }%.

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.

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

JSON Examples

Example to set, modify and get a JSON object:

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

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

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: 2024-12-09 16:56:43
  • Now: 2024-12-12 16:57:56

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

Example:
http://amazedbygrace.org/bin/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:

Example:
http://amazedbygrace.org/bin/rest/SetGetPlugin/get?name=rest-test;default=rest-test+variable+not+found

Plugin Installation Instructions

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

Show details toggleopen.gif Hide details toggleclose.gif

Plugin Info

Plugin Author: TWiki:Main.PeterThoeny
Copyright: © 2015 Alba Power Quality Solutions
© 2015 Wave Systems Corp.
© 2010-2018 TWiki:Main.PeterThoeny
© 2010-2018 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Sponsor: Wave Systems Corp.
Plugin Version: 2018-07-05

Show Change History toggleopen.gif Hide Change History toggleclose.gif
2018-07-05: TWikibug:Item7841: Copyright update to 2018
2016-01-09: TWikibug:Item7708: Copyright update to 2016
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
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
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

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

Revision r7 - 2018-07-06 - 05:44:14 - TWikiContributor Edit