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:
- Provide the ability to easily navigate between different fragments.
- Provide the ability to open fragments for result.
- 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
Instruction for adding FlowR in your project.
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
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
FlowrScreenimplemented, this will provide Flowr with access to the activity’s
FragmentManagerand 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
Toolbaris going to be used for every fragment, in most cases this will be your activity with the interface
ToolbarHandlerprovides 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
DrawerHandler: this is only needed if the activity contains a side drawer, again in most cases this will be your activity with the
DrawerHandlerinterface implemented. The
DrawerHandlerprovides 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.
Bundlecontaining the arguments the fragment might need. The default value for this is
skipBackStack: specify whether this fragment will be added to the
FragmentManagerback stack or not. The default value for this is
clearBackStack: specify whether the
FragmentManagerbackstack should be cleared before displaying this fragment. The default value used for this is
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
popExitAnim: animation resource ID for the enter, exit, pop enter, and pop exit fragment animation. The default values used for these animations is
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
AbstractFlowrFragmentis 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.
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
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:
Each fragment can specify its own preferred screen orientation by simply overriding the method
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.
These values are only used if the parent activity has a toolbar and Flowr was provided a
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
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.
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
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
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
Additionally you can access a Fragment via the link attached to it:
variables work too:
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.