You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<ahref="https://github.com/Volicon/React-MVx/blob/develop/docs/05_Collection/Updates_and_Events.md" target="_blank">Edit on GitHub</a>
83
83
</span>
84
84
</div>
85
85
86
86
87
87
<divclass="s-content">
88
-
<h2id="page_Updates%2C+change+events%2C+and+transactions">Updates, change events, and transactions</h2>
89
-
<p>Changes to collections are <em>observable</em> through events. All updates to the collections are executed in the scope of transactions, which are executed in 4 steps:</p>
88
+
<h2id="page_Updates">Updates</h2>
89
+
<p>Collections notify listeners on the details of the update with events. It's executed in 3 steps:</p>
90
90
<ol>
91
-
<li>Open the transaction.</li>
92
91
<li>Apply all changes to collection and nested records.</li>
93
92
<li>Trigger events for individual changes:
94
93
<ul>
95
94
<li>Trigger <code>add</code>, <code>remove</code>, or <code>change</code> event for every individual record change.</li>
96
95
<li>Trigger an <code>update</code> event when there are any records added or removed, and <code>sort</code> event if an order of records was changed.</li>
97
96
</ul>
98
97
</li>
99
-
<li>Close transaction. If any changes were applied to the collection:
98
+
<li>If any changes were applied to the collection:
100
99
<ul>
101
100
<li>trigger <code>changes</code> event;</li>
102
101
<li>notify collection's owner on aggregation subtree changes.</li>
103
102
</ul>
104
103
</li>
105
104
</ol>
106
-
<p>Every collection update method opens an implicit transaction.</p>
107
-
<h4id="page_record.transaction%28+fun+%29">record.transaction( fun )</h4>
108
-
<p>Execute the sequence of updates in <code>fun</code> function in the scope of the transaction, so it will trigger the single <code>change</code> event.</p>
109
-
<h4id="page_collection.updateEach%28+iteratee+%3A+%28+val+%3A+Record%2C+index+%29+%3D%3E+void%2C+context%3F+%29">collection.updateEach( iteratee : ( val : Record, index ) => void, context? )</h4>
110
-
<p>Similar to the <code>collection.each</code>, but wraps an iteration in a transaction.</p>
<p>Add a record (or an array of records) to the collection, firing an "add" event for each record, and an "update" event afterwards. If a record property is defined, you may also pass raw attributes objects, and have them be vivified as instances of the record. Returns the added (or preexisting, if duplicate) records. Pass {at: index} to splice the record into the collection at the specified index. If you're adding records to the collection that are already in the collection, they'll be ignored, unless you pass {merge: true}, in which case their attributes will be merged into the corresponding records, firing any appropriate "change" events.</p>
<p>Remove a record (or an array of records) from the collection, and return them. Each record can be a record instance, an id string or a JS object, any value acceptable as the id argument of collection.get. Fires a "remove" event for each record, and a single "update" event afterwards, unless {silent: true} is passed. The record's index before removal is available to listeners as options.index.</p>
<p>Adding and removing records one at a time is all well and good, but sometimes you have so many records to change that you'd rather just update the collection in bulk. Use reset to replace a collection with a new list of records (or attribute hashes), triggering a single "reset" event on completion, and without triggering any add or remove events on any records. Returns the newly-set records.</p>
131
-
<p>Pass null for records to empty your Collection with options.</p>
132
-
<p>Here's an example using reset to bootstrap a collection during initial page load, in a Rails application:</p>
133
-
<pre><code><script>
134
-
var accounts = new Backbone.Collection;
135
-
accounts.reset(<%= @accounts.to_json %>);
136
-
</script>
137
-
</code></pre>
138
-
<p>Calling collection.reset() without passing any records as arguments will empty the entire collection.</p>
<p>The set method performs a "smart" update of the collection with the passed list of records. If a record in the list isn't yet in the collection it will be added; if the record is already in the collection its attributes will be merged; and if the collection contains any records that aren't present in the list, they'll be removed. All of the appropriate "add", "remove", and "change" events are fired as this happens. Returns the touched records in the collection. If you'd like to customize the behavior, you can disable it with options: {add: false}, {remove: false}, or {merge: false}.</p>
141
124
<pre><codeclass="language-javascript">const vanHalen = new Man.Collection([ eddie, alex, stone, roth ]);
@@ -146,6 +129,21 @@ <h4 id="page_collection.set%28+records%2C+options%3F+%29">collection.set( record
146
129
// Updates any of stone, alex, and eddie's attributes that may have
147
130
// changed over the years.
148
131
</code></pre>
132
+
<h4id="page_record.transaction%28+fun+%29">record.transaction( fun )</h4>
133
+
<p>Execute the sequence of updates in <code>fun</code> function in the scope of the transaction.</p>
134
+
<p>Transaction is the sequence of updates resuling in a single <code>changes</code> event. Every collection update method opens an implicit transaction.</p>
135
+
<h4id="page_collection.updateEach%28+iteratee+%3A+%28+val+%3A+Record%2C+index+%29+%3D%3E+void%2C+context%3F+%29">collection.updateEach( iteratee : ( val : Record, index ) => void, context? )</h4>
136
+
<p>Similar to the <code>collection.each</code>, but wraps an iteration in a transaction.</p>
<p>Adding and removing records one at a time is all well and good, but sometimes you have so many records to change that you'd rather just update the collection in bulk. Use reset to replace a collection with a new list of records (or attribute hashes), triggering a single "reset" event on completion, and without triggering any add or remove events on any records. Returns the newly-set records.</p>
139
+
<p>Pass null for records to empty your Collection with options.</p>
140
+
<p>Here's an example using reset to bootstrap a collection during initial page load, in a Rails application:</p>
141
+
<pre><code><script>
142
+
var accounts = new Backbone.Collection;
143
+
accounts.reset(<%= @accounts.to_json %>);
144
+
</script>
145
+
</code></pre>
146
+
<p>Calling collection.reset() without passing any records as arguments will empty the entire collection.</p>
149
147
<h2id="page_Listening+to+events">Listening to events</h2>
150
148
<p>Collection implements Events API (<code>on</code>, <code>off</code>, <code>once</code>, <code>listenTo</code>, <code>stopListening</code>, <code>listenToOnce</code>, <code>trigger</code>), and dedicated methods for listening to the <code>changes</code> event (<code>onChanges</code>, <code>offChanges</code>, <code>listenToChanges</code>).</p>
Copy file name to clipboardExpand all lines: docsource/05_Collection/Updates_and_Events.md
+31-32Lines changed: 31 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,28 +1,15 @@
1
-
## Updates, change events, and transactions
1
+
## Updates
2
2
3
-
Changes to collections are _observable_ through events. All updates to the collections are executed in the scope of transactions, which are executed in 4 steps:
3
+
Collections notify listeners on the details of the update with events. It's executed in 3 steps:
4
4
5
-
1. Open the transaction.
6
-
2. Apply all changes to collection and nested records.
7
-
3. Trigger events for individual changes:
5
+
1. Apply all changes to collection and nested records.
6
+
2. Trigger events for individual changes:
8
7
- Trigger `add`, `remove`, or `change` event for every individual record change.
9
8
- Trigger an `update` event when there are any records added or removed, and `sort` event if an order of records was changed.
10
-
4. Close transaction. If any changes were applied to the collection:
9
+
3. If any changes were applied to the collection:
11
10
- trigger `changes` event;
12
11
- notify collection's owner on aggregation subtree changes.
13
12
14
-
Every collection update method opens an implicit transaction.
15
-
16
-
#### record.transaction( fun )
17
-
18
-
Execute the sequence of updates in `fun` function in the scope of the transaction, so it will trigger the single `change` event.
19
-
20
-
#### collection.updateEach( iteratee : ( val : Record, index ) => void, context? )
21
-
22
-
Similar to the `collection.each`, but wraps an iteration in a transaction.
23
-
24
-
## Update methods
25
-
26
13
#### collection.add( models, options? )
27
14
28
15
Add a record (or an array of records) to the collection, firing an "add" event for each record, and an "update" event afterwards. If a record property is defined, you may also pass raw attributes objects, and have them be vivified as instances of the record. Returns the added (or preexisting, if duplicate) records. Pass {at: index} to splice the record into the collection at the specified index. If you're adding records to the collection that are already in the collection, they'll be ignored, unless you pass {merge: true}, in which case their attributes will be merged into the corresponding records, firing any appropriate "change" events.
@@ -45,6 +32,32 @@ is a no-op.
45
32
46
33
Remove a record (or an array of records) from the collection, and return them. Each record can be a record instance, an id string or a JS object, any value acceptable as the id argument of collection.get. Fires a "remove" event for each record, and a single "update" event afterwards, unless {silent: true} is passed. The record's index before removal is available to listeners as options.index.
47
34
35
+
#### collection.set( records, options? )
36
+
37
+
The set method performs a "smart" update of the collection with the passed list of records. If a record in the list isn't yet in the collection it will be added; if the record is already in the collection its attributes will be merged; and if the collection contains any records that aren't present in the list, they'll be removed. All of the appropriate "add", "remove", and "change" events are fired as this happens. Returns the touched records in the collection. If you'd like to customize the behavior, you can disable it with options: {add: false}, {remove: false}, or {merge: false}.
// Fires a "remove" event for roth, and an "add" event for "hagar".
45
+
// Updates any of stone, alex, and eddie's attributes that may have
46
+
// changed over the years.
47
+
```
48
+
49
+
#### record.transaction( fun )
50
+
51
+
Execute the sequence of updates in `fun` function in the scope of the transaction.
52
+
53
+
Transaction is the sequence of updates resuling in a single `changes` event. Every collection update method opens an implicit transaction.
54
+
55
+
#### collection.updateEach( iteratee : ( val : Record, index ) => void, context? )
56
+
57
+
Similar to the `collection.each`, but wraps an iteration in a transaction.
58
+
59
+
60
+
48
61
#### collection.reset( records, options? )
49
62
50
63
Adding and removing records one at a time is all well and good, but sometimes you have so many records to change that you'd rather just update the collection in bulk. Use reset to replace a collection with a new list of records (or attribute hashes), triggering a single "reset" event on completion, and without triggering any add or remove events on any records. Returns the newly-set records.
@@ -60,20 +73,6 @@ Here's an example using reset to bootstrap a collection during initial page load
60
73
61
74
Calling collection.reset() without passing any records as arguments will empty the entire collection.
62
75
63
-
#### collection.set( records, options? )
64
-
65
-
The set method performs a "smart" update of the collection with the passed list of records. If a record in the list isn't yet in the collection it will be added; if the record is already in the collection its attributes will be merged; and if the collection contains any records that aren't present in the list, they'll be removed. All of the appropriate "add", "remove", and "change" events are fired as this happens. Returns the touched records in the collection. If you'd like to customize the behavior, you can disable it with options: {add: false}, {remove: false}, or {merge: false}.
// Fires a "remove" event for roth, and an "add" event for "hagar".
73
-
// Updates any of stone, alex, and eddie's attributes that may have
74
-
// changed over the years.
75
-
```
76
-
77
76
## Listening to events
78
77
79
78
Collection implements Events API (`on`, `off`, `once`, `listenTo`, `stopListening`, `listenToOnce`, `trigger`), and dedicated methods for listening to the `changes` event (`onChanges`, `offChanges`, `listenToChanges`).
0 commit comments