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.

Initial setup

• Set up a Component
• TODO
• ...

Using a Store in an Activity or Fragment

• 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.

Using 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.

Note: For the dispatcher to work, the activity or fragment using it must be subscribed to at least one OnChanged event.

Receiving OnChanged events

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());
	}
}

Notes:

• 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 that OnChanged.isError() will be true in case of failure, and OnChanged.error will contain error details
• Some OnChanged events have a causeOfChange field, which specifies the action that resulted in this OnChanged event. For example, the FETCH_POSTS and DELETE_POST actions both result in an OnPostChanged action, and we can check the origin using causeOfChange. OnPostUploaded, on the other hand, is only emitted as a result of PUSH_POST, and so doesn't have a causeOfChange.

Working with Models

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 resulting OnXInstantiated 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 CommentModels and TermModels. In such cases, instantiating a model directly is permissible.