List Primitive
List primitive represents states that contains a list of object. This can be used for real-time data table, charts, and as you see fit.
Create state
To create the state, you call the method createList(stateName, stateValue) which is available from the object initialised from the Hamoni class. It takes the name of the state and the value to store as parameters to the method.
hamoni.createList("score", [1, 2, 3])
.then(primitive => {
listPrimitive = primitive;
})
.catch(error => console.log(error));
Swift SDK coming soon
Java SDK coming soon
Working with data
If the state is created, you get an object that represents that state. In it you have function to update the state. You can either update an item in a particular index or add new data to the list.
Add Item
To add a new item, you use the push(newItem) method passing it the new data to add to the list
listPrimitive.add({label: March, amount: "$25.52"})
If it succeeds, it'll notify clients that new item has been added to the list.
Note that SDK versions below 0.6.0 used push() and not add().
Swift SDK coming soon
Java SDK coming soon
Update Item
To update an item at a particular index, you call the update(index, updatedItem) method passing it the index and the record to replace with the value at that index
listPrimitive.update(2, {label: June, amount: "$54.52"})
If it succeeds, it'll notify clients that an item was updated
Swift SDK coming soon
Java SDK coming soon
Remove Item
To remove an item at a particular index, you call the remove(index) method passing it the index of the record to remove.
listPrimitive.remove(2)
If it succeeds, it'll notify clients that an item was deleted.
Note that SDK versions below 0.6.0 used delete() and not remove().
Swift SDK coming soon
Java SDK coming soon
Reset state
There are times you want to reset the state to a new set of values. To reset state, you call the set(stateVale) method passing in the new values.
listPrimitive.set([{label: "June", amount: "$10"}, {label: "July", amount: "$20"}])
If it succeeds, it'll notify clients that the state was reset. See the next section on how to receive this notification using the onReset() function.
Swift SDK coming soon
Java SDK coming soon
Receiving state change notification
If the server completes persisting the new state, it notifies connected clients including the one that made the update. To get this update you need to tell Sync which method to call when there's an update.
You get these notifications when an item is added, updated or deleted. When an item is added, it notifies the client and you can subscribe to it by passing a callback to onItemAdded.
listPrimitive.onItemAdded( newItem => console.log(`${newItem.index}: ${newItem.value}`));
When an item is updated, it notifies the client and you can subscribe to it by passing a callback to onItemUpdated.
listPrimitive.onItemUpdated( updatedItem => console.log(`${updatedItem.index}: ${updatedItem.value}`));
When an item is removed, it notifies the client and you can subscribe to it by passing a callback to onItemRemoved.
listPrimitive.onItemRemoved( removedItem => console.log(`${removedItem.index}: ${removedItem.value}`));
Note that SDK versions below 0.6.0 used onItemDeleted() and not onItemRemoved().
When the list is reset (by calling set(newState)), it notifies the client and you can subscribe to it by passing a callback to onReset.
listPrimitive.onReset( state => console.log("new state is: ", state));
Swift SDK coming soon
Java SDK coming soon
Getting state value
You can get the value of the state by calling getAll() or getByIndex() on the state primitive object
To get all the items in a list primitive you use getAll()
let state = listPrimitive.getAll();
To get a a single item, you use getByIndex(index) passing it the index to of the item to retrieve
let state = listPrimitive.getByIndex(2);
Swift SDK coming soon
Java SDK coming soon
Getting existing state primitive
If you already created a state primitive you can get it by calling get(stateName) with the name of the state as parameter. This gets the state from the server and returns an object of that primitive
hamoni
.get("score")
.then(primitive => {
listPrimitive = primitive;
listPrimitive.onItemUpdated( item => console.log(item.value))
})
.catch(error => console.log(error));
Swift SDK coming soon
Java SDK coming soon
Reconnection
If a client reconnects after losing connection, the sdk fetches the state from the server. If it has been updated, it updates the local state and calls the callback passed in onSync() method
hamoni
.get("score")
.then(primitive => {
primitive.onSync( state => console.log(state))
})
.catch(error => console.log(error));
Swift SDK coming soon
Java SDK coming soon