TODO: Flesh out docs here. Any takers to help? The contents here are rough notes...
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);
nestedRecord.get('id')
>>> 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.
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().
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.
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.
Start learning about DataSources »
or back to DataStore Programming Guide Home »