Skip to the content Back to Top

The Inmagic DB/Textworks and CS/Textworks script object model includes a Store object which you can use to store strings. It's a simple dictionary object of key/value pairs where the key is a unique identifier for the corresponding value. There are two versions of the Store object: userStore and sessionStore. The first persists key/value pairs to the local machine, while sessionStore only sticks around so long as Textworks is open.

It's a lot like writing cookies. If you need to keep some values around to reuse that would otherwise disappear when the form unloads, you need to use the Store object.

set:

var myString = "foo";

Application.userStore.value("keyName") = myString;

 

get:

var myString = "";

myString = Application.userStore.value("keyName");

Unfortunately it only stores a string, like a cookie. If you like to work with objects, it doesn't seem right to store individual object properties as separate key/value pairs. Especially if you decide to change the object profile down the road, because you will have to rewrite code. It would be great to simply store an object's state and pick it back up again whenever.

Serialize the object

Serialization is the act of saving an object into a binary or text format. Aha! Text format - that's a string. We can save our object to a string, and persist it to the Store object. Then later we can get that string and deserialize back into an object.

What's the best way to store the string so we can easily turn it back into an object? We could roll our own format, but it's best to stick with something already known and tested and out there. So let's use JSON. JSON stands for JavaScript Object Notation and it's a text-based human-readable format for representing data structures, commonly for transmission over an HTTP connection. Basically it's AJAX without the X (Object Notation instead of XML).

JSON Example

In the following example, we define a Person object, instantiate it, set its properties, serialize it, store it, retrieve it, and deserialize back into an object.

function Person()

{

    this.Name;

    this.BirthDate;

}

 

// instantiate a Person

var person = new Person();

person.Name = "Joe Blow";

person.BirthDate = new Date("July 1, 1975 08:30:00");

 

// serialize the Person object

var strPerson = person.toJSONString();

/*

strPerson =

{"name":"Joe Blow","BirthDate":"1975-07-01T08:30:00"}

*/

 

// store the serialized Person

Application.userStore.value("mykey") = strPerson;

 

// retrieve the serialized Person

var s = Application.userStore.value("mykey");

 

// deserialize from string back into object

var o = s.parseJSON();

Pretty simple!

JSON Source Code

The prototype functions toJSONString() and parseJSON() are provided by an open source JSON parser and stringifier at http://www.json.org/json.js which can be compressed to less than 2000 characters and placed in the form script.

toJSONString() serializes strings, dates, arrays, booleans, numbers, nested versions of these... pretty much anything. parseJSON() is a more secure rewrite of javascript eval which limits itself to valid JSON notation only.

A Short Aside About Eval

If you're not already aware of how powerful eval is, consider that you can pass in a string and have it interpreted as code. You can say:

eval("var a = 1");

and thereafter have a variable, a, which equals 1. This is incredibly handy, but also a security concern, so you would never eval anything you didn't have complete trust in. You can directly eval a JSON string and magically get your object back, but parseJSON() is safer.

Let Us Help You!

We're Librarians - We Love to Help People