Controls
FoundationDataSet
A DataSet is a list of objects. DataSets also contain support for posting commands to the server.
Remarks
DataSet is a DataList which acts as the root of a data hierarchy. Most datasets
contain DataObjects, which in turn may contains nested DataLists and DataObjects.
Properties
| ID_items (inherited from DataList) | |
| ID_src | |
| ID_type |
Events
| ID_listChanged (inherited from SitedList) | Event handler called when the list changes. |
| ID_preload | Event handler fired just before this dataset is loaded for the first time. |
Methods
| add (inherited from SitedList) | Adds an item to the list. Notifies listeners of the change. |
| addEventHandler (inherited from SitedObject) | Adds a delegate to be called when the specified eventId occurs on this object. |
| addOrFlattenItem (inherited from SitedList) | |
| contains (inherited from SitedList) | Tests if this list contains the specified object. |
| equals (inherited from SitedObject) | Tests if two objects are equal. |
| fireEventHandler (inherited from SitedObject) | Invokes any user event handlers registered for a particular event using SitedObject.addEventHandler(). |
| flatten (inherited from SitedList) | Creates a SitedList from the list of arguments, expanding any nested arrays into individual elements, recursively. |
| getBindingStatus (inherited from SitedObject) | Provides debugging information on bindings for this object. |
| getInternalArray (inherited from SitedList) | Gets the JavaScript Array object used internally to store the list's items. |
| getLength (inherited from SitedList) | Gets the number of items in the list. |
| getPathValue (inherited from SitedObject) | Traverses a binding path and returns the value at the end of it. |
| getPostUrl | Gets the URL this DataSet should posts changes to. |
| getPropertyInfo (inherited from SitedObject) | Gets information on a property. |
| getSite (inherited from SitedObject) | Gets this object's site. |
| getValue (inherited from SitedList) | Gets the value of a property on this object. |
| indexOf (inherited from SitedList) | Gets the index of the specified object. |
| insert (inherited from SitedList) | Inserts an item in the list at the specified index. Notifies listeners of the change. |
| onSetValue (inherited from DataList) | Called by SitedObject.setValue() when a property value is set on this object. |
| onSited (inherited from SitedObject) | Called when this object is sited. |
| onUnsited (inherited from SitedObject) | Called when this object is about to lose its site. |
| onValueSited (inherited from SitedObject) | Called when an object is sited within this object. |
| onValueUnsited (inherited from SitedObject) | Called when an object is about to be unsited in this. |
| receiveResponse | Called when the server sends responses to commands sent with sendCommand. |
| remove (inherited from SitedList) | Removes the specified object from the list. Notifies listeners of the change. |
| removeAt (inherited from SitedList) | Removes the item at the specified index. Notifies listeners of the change. |
| removeEventHandler (inherited from SitedObject) | Remove an existing delegate from the list of delegates for the specified event. |
| sendCommand | Sends a command back to the server to do something to this dataset. |
| setInitialValues (inherited from SitedObject) | Sets multiple property values on an object (during initialization only) |
| setItems (inherited from SitedList) | Wholesale replacement of this lists contents with another list's contents. Fires change notifications. |
| setPathValue (inherited from SitedObject) | Traverses a binding path and sets the value at the end of it. |
| setValue (inherited from SitedList) | Sets the value of a property on this object. |
| toArray (inherited from SitedList) | Returns a copy of this list's items as an array. |
| toString (inherited from SitedObject) | Returns a string representation of this object. |
| traverseArefPath | Follow an aref path array and get the object at the end of it. |
DataSet getPostUrl method
Gets the URL this DataSet should posts changes to.
JavaScript
dataSet.getPostUrl()
Remarks
This returns the value of ID_postURL if it is set on this dataset.
Otherwise, if the application the dataset is attached to has an ID_postUrl set, this
returns that URL. If neither the application or the dataset specify an ID_postURL, this
returns the current page's URL.
The URL string to post changes to.
DataSet ID_preload event
Event handler fired just before this dataset is loaded for the first time.
JavaScript
dataSet.addEventHandler(ID_preload, new Delegate(obj, func))
Xml
<j:DataSet preload="alert('preload happened')" ... >Example
In Xml, writing:
<j:DataSet name="people" src="http://xxx.yyy" preload="preloadPeople(sender)"/>
calls the preparePeople function just before the dataset's contents are fetched for the first time.
In JavaScript, you might write:
// create a preload function that sets the dataset's
// url dynamically. (This is only an example, typically,
// you would use the value of a cookie or URL parameter).
//
function preloadPeople(ds) {
ds.setValue(ID_src, "/src/myURl/" + Math.random());
}DataSet ID_src property
JavaScript
var strVal = dataSet.getValue(ID_src)
dataSet.setValue(ID_src, strVal)
Xml
<j:DataSet src="string" ... >
DataSet ID_type property
JavaScript
var strVal = dataSet.getValue(ID_type)
dataSet.setValue(ID_type, strVal)
Xml
<j:DataSet type="string" ... >
DataSet receiveResponse method
Called when the server sends responses to commands sent with
sendCommand.
JavaScript
dataSet.receiveResponse(jsonObj)
DataSet sendCommand method
Sends a command back to the server to do something to this dataset.
JavaScript
dataSet.sendCommand(command)
Remarks
The argument is a single JavaScript object, which is then encoded in JSON format. The object should have an "op" property that specifies which operation is being performed.
The following "op" commands are sent by the framework.
| Message | Description |
| {"op":"load", "path":path} | The load command is invoked with a "path" property that identifyies a single object in this dataset. The server should respond by sending the complete JSON representation for that object back to the client. |
| {"op":"refresh","path":path} | The "refresh" command is invoked with no arguments - the server should respond by resending a refresh version of the dataset down to the client. |
| {"op":"remove", "path":path, "aref":aref, "index":index} | The "delete" command is invoked with a "path" argument identifying a single object in this dataset. The server should respond by deleting that object. |
| {"op":"set", "path":path, "key":propertyId, "val":newVal} | The "set" command is invoked with a "path" argument identifying an object in this dataset, a "key" argument listing the name of a property of the object, and a "val" argument containing the new value. The server should respond by updating that object. |
| {"op":"add", "path":path, "val":item, "index":index} | The "create" command is invoked with a "obj" argument containing a JSON serialized object that represents the initial values a new object, and a "parentPath", the path of the parent object that the newly created object should be inserted into. The server should add the new object to the dataset. During creation, objects are given a temporary aref value - the server should send the |
DataSet traverseArefPath method
Follow an aref path array and get the object at the end of it.
JavaScript
dataSet.traverseArefPath(pathArray)
Remarks
Given an array containing an aref path, this descends down the objects in the dataset and returns the DataObject or DataList at the end of the path, or null if there is no matching object.
The first element in the path Array is the name of the dataset, the second element should be the aref of an object in the dataset, and so on.