• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • Work with all your cloud files (Drive, Dropbox, and Slack and Gmail attachments) and documents (Google Docs, Sheets, and Notion) in one place. Try Dokkio (from the makers of PBworks) for free. Now available on the web, Mac, Windows, and as a Chrome extension!


DataStore NestedStores

Page history last edited by Maurits Lamers 11 years, 4 months ago

TODO: Flesh out docs here.  Any takers to help?  The contents here are rough notes...


About Nested Stores


NestedStores provide a way for you to buffer a bunch of changes and commit them to the rest of the application all at once.  You will often use this for example when you open a modal dialog and when to let the user make a bunch of edits then cancel/submit in bulk.


To create a nested store use store.chain():


nested = MyApp.store.chain();


Once you have a nested store, you can work with it just like a normal store.  You will need to find() records all over again.  Each record belongs to a particular store.


rec = nested.find(MyApp.Contact, 1);


Once you have found a record in the nested store, you can make changes to it.  You can follow relationships (toOne/tomany) and they will also be pulled from the nested store.  All changes you make to be buffered in the nested store.


NOTE: If you have a reference to a record from another store and you want to get the same record in a nested store, just call find() passing the record itself:


record = MyApp.store.find(MyApp.Contact, 1);

nested = MyApp.store.chain();


nestedRecord = nested.find(record); 



>>> 1


Note also that nested stores can be nested indefinitely.  You can do:  MyApp.store.chain().chain().chain().  This allows you to stage changes up in any order that you like.


Committing Changes


Once you've made changes to a nested store, you commit those changes by calling nested.commitChanges().  This will copy any data hashes you've modified from the nested store to the parent.  The same goes for state changes.  (so if you destroy() a record in a nested store then commit changes, the record will be destroyed() in the parent store.)


To maintain consistency, the store keeps track of what you've modified in the parent store since you cloned it.  If you modify the same record in both a nested store and in a parent store, an exception will be thrown when you try to commit Changes().


Discarding Changes


If you've made changes to a nested store and decide you don't need them, call nested.discardChanges().  This will reset the nested store to the parent store's current state.  Updating any records, etc. along the way.


Lock On Read


By default, if you get a record out of a nested store, the store will "lock" the version of that record at the time that you read it.  i.e. once you read a record, you can be sure that it's state won't suddenly change from underneath you because a parent store changed until you commitChanges() or discardChanges() to sync up again. 


This is normally the behavior that you want.  However, sometimes you may want a nested store to keep tracking changes from the parent store UNLESS you modify a record.  To get this behavior set lockOnRead property on nested store to NO.

This behaviour allows you to have the entire application work from the nested store and only send the changes to the parent store (and to the back end) when you want it to.


Moving On 


Start learning about DataSources »

or back to DataStore Programming Guide Home »

Comments (1)

Robert Allard said

at 12:27 pm on Jul 29, 2010

Adding records.

As of July 2010 this page does not mention adding records but only updating existing records in the nested store.

I have found that records can be added with the same create method that is used by the regular store when adding a new record. i.e.
record = nested.createRecord(MyApp.Contact, {
firstName: “John”, lastName: “Doe” }, id="");
An id property must be provided otherwise an error is generated.
The value can be empty and provided later.

Using the "commitChanges()" method
on a new record will cause a "sync error".
To commit the changes for a new record you must use the "force" parameter which causes the synchronization test to be bypassed.

This has worked for me because I only modify or add one record at a time in my nested store.
If I was to do both updating and adding at the same time in my nested store then I would have to use the "force" parameter and I would loose the synchronization verification on the updated record.
I believe the synchronization verification verifies that the record in the application store has not been modified while it was being modified in the nested store. If it was modified then a synchronization error is raised.

You don't have permission to comment on this page.