Data Persistence

UNDER CONSTRUCTION --Wayn3w 05:59, 17 March 2008 (PDT)

Sometimes widgets take information from users that should be stored for later. For instance, if a user changes the color of a screen by pressing on it, then when the widget next loads it should still use this color.

Persisting to Chumby Servers

 * persists across Chumby reboots
 * may take longer because of network fetches
 * a tad more complex because of the need to create and parse XML

Widgets can can save and restore data by exchanging XML with a web service developed for this purpose. When a widget first loads, the parameter _root._chumby_widget_instance_href stores the URL of the service the widget should use to exchange XML-encoded parameters (the configuration widget should use _root._chumby_instance_url). The flow usually proceeds this way:
 * widget configuration:
 * XML.load(_root._chumby_instance_url)
 * get the parameters from the user
 * XML.send(_root._chumby_instance_url or XML.sendAndLoad(_root._chumby_instance_url)
 * Widget parameter format (in XML)
 * widget construction:
 * The _root timeline has the values saved from the configuration widget (no need to fetch the parameters explicitly using XML).

If the widget needs to save data to the server:
 * widget invokes XML.sendAndLoad(_root._chumby_widget_instance_href) to send data to the widget service to save. send could be used but sendAndLoad has a better feedback mechanism.

Classes for helping with the XML

 * com.chumby.util.WidgetParams ( part of the Widget_Parameter_Example )
 * WidgetParameterObject

Persisting Locally: Mobile Shared Objects
This involves using objects of the SharedObject class. An excellent tutorial for the using them is Persistent data: Saving user preferences and game scores (2010: broken link). Things to note about them are:
 * they are stored in /tmp/pdata, but it is not easily readable
 * they will be removed when a Chumby restarts.
 * flashplayer does not support shared objects, so this will have to be tested on the Chumby.

MTASC Issues
MTASC has an older, incomplete definition for SharedObject. The file SharedObject.as (on Linux stored in /usr/share/mtasc/std/SharedObject.as) will have to be edited to include the following code:

static function addListener(objectName:String, notifyFunction:Function): Void; static function removeListener(objectName:String): Void;

Also, SharedObject is defined as intrinsic, but not dynamic class, so it is not possible to have private data -- that is, data on the shared object that will not persist. This is not necessarily a detriment, because in an object-oriented project there will be other places to store private data. Note that this makes it difficult to derive a new class from SharedObject.

Debugging
trace is your friend.