@@ -12,8 +12,8 @@ WIP docs!
1212:::
1313
1414A Collection holds a set of Information that we need to remember at a later point in time.
15- It is designed for arrays of data objects following the same structure .
16- Be aware that each collected Data needs an ** unique primaryKey** to properly identify it later.
15+ It is designed for arrays of data objects following the same pattern .
16+ Be aware that each collected Data needs an ** unique primaryKey** to get properly identified later.
1717We instantiate a Collection with help of an [ Agile Instance] ( ../agile-instance/Introduction.md ) here called ` App ` .
1818By doing this the Collection gets automatically bound to the Agile Instance it was created from.
1919``` ts
@@ -25,11 +25,11 @@ but there we have to pass the `Agile Instance`, to which the Collection should g
2525const = new Collection (App );
2626```
2727Both instantiations lead to the same result, but we recommend using the former way.
28- After we have successfully created our Collection, we can dynamically manipulate and work with it.
28+ After we have successfully created our Collection, we can work with it dynamically and easily .
2929``` ts
3030MY_COLLECTION .collect ({id: 1 , name: " jeff" // Add Item to Collection
31- MY_COLLECTION .remove (1 ).everywhere (); // Remove Item from everywhere
32- MY_COLLECTION .persist (); // Persists Collection Value into the Storage
31+ MY_COLLECTION .remove (1 ).everywhere (); // Remove Item from Collection
32+ MY_COLLECTION .persist (); // Persists Collection Value into a Storage
3333```
3434Most methods we use to modify, mutate and access the Collection are chainable.
3535``` ts
@@ -38,36 +38,42 @@ MY_COLLECTION.collect({id: 1, name: "jeff"}).persist().removeGroup('myGroup').re
3838
3939## 🔹 Item
4040
41- Each Data we have added to the Collection, like with the ` collect ` method,
42- gets applied to an Item and stored as such in our Collection.
41+ Each Data Object we add to our Collection, for example with the ` collect ` method,
42+ gets transformed to an Item. This Item than gets stored in our Collection.
43+ We can simply access each Item with the ` getItem ` method and the correct primary Key.
4344``` ts
4445MY_COLLECTION .getItem (/* primary Key */ // Returns Item at the primary Key
4546```
46- An Item is an extension of the State Class and offers the same powerful features.
47+ The cool thing about Items is, they are an extension of the ` State Class ` .
48+ This means that they have the same powerful tools like a State.
4749``` ts
48- const = MY_COLLECTION .getItem (1 );
50+ MY_COLLECTION .collect ({id: 1 , name: " jeff" // Collect Data
51+ const = MY_COLLECTION .getItem (1 ); // Returns Item at primaryKey '1'
52+ myItem .value ; // Returns '{id: 1, name: "jeff"}'
4953myItem .patch ({name: " frank" // Update property 'name' in Item
54+ myItem .undo (); // Undo latest change
5055```
5156
5257## 👨👧👦 [ Group] ( ./group/Introduction.md )
5358
5459Often applications need to categorize and preserve ordering of structured data and
55- in AgileTs Groups are the cleanest way to reach this goal. They allow us to
60+ in AgileTs Groups are the right way to reach this goal. They allow us to
5661cluster together data from a Collection as an array of primary Keys.
57- We might use a Group, if we want to have an array of 'Today Todos' from
58- a Todo Collection or Posts that belong to the logged-in User from the Post Collection.
5962``` ts
6063MY_COLLECTION .createGroup (" groupName" /* initial Items*/
6164```
62- We are able to create as many Groups as we want, and the Collection won't lose
63- its redundant behaviour, since the Items are still stored in the Collection, and
64- the Groups are only like an interface to it.
65+ We might use a Group, if we want to have an array of 'Today Todos' from
66+ a Todo Collection or Posts that belong to the logged-in User from the Post Collection.
67+
68+ In our Collection we are able to create as many Groups as we want, and the Collection won't lose
69+ its redundant behaviour. This is due to the fact, that each Item gets stored in the Collection itself and not in the Group.
70+ You can imagine a Group like an interface to the Collection Data.
6571``` ts
6672MY_COLLECTION .createGroup (" group1" 1 , 2 , 3 ]);
6773MY_COLLECTION .createGroup (" group2" 2 , 5 , 8 ]);
6874MY_COLLECTION .createGroup (" group5000" 1 , 10 , 500 , 5 ]);
6975```
70- A Group is an extension of the State Class and offers the same powerful features.
76+ Also, a Group is an extension of the ` State Class ` and offers the same powerful features.
7177``` ts
7278MY_STATE .undo (); // Undo latest change
7379MY_GROUP .reset (); // Reset Group to its intial Value
@@ -77,23 +83,31 @@ But be aware that the `value` might not be the output you expect.
7783``` ts
7884MY_GROUP .value ; // Returns '[8, 5, 30, 1]'
7985```
80- It holds the primary Keys of the Items the Group represent .
81- To get the right value to the primary Keys just use ` output ` property.
86+ Because this property doesn't hold the Item Values, it contains the primary Keys the Group represents .
87+ To get the Item Value to each primary Keys, just use the ` output ` property.
8288``` ts
8389MY_GROUP .output ; // Returns '[{ id: 8, name: 'jeff' }, ...]'
8490```
8591
8692## 🔮 [ Selector] ( ./selector/Introduction.md )
8793
88- Selectors allow us to _ select_ an Item from a Collection.
94+ Selectors allow us to _ select_ a specific Item from our Collection.
95+ ``` ts
96+ MY_COLLECTION .createSelector (" selectorName" /* to select Item Key*/
97+ ```
8998We might use the Selector, if we want to select a 'current User' from our User Collection or
9099the 'current viewing Post' from our Post Collection.
100+
101+ A Selector is also able to select a not existing Item, then it holds
102+ a reference to this Item. But be aware that the Value of the Selector is
103+ ` undefined ` during this period of time, since we do not know your desired Item.
91104``` ts
92- MY_COLLECTION .createGroup (" selectorName" /* to select Item Key*/
105+ MY_SELECTOR .select (" notExistingItem"
106+ MY_SELECTOR .value ; // Returns 'undefined' until it the Item got added to the Collection
93107```
94- A Selector is an extension of the State Class and offers the same powerful features.
108+ Beside the Group, a Selector is also an extension of the State Class and offers the same powerful features.
95109``` ts
96- MY_STATE .undo (); // Undo latest change
110+ MY_SELECTOR .undo (); // Undo latest change
97111```
98112But be aware that by mutating the Selector we won't modify the
99113selected Item in the Collection. To do that we have to modify the Item directly.
0 commit comments