-
Notifications
You must be signed in to change notification settings - Fork 9
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.
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 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
.
// Toggling data store events
app.data.events = false;
app.data.batch("set", recordsArray).then(function () { app.data.events = true; });
array.each(function (i) {
app.data.set(i.primaryKey, i);
});
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 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 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 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);
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.