FlowR — Making Android Fragments Easy

Fragments are a very big and useful part of the Android platform, but as many Android developers know it’s always a nightmare to deal with. So when we had decided to go with a single activity multiple fragments navigation pattern we knew we had to create a good solution to help us deal with fragments more easily, and thus came about Flowr.

Flowr is a small library that simplifies Fragment navigation by providing a wrapper class around the FragmentManager. It’s mainly used to navigate between different fragments easily while providing a wide range of functionality. When building Flowr we had three main points we wanted to achieve with the library:

1. Provide the ability to easily navigate between different fragments.
2. Provide the ability to open fragments for result.
3. Automatically keeping the state of the activity correctly synced depending on the custom values specified by the fragment currently visible such as the screen orientation and navigation bar color.

After the initial release of Flowr, we decided to expand the functionality to also include deep link handling.

Adding FlowR to your Project

To add Flowr in your project you can simply follow the instruction provided on the JitPack website.

FlowR | Wrapper Class Around Android FragmentManager

Getting Started With FlowR

With Flowr each new activity will have its own Flowr instance, the Flowr lifecycle should be bound to the activity, meaning it should be destroyed and created with the activity. For the activity to work with Flowr, the activity has to implement the interface FlowrScreen.

While creating a new Flowr instance these are the required parameters:

• containerId: this is the id for the layout that the Flowr will use to display the fragments inside.
• FlowrScreen: in most cases this will be your activity with the interface FlowrScreen implemented, this will provide Flowr with access to the activity’s FragmentManager and the ability to set values such as the screen orientation and navigation bar color depending on the fragment currently being displayed.
• FragmentsResultPublisher: this is used to publish results from fragments that were opened for results.

And some of the optional values are:

• ToolbarHandler: this is only needed if a single Toolbar is going to be used for every fragment, in most cases this will be your activity with the interface ToolbarHandler implemented. The ToolbarHandler provides extra functionality to the fragments displayed to define the toolbar navigation icon, and to toggle the toolbar visibility.
• tagPrefix: a custom prefix for the tags to be used for fragments that will be added to the backstack, the default tag used is #id-.
• DrawerHandler: this is only needed if the activity contains a side drawer, again in most cases this will be your activity with the DrawerHandler interface implemented. The DrawerHandler provides the ability to enable/disable the drawer and open/close the drawer.

Creating a new Flowr instance for an activity that does not have a toolbar and a drawer:

Creating a new Flowr instance for an activity that does have a toolbar and a drawer:

Displaying a Fragment

When displaying a new fragment there are multiple parameters that can be specified. Displaying a Fragment is done through a builder pattern which allows us to only specify the parameters that we require easily. these parameters are listed and explained below:

• fragmentClass: The class of the fragment to be displayed, this is the only parameter that would always be required when displaying a new fragment.
• data: a Bundle containing the arguments the fragment might need. The default value for this is null.
• skipBackStack: specify whether this fragment will be added to the FragmentManager back stack or not. The default value for this is false.
• clearBackStack: specify whether the FragmentManager backstack should be cleared before displaying this fragment. The default value used for this is false.
• replaceCurrentFragment: specify whether this fragment should replace the fragment currently displayed inside the container or just be added over it. The default value used for this is false.
• enterAnim, exitAnim, popEnterAnim, popExitAnim : animation resource ID for the enter, exit, pop enter, and pop exit fragment animation. The default values used for these animations is FragmentTransaction.TRANSIT_NONE.

finally after we have specified all the parameters we need, we can simply call displayFragment() to display the specified fragment.

Displaying a Fragment for Results

When displaying a fragment for results, we will have access to all the parameters described in the previous section with the only difference being that displayFragmentForResults should be called rather than displayFragment at the end with the following parameters:

• fragmentId: a unique ID that each new instance of AbstractFlowrFragment is assigned at the start and it can simply be accessed by calling getFragmentId() from inside your fragment. This ID is used to deliver the results to the correct fragment instance at the end.
• requestCode: this code will be returned in onFragmentResults() when the fragment is closed, and it can be used to identify the request from which the results were returned.

Flowr.open(RequestFragment.class)
      .displayFragmentForResults(getFragmentId(), REQUEST_CODE);

To handle the results all you need to do is simply just override the onFragmentResults() method in your fragment:

Finally when closing a fragment that was opened for results you will need to call the Flowr method closeWithResults():

Flowr.closeWithResults(getResultsResponse(resultCode, resultData));

State Sync and Fragment Dependent Customization

Flowr provides the ability to set custom attributes for values such as the screen orientation and navigation bar color for each fragment. These values are kept in sync automatically with the parent activity when navigating between different fragments through Flowr syncScreenState() method. The syncScreenState() method is only required to be invoked manually when a change to one of these values is made after the fragment has already been displayed.

The following custom values are what is currently supported by the Flowr:

Screen Orientation

Each fragment can specify its own preferred screen orientation by simply overriding the method getScreenOrientation() from AbstractFragment and returning one of the following supported values listed here.

Navigation Bar Color

Fragments can also specify a preferred color to be used for the navigation bar, this can be done by simply overriding getNavigationBarColor() and returning the integer value for the color to be used.

Toolbar Options

These values are only used if the parent activity has a toolbar and Flowr was provided a ToolbarHandler instance.

1. Toolbar Visibility: The boolean value specified here by overriding the isToolbarVisible() method in your fragment, will be used to determine if the toolbar should be visible or not. By default the toolbar is visible.

2. Navigation Icon Type: This value is used to determine the type of the navigation icon to be used by the toolbar. This is done simply by overriding the getNavigationIconType() method in your fragment, and returning one of the following values HIDDEN, HAMBURGER, BACK, or CUSTOM.

3. Navigation Icon Drawable: This value is only used if the navigation icon type returned previously was CUSTOM. The drawable returned here will be used as the toolbar navigation icon, which can be simply done by just overriding the getNavigationIcon() in you fragment.

Drawer Options

Flowr also provides the ability to specify whether the drawer should be enabled or not for the current fragment, this option is also only available if the fragment has a drawer and Flowr was provided with a DrawerHandler instance. To specify this you will have to override the isDrawerEnabled() method in your fragment and return either true or false.

Deep Linking

Deep link handling was also recently added to Flowr. Below are the steps you will need to follow to implement deep link handling.

First, setup the deep link as explained in the documentation. Then annotate your fragment with a @DeepLink annotation and provide it with path value to map the fragment to. That value will be the relative path...

… or two.

You can also insert variable:

Deep Linking Setup

To generate your deep link handler you will need to annotate at least one class with the @DeepLinkHandler annotation. The name of the class annotated with the @DeepLinkHandler annotation would then be used as the name of the generated handler class with "Impl" appended at the end.

However it is also possible to specify a custom name for the generated class by passing the desired class name as a string argument to the @DeepLinkHandler annotation.

If you have fragments across multiple modules, you will need to add the @DeepLinkHandler annotation to at least one class in each module.

Then you will need to provide the list of generated deep link handlers to your flowr instance.

Finally to trigger the deep linking handling, simply call open(Intent, Fragment)) from your Activity#onCreate(Bundle) method.

Additionally you can access a Fragment via the link attached to it:

variables work too:

Upcoming features

With the upcoming new version of the Android support library (26.0.0), one feature we are really looking forward to incorporating into Flowr is the ability to easily synthesize a new back stack history. This feature will be possible due to the addition of the new setReorderingAllowed(boolean) Fragment Transaction API, as it will remove redundant operations, by eliminating operations that cancel.

Finally we are always looking forward to getting feedback from the community and are happy to incorporate new features requested by the community, so if you have any feature in mind you would like to see added in Flowr please feel free to create a new GitHub issue with the details of the required feature.