Creating a data store

Creating a data store

Data stores act as a powerful NoSQL document storage system, with the ability to create cached views based on sorting one or more fields.

Getting started

Creating a data store is easy! You either call $.data() on an existing Object, or create one as a parameter, such as below:

var app  = $.data({id: "app"}, null, {key: "name"});

Data stores are evented, so the Object that receives the data store will fire events as the state of the store changes (e.g. records are added or deleted).

In this case, app will fire events. If you know the ID of the store's Parent ("app"), you can register listeners against that String without requiring the data store to be accessible:

"app".on("afterDataSet", function (rec) {
	… // rec is the new or updated record
});

Populating the data store

Populating the data store can be done as a single statement, or with iteration. In most cases, using the data.batch method yields simpler code.

An Array of Objects is expected when working with local data. If the Objects in the Array do not have a property matching the value of data.key, the index position will be used.

When setting a large amount of records (e.g. over 100), it's recommended to disable store events, to reduce latency. This effectively halts a wired GUI. You can re-enable the observer events by using a deferred Object (i.e. a promise) as the 5th parameter to data.batch.

Batching

// Toggling data store events
app.data.events = false;
app.data.batch("set", recordsArray)
        .then(function () { app.data.events = true; });

Iteration

array.each(function (i) {
	app.data.set(i.primaryKey, i);
});

Getting a record, or records

Getting a record can be achieved by passing the key, or Array index of the record.

var record = app.data.get("abc-123");

Getting a record set requires passing a second parameter, the number of records to retrieve from the index for the first parameter. This is how you can paginate a record set.

var records = app.data.get(0, 5);

Updating a record

Updating a record will erase cached views. This happens because when a record mutates, the cached views become stale.

app.data.set("abc-123", {"someProperty": value});

Deleting a record

Deleting a record will remove the record(s) from the data store, erase cached views & reindex the data store.

app.data.del("abc-123");

Clearing a data store

Clearing a data store will erase data.records, data.views and reset data.total. This effectively erases the contents of the store.

// Hard reset
app.data.clear();

// Soft reset, leaves configuration alone
app.data.clear(true);

Tearing down a data store

Advanced GUIs could have Elements wired to records, or values of a data store (e.g. data.total). If a data store is deleted without data.teardown executed, the global observer will hold a reference to the data store & the corresponding element, creating a memory leak. Even worse, the events for the data store will continue to occur!

It's very important to use data.teardown when you create something complex, where data stores are not long lived.