-
Notifications
You must be signed in to change notification settings - Fork 37
Using FluxC
There are a few working examples of using FluxC as a library. See the FluxC Example app and Instaflux.
The following examples use snippets from the FluxC Example app.
- Set up a Component
- TODO
- ...
-
Add the activity to the Component
-
Inject the fragment into the current Component instance when the activity is created onCreate:
@Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); ((ExampleApp) getApplication()).component().inject(this); ...
* Inject any needed FluxC stores:
```java
public class PostsFragment extends Fragment {
@Inject PostStore mPostStore;
...
The injected PostStore
can now be used to fetch data from the store.
mPostStore.getPostsForSite(mSite);
Only read actions are available in this way - anything that involves making a network request or altering the local storage requires use of Actions and the Dispatcher.
The same prerequisites as above apply for the Dispatcher - the activity using it must be registered with the Component, and the activity should be injected.
Next, inject the Dispatcher into the activity:
public class PostsFragment extends Fragment {
@Inject PostStore mPostStore;
@Inject Dispatcher mDispatcher;
...
An additional requirement for using the Dispatcher
is that the actvity needs to register and unregister itself with the dispatcher as part of its life cycle. For example:
@Override
public void onStart() {
super.onStart();
mDispatcher.register(this);
}
@Override
public void onStop() {
super.onStop();
mDispatcher.unregister(this);
}
We can now dispatch actions. For example, let's fetch a list of posts from a user's site. This will involve the PostStore
, and the FETCH_POSTS
action (all actions supported by each store can be found here).
To dispatch an action, we must first create an Action
object. All available actions for a store will be accessible as methods of that store's ActionBuilder
. For example, to make a FETCH_POSTS
request, we build a FETCH_POSTS
action:
PostActionBuilder.newFetchPostAction();
Each method requires a specific Payload
type (some may require no Payload at all). In this case, we need to pass newFetchPostAction()
a FetchPostsPayload
.
FetchPostsPayload payload = new FetchPostsPayload(mSite);
mDispatcher.dispatch(PostActionBuilder.newFetchPostsAction(payload));
Dispatched actions will eventually result (asynchronously) in an OnChanged
event, which the dispatching activity or fragment should listen for if it needs to act on the results of the action.
Any dispatched action will eventually result in a OnChanged
event. This event will be emitted asynchronously, and the calling activity needs to listen for the event in order to be notified of the result of the action.
For example, a FETCH_POSTS
action will result in a OnPostChanged
event once the network call has completed and the database updated:
@SuppressWarnings("unused")
@Subscribe(threadMode = ThreadMode.MAIN)
public void onPostChanged(OnPostChanged event) {
if (event.isError()) {
prependToLog("Error from " + event.causeOfChange + " - error: " + event.error.type);
return;
}
if (event.causeOfChange.equals(PostAction.FETCH_POSTS)) {
prependToLog("Fetched " + event.rowsAffected + " posts from: " + firstSite.getName());
}
}
- All actions generate an
OnChanged
event, whether they succeeded or not - The same
OnChanged
event is emitted in case of success or failure; the difference is thatOnChanged.isError()
will betrue
in case of failure, andOnChanged.error
will contain error details - Some
OnChanged
events have acauseOfChange
field, which specifies the action that resulted in thisOnChanged
event. For example, theFETCH_POSTS
andDELETE_POST
actions both result in anOnPostChanged
action, and we can check the origin usingcauseOfChange
.OnPostUploaded
, on the other hand, is only emitted as a result ofPUSH_POST
, and so doesn't have acauseOfChange
.
In general, instantiating Models directly using should be avoided. This is because the model won't exist in the local DB and so lack a local ID, and this may cause unexpected behaviour.
Depending on the situation, obtaining a Model object may require:
- Querying the store
- Cloning an existing Model
- Dispatching an
INSTANTIATE_X
action and receiving a Model from the resultingOnXInstantiated
event
For example, dispatching an INSTANTIATE_POST
action will prompt the PostStore
to create a new PostModel
, store it in the local db and emit it in an OnPostInstantiated
event. The PostModel
can now be used as a draft post.
An exception to this is for temporary models that aren't intended to be used outside the UI, and for models currently lacking draft support, where the db shouldn't contain any Models that don't correspond to a server-side object. Currently, this includes CommentModel
s and TermModel
s. In such cases, instantiating a model directly is permissible.