Skip to content
This repository was archived by the owner on Feb 15, 2025. It is now read-only.

Commit c3ebfe7

Browse files
bennobuilderbennobuilder
committed
optimized some docs
1 parent 32cb503 commit c3ebfe7

File tree

2 files changed

+371
-15
lines changed

2 files changed

+371
-15
lines changed

‎docs/packages/core/features/collection/Methods.md

Lines changed: 358 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -423,7 +423,7 @@ If a Group can't be found it returns `undefined`.
423423

424424
:::info
425425

426-
The `getGroup()` method is perfect to access a Group in our program logic.
426+
The `getGroup()` method is perfect to access a Group in our business logic.
427427
But it's not that good to get a Group which should be subscribed to a UI-Component for instance with the `useAgiele()` hook.
428428
The reason is, that it returns `undefined` whenever the Group doesn't exist.
429429
In this case we should use [`getGroupWithReference()`](#getgroupwithreference) instead,
@@ -639,7 +639,7 @@ If a Selector can't be found it returns `undefined`.
639639

640640
:::info
641641

642-
The `getSelector()` method is perfect to access a Selector in our program logic.
642+
The `getSelector()` method is perfect to access a Selector in our business logic.
643643
But it's not that good to get a Selector which should be subscribed to a UI-Component for instance with the `useAgiele()` hook.
644644
The reason is, that it returns `undefined` whenever the Selector doesn't exist.
645645
In this case we should use [`getSelectorWithReference()`](#getselectorwithreference) instead,
@@ -722,3 +722,359 @@ MY_COLLECTION.removeSelector('mySelector');
722722
### 📄 Return
723723

724724
Returns the [Collection](./Introduction.md) it was called on.
725+
726+
727+
728+
<br />
729+
730+
---
731+
732+
<br />
733+
734+
735+
736+
## `hasItem()`
737+
738+
With `hasItem()` we can check if a specific Item exists in the Collection.
739+
```ts {1,3}
740+
MY_COLLECTION.hasItem(3); // Returns false
741+
MY_COLLECTION.collect({id: 1, name: 'frank'});
742+
MY_COLLECTION.hasItem(1); // Returns true
743+
```
744+
745+
### 📭 Props
746+
747+
| Prop | Type | Default | Description | Required |
748+
|----------------|---------------------------------------------------------------------------|------------|-------------------------------------------------------|----------|
749+
| `itemKey` | number \| string | undefined | Key/Name of Item | Yes |
750+
| `config` | [HasConfig](../../../../Interfaces.md#hasconfig) | {} | Configuration | No |
751+
752+
### 📄 Return
753+
754+
`true` if the Item exists and `false` if the Item doesn't exist.
755+
756+
757+
758+
<br />
759+
760+
---
761+
762+
<br />
763+
764+
765+
766+
## `getItem()`
767+
768+
`getItem()` returns the Item at a specific `itemKey`.
769+
```ts
770+
const MY_ITEM = MY_COLLECTION.getItem('myItem');
771+
```
772+
If an Item can't be found it returns `undefined`.
773+
774+
:::info
775+
776+
The `getItem()` method is perfect to access an Item in our business logic.
777+
But it's not that good to get an Item which should be subscribed to a UI-Component for instance with the `useAgiele()` hook.
778+
The reason is, that it returns `undefined` whenever the Item doesn't exist.
779+
In this case we should use [`getItemWithReference()`](#getitemwithreference) instead,
780+
because it returns a reference to the not existing Item.
781+
Such reference allows AgileTs to rerender the UI-Component, whenever the missing Item gets created.
782+
783+
:::
784+
785+
### 📭 Props
786+
787+
| Prop | Type | Default | Description | Required |
788+
|----------------|---------------------------------------------------------------------------|------------|-------------------------------------------------------|----------|
789+
| `itemKey` | number \| string | undefined | Key/Name of Item | Yes |
790+
| `config` | [HasConfig](../../../../Interfaces.md#hasconfig) | {} | Configuration | No |
791+
792+
### 📄 Return
793+
794+
An Item fitting to the passed `itemKey` or `undefined`.
795+
796+
797+
798+
<br />
799+
800+
---
801+
802+
<br />
803+
804+
805+
806+
## `getItemWithReference()`
807+
808+
`getItemWithReference()` returns like [`getItem()`](#getitem) the Item at a specific `itemKey`.
809+
```ts
810+
const MY_ITEM = MY_COLLECTION.getItemWithReference('myItem');
811+
```
812+
But it differs in one key area, since it doesn't return `undefined` whenever it couldn't find an Item.
813+
If this case occurs it returns a `placeholder` Item to hold a reference to the not existing Item.
814+
Such reference is for instance useful, to reliably subscribe a not existing Item to a UI-Component with the `useAgile()` hook.
815+
```ts
816+
// Doesn't cause rerender, whenever Item gets created and returns undefined
817+
const myItem = useAgile(MY_COLLECTION.getItem('myItem'));
818+
819+
// Does cause rerender, whenever Item gets created and returns an empty array
820+
const myItemWithReference = useAgile(MY_COLLECTION.getItemWithReferenece('myItem'));
821+
```
822+
823+
### 📭 Props
824+
825+
| Prop | Type | Default | Description | Required |
826+
|----------------|---------------------------------------------------------------------------|------------|-------------------------------------------------------|----------|
827+
| `itemKey` | number \| string | undefined | Key/Name of Item | Yes |
828+
829+
### 📄 Return
830+
831+
An Item fitting to the passed `itemKey` or a `placeholder` Item.
832+
833+
834+
835+
<br />
836+
837+
---
838+
839+
<br />
840+
841+
842+
843+
## `getAllItems()`
844+
845+
`getAllItems()` returns all [Items](./Introduction.md#-item) of the Collection
846+
```ts {1}
847+
MY_COLLECTION.getAllItems(); // Returns something like (see below)
848+
/*
849+
[
850+
Item(1),
851+
Item(10),
852+
Item(23)
853+
]
854+
*/
855+
```
856+
857+
### 📭 Props
858+
859+
| Prop | Type | Default | Description | Required |
860+
|----------------|---------------------------------------------------------------------------|------------|-------------------------------------------------------|----------|
861+
| `config` | [HasConfig](../../../../Interfaces.md#hasconfig) | {} | Configuration | No |
862+
863+
### 📄 Return
864+
865+
All Items of the Collection.
866+
867+
868+
869+
<br />
870+
871+
---
872+
873+
<br />
874+
875+
876+
877+
## `getAllItemValues()`
878+
879+
With `getAllItemValues()` we can get all Item `values` of the Collection
880+
```ts {1}
881+
MY_COLLECTION.getAllItemValues(); // Returns something like (see below)
882+
/*
883+
[
884+
{id: 1, name: "frank"},
885+
{id: 10, name: "hans"},
886+
{id: 23, name: "jeff"},
887+
]
888+
*/
889+
```
890+
891+
### 📭 Props
892+
893+
| Prop | Type | Default | Description | Required |
894+
|----------------|---------------------------------------------------------------------------|------------|-------------------------------------------------------|----------|
895+
| `config` | [HasConfig](../../../../Interfaces.md#hasconfig) | {} | Configuration | No |
896+
897+
### 📄 Return
898+
899+
All Item `values` of the Collection.
900+
901+
902+
903+
<br />
904+
905+
---
906+
907+
<br />
908+
909+
910+
911+
## `persist()`
912+
913+
With `persist()` we preserve the State Value in the appropriate local storage for the current environment.
914+
No matter if Mobile or Web environment as long as we have configured our [Storage](../storage/Introduction.md) correctly.
915+
```ts
916+
MY_COLLECTION.perist("myPersistKey");
917+
```
918+
919+
### 💻 Web
920+
I guess the most people persisting something on the web, will use the [Local Storage](https://www.w3schools.com/html/html5_webstorage.asp).
921+
Luckily AgileTs has already set up it by default, as long as you haven't disabled it.
922+
```ts {2}
923+
const App = new Agile({
924+
localStorage: true
925+
})
926+
```
927+
So there is noting to setup here.
928+
929+
### 📱 Mobile
930+
In the mobile environment the Local Storage unfortunately doesn't exist,
931+
so we might use the [Async Storage](https://reactnative.dev/docs/asyncstorage).
932+
The Async Storage isn't configured by default, so we have to do it on our own.
933+
```ts {3-9}
934+
App.registerStorage(
935+
new Storage({
936+
key: "AsyncStorage",
937+
async: true,
938+
methods: {
939+
get: AsyncStorage.getItem,
940+
set: AsyncStorage.setItem,
941+
remove: AsyncStorage.removeItem,
942+
},
943+
}), {default: true}
944+
);
945+
```
946+
947+
### 🔑 Local Storage Key
948+
To persist our Collection,
949+
we have two options to provide the `persist` function the **required** Storage Key.
950+
951+
- **1.** Assign a unique Key to our Collection,
952+
because if no key was given to the `persist` function,
953+
it tries to use the Collection Key as Storage Key.
954+
```ts {2}
955+
MY_COLLECTION.key = "myCoolKey";
956+
MY_STATE.persist(); // Success
957+
```
958+
- **2.** Pass the Storage Key directly into the `persist` function.
959+
```ts {1}
960+
MY_COLLECTION.persist("myCoolKey"); // Success
961+
```
962+
963+
If AgileTs couldn't find any key, it drops an error and doesn't persist the Collection Value.
964+
```ts {2}
965+
MY_STATE.key = undefined;
966+
MY_STATE.persist(); // Error
967+
```
968+
969+
### 📝 Multiple Storages
970+
If our Application for whatever reason has more than one registered Storages that get actively used.
971+
We can define with help of the `storageKeys` in which Storage the `persist` function stores the Collection Value.
972+
```ts {2}
973+
MY_STATE.persist({
974+
storageKeys: ["myCustomStorage"]
975+
})
976+
```
977+
By default, it gets stored in the `default` Storage.
978+
979+
### 📭 Props
980+
981+
| Prop | Type | Default | Description | Required |
982+
|----------------------|----------------------------------------------------------------------------|------------|---------------------------------------------------------------------------------|----------|
983+
| `key` | string \| number | undefined | Key/Name of created Persistent (Note: Key required if State has no set Key!) | No |
984+
| `config` | [StatePersistentConfig](../../../../Interfaces.md#statepersistentconfig) | {} | Configuration | No |
985+
986+
### 📄 Return
987+
Returns the [Collection](./Introduction.md) it was called on.
988+
989+
990+
991+
<br />
992+
993+
---
994+
995+
<br />
996+
997+
998+
999+
## `onLoad()`
1000+
1001+
`onLoad()` allows us to register a callback which gets called whenever our [persisted](#persist) Collection Value got loaded into the Collection.
1002+
```ts
1003+
MY_COLLECTION.onLoad((success) => {
1004+
console.log(`Value '${MY_STATE.value}' got loaded into the Collection! Success? ${success}`)
1005+
});
1006+
```
1007+
For instance this might be useful, to show a loading indicator until
1008+
the persisted Value got loaded.
1009+
1010+
### 📭 Props
1011+
1012+
| Prop | Type | Default | Description | Required |
1013+
|----------------------|----------------------------------------------------------|------------|-----------------------------------------------------------------------------------------------|----------|
1014+
| `callback` | (success: boolean) => void | undefined | Callback Function that gets called once, when the Storage Value got loaded into the Collection| Yes |
1015+
1016+
### 📄 Return
1017+
Returns the [Collection](./Introduction.md) it was called on.
1018+
1019+
1020+
1021+
<br />
1022+
1023+
---
1024+
1025+
<br />
1026+
1027+
1028+
1029+
## `getGroupCount()`
1030+
1031+
`getGroupCount()` returns how many Groups the Collection has.
1032+
```ts
1033+
MY_COLLECTION.getGroupCount(); // Returns 1
1034+
```
1035+
It should always return a greater number that `1`,
1036+
since each Collection has a `default` Group.
1037+
1038+
### 📄 Return
1039+
`number`
1040+
1041+
1042+
1043+
<br />
1044+
1045+
---
1046+
1047+
<br />
1048+
1049+
1050+
1051+
## `getSelectorCount()`
1052+
1053+
`getSelectorCount()` returns how many Selectors the Collection has.
1054+
```ts
1055+
MY_COLLECTION.getGroupCount(); // Returns 0
1056+
```
1057+
1058+
### 📄 Return
1059+
`number`
1060+
1061+
1062+
1063+
<br />
1064+
1065+
---
1066+
1067+
<br />
1068+
1069+
1070+
1071+
## `reset()`
1072+
1073+
With the `reset()` method we can reset the Collection.
1074+
A reset includes:
1075+
- removing all Items
1076+
- resetting each [Group](./group/Introduction.md)
1077+
- resetting each [Selector](./selector/Introduction.md)
1078+
1079+
### 📄 Return
1080+
Returns the [Collection](./Introduction.md) it was called on.

0 commit comments

Comments
 (0)