DOCS

EXC | DEV | Documentation | Version 1.0

Value Observers

Part of EXC JS Client
Dependencies: CORE, MODEL.

Observable Collection

Is an object used to store a collection of key-value pairs that are observable.

The function exc.ds.observable(aPlainObj) creates an observable object. Used to store a set of related items in a larger structure of key-value pairs that is observable.

var data = {
	name: "Jose",
	lname: "Cuevas",
	code: 50
};

var observable = exc.ds.observable(data);

Observing for key changes

To observe a key we use observable.observeKey(keyName, fnCallback).

var myObserver = function(value, key, obj){
	console.log("The Key [%s] changed to ", key, value);
};

observable.observeKey("name", myObserver);

//lets test our observer
observable.name = "Joe";

Since the observable is an event emitter using the emitter trait we can take advantage of its features.

When calling observeKey() a subscription is returned. Use the subscription.dispose() to stop observing a key change.


var subscription = observable.observeKey("name", myObserver);
subscription.dispose();

An observable also emits the event "change" to indicate that some key in the object changed.

var observable = exc.ds.observable({
	name: "Jose",
	lname: "Cuevas",
	code: 50
});

observable.on("change", function(obj, key){
	console.log("observable changed");
	console.log("Key %s=%o", key, obj[key]);
});

We can use a subscription to chain multiple functions when a key changes.


observable.observeKey("name", function(value, key, obj){
	return value.toUpperCase();
}).then(function(value){
	console.log("Value is now %s", value);
});

Adding a new key

To add an observable key we use value(key, value).

Properties and Methods

Other useful methods and properties and functions of an observable:

Member Description
keys Readonly Property Returns an array with the keys in the collection.
hasKey(key) Returns true if the key in key is part of the collection.
value(key) Returns the value of a key in the collection. If not present undefined is returned.
value(key, value) Sets the value of a key in the collection. If the key doesn't exists it will be created.
clone() Returns a copy of the observable collection.
asPrimitive() Returns a plain object with a property for each corresponding key in the collection.
serialize() Returns a json string representing the keys in the collection.

DataSource

A datasource represents data from a source that can be remote (ex: API), or a local object.

The datasource holds one or multiple records, where each record represented as row in array-like manner.

The dataSource object obtains its data from one of the supported sources.

To create a datasource we use exc.ds.create(options).

var ds = exc.ds.create({
	type: "rest",
	method: "post",
	url:"http://localhost/app1/data.js",
});

The create(options) method expects a plain object in the parameter options. The options object has particular values used by the selected source.

Key Description Values
type Required String indicating the source type. "rest"
processData Optional function that will be called to process data received. This function must return an array or object. function(data)

To indicate the source of a datasource we use the property type in our options object. In the previous example we use the source type "rest".

As the name implies the source rest is a basic source of data used to fetch data using a REST request. This source uses for its data the JSON returned by the request ( either as one plain object or an array of plain objects) (for more details see JSON API in this document).

A source of type "rest" uses the url option and the method option. The method may be set to get, post or another valid HTTP method.

The URL of our rest service my use parameters. For example:

var ds = exc.ds.create({
		type: "rest",
		method: "post",
		url:"http://localhost/exc_core/app1/testAPI.php?id={id}",
});

In this second example we have the URL parameter id. A URL parameter lets you compose a dynamic URL.

Use the params() function to set parameters in a dynamic URL or additional parameters. For example:

ds.params('id', 205);

you may set multiple parameters at once:

ds.params('id', recordID, 'location', locationID); //multiple keys

The dataSource.load() function is used to load the datasource, which in our example will be a rest request as configured in our create().

ds.load().then(function(ds){
	console.log("ds is ready...");
	console.log(ds);
});

A dataSource.load() returns an instance of core.promise which is EXC's stand in replacement for a native promise (See promises).

ds.params('id', 205).load().then(function(ds){
	while(ds.next()){
		var record = ds.item();
	}
});

Members and Properties

Key Description
length Returns the number of rows in the dataset.
push() Adds one or more elements to the end of an array and returns the new length of the dataset.
forEach(fnCallback(row)) Calls a function for each row in the dataset.
slice(begin, end) Extracts a section of the dataset and returns a new array.
item() Returns the value of the current item when iterating over the datasource.
row(index) Returns the record at a particular index on the datasource.
row(index, value) Replaces the record at a particular index on the datasource.
rewind() Resets the iteration state when using next() or previous().
next() Moves the datasource to point to the next available record. It returns true if it was able to move else it will return false. Use the current property to access the record.
previous() Moves the datasource to point to the previous available item. It returns true if it was able to move else it will return false. Use the current property to access the record.
hasKey(keyName) Checks if the current item has a property with the name provided in keyName.
where(opName, opValue [, ...])

where(plainObject)
Use to set load() parameters.

Using a DataSource with JSON API

API support in EXC is based on a very simplistic format that is self contained.

EXC expects a JSON response to follow a basic set of rules. These rules are inspired by specifications like JSend, JSON API and HAL. We also looked at other standards/specifications (Swagger/JSON-SCHEMA, Open-API , OASIS ODATA ) and found some interesting concepts, yet we found them a bit too complicated for the spirit of EXC.

An API response is a plain JSON object with some special keys.

Key Description Values
status Required A string property indicating the state of this request.

A successful call will have the value "success".
success
fail
data A plain object or an array of plain objects.

This field is required for a successful request.
{...}
[...]
paginate Optional Boolean indicating that results are paged. true
false
pageSize Optional Integer indicating the number of items in a set, when paginate is true. true
false

EXC supports plain JSON and JSON based API.

Error Responses

On error an API sets the status property to fail and optionally may send an error object.

The error object contains the following keys.

Key Description
code An application-specific error code as a string value.
detail A string with a human-readable explanation or message.

On error the data property should be omitted or if included it must have a value of null.

Fork me on GitHub