Class: DomStorage

Constructor for a DomStorage object that can be saved to a Fireworks document's dom.pngText storage area. Any properties added to the object will be saved when you call its save() method. To recover the stored data, instantiate a new object with the same name that was originally used to save the preference:

require(["fwlib/DomStorage"], function(DomStorage) {
    var settings = new DomStorage("MySettings", { foo: 42 });
    alert(settings.foo); // 42
    settings.foo = "bar";
    settings.baz = "hello, world";
    settings.save();
    var newSettings = new DomStorage("MySettings", { foo: 42 });
    alert(newSettings.foo); // "bar"
    alert(newSettings.baz); // "hello, world"
});

The data is saved with the document itself, rather than in an external file, which ensures that it's always available if the user distributes the file to someone else.

The advantage to using the DomStorage class over accessing the dom.pngText property directly is that the latter supports only string values. So if you do:

dom.pngText.foo = [1, 2, 3];

and then save the file, the next time you reopen it, the array value will have been turned into the source string version of that value: "[1,2,3]". Even more confusing, dom.pngText.foo will appear to still be an array after you set it. It's only after the document is saved, closed and reopened do you discover it's been converted into a string.

And to make matters worse, each property on dom.pngText is limited to 1023 characters. So if you think you can just stringify some data and store it, think again. It will get cut off if it's too long.

The DomStorage class works around these limitations by converting the data to JSON, chunking up the JSON into strings of 1023 characters, storing each one, and keeping track of how many chunks there are. If the name of your object is "foo", then the number of string chunks it contains is stored in dom.pngText.foo. The first chunk is dom.pngText.foo_0, the second is dom.pngText.foo_1, and so on.

When you later instantiate the DomStorage object again, the constructor grabs all of the related strings that are stored in dom.pngText, joins them, and evals that. The resulting properties are then copied onto the instance.

One limitation of dom.pngText is that once a property has been added to it, there is no way to remove it. So when you call remove() on an instance, the best it can do is go through all of the properties it had previously used and set them to "". The same thing happens when an instance is saved and its JSON is shorter than it was previously.

Note that the data is stored on the dom.pngText of the first page in the document, as each page in a document has its own copy of the property. If the user deletes the first page, the data will be lost. If the user moves the first page to a different location, the saved data won't be found by default, but you can pass true as the third argument to the DomStorage constructor to force it to check all the pages

Also note that the properties save and remove are reserved and cannot be modified on a DomStorage instance.