Live Objects
In iOS, LiveObjects are represented by the EkoObject
and EkoCollection
classes. EkoObject
represents live updates on one model, while EkoCollection
represents live updates on a collection of models.
EkoObject
Observing live changes to any EkoObject
can be done via a simple observe block:
In this example the block observes the data of the currently authenticated user and prints out the displayName
. The observe block can be called multiple times throughout the lifetime of the application (as long as its associated EkoNotificationToken
is retained in memory):
If the requested object data is stored locally on the device, the block will be called immediately with the local version of the data (this can be verified this through the
EkoObject
propertydataStatus
).In parallel, a network request for the latest version of the data is fired, once the network returns the data, the observe block will be called again with the updated data.
Any future changes to the data (whenever the user changes its
displayName
on another device, for example) can trigger additional callbacks.
Any UI update logic can be performed within the observe blocks, which will always be called in the main thread: this way, you can ensure that your UI displays the most up-to-date version of the state at all times.
In case you'd like to operate exclusively with fresh data, without using the potientially out-of-date local data, you can make sure to do so by reading the
EkoObject
dataStatus
property, which reflects the status of the callback data, and check that its value is set to fresh.You can also use the
EkoObject
loadingStatus
property to determine the current state of network operations being performed by the LiveObject. This is useful for any UI element that needs to communicate the loading state.
The EkoNotificationToken
is a token that is used to control the lifecycle of a LiveObject. The observeWithBlock
callback will be triggered only if the notificationToken
is retained in memory: once it is released, the observe block will no longer be called, and its memory will be automatically released. Hold a strong reference to any EkoNotificationToken
whose block you would like still to be called.
Beside the
observeWithBlock
method, aobserveOnceWithBlock
method is also available, which will trigger its callback only once, regardless of thedataStatus
of the callback and the associated token retainment (the token still needs to be retained to fire once).To stop receiving
observeWithBlock
updates, release the associatedEkoNotificationToken
or callinvalidate
method on the token itself.
EkoCollection
An EkoCollection
instance is given for any queries that return a list of objects. EkoCollection
has the same change observation interface as EkoObject
, but contains a few other helper methods around data access that allows better integration with collection views like UITableView
.
Data Access
Unlike most databases, EkoCollection
does not return all data in an array. Instead, data are fetched one-by-one using the objectAtIndex:
method. This allows the framework to store most of the actual result on disk, and load them in memory only when absoutely necessary. Additionally, the objectAtIndex:
API fits perfectly into UITableView
's tableView:cellForRowAtIndexPath:
. Together with the count
property, a typical tableView
integration looks like this:
Pagination
EkoCollection
offers both a nextPage
and previousPage
methods which will trigger a local cache lookup, a network call, and multiple LiveObject updates once new data is returned. After the method call is successful, the number of records returned by EkoCollection
will be increased by the additional number of new records. For the typical use case of infinite scroll, you can call nextPage
directly in the scroll view delegate method:
Lastly, if there is a need to shrink the list of models exposed back to original first page, when passing the EkoCollection
object to a new view for example, you can do so by calling resetPage
into the collection itself.
Last updated