FlowR


Source link: https://github.com/Fueled/flowr

FlowR

FlowR is a wrapper class around the Fragment Manager. It's mainly used to navigate between different fragments easily while providing a wide range of functionality. The following are the functionalities provided by the Flowr:

  • Easily navigate between different fragments.
  • Ability to open fragments for result.
  • 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.

Install

Add it in your root build.gradle at the end of repositories:

 allprojects {

repositories {

 ...
 maven {
 url "https://jitpack.io" 
}

}
  
}

Then add the dependency to the application module:

 dependencies {

annotationProcessor 'com.github.fueled.flowr:flowr-compiler:X.X.X'
compile 'com.github.fueled.flowr:flowr:X.X.X'  
}

Getting Started

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 the Flowr we need to make sure that it implements 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 the Flowr with access to the activity 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 where 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 provide 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:

Flowr Flowr = new Flowr(R.id.main_container, flowrScreen, resultPublisher);

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

Flowr Flowr = new Flowr(R.id.main_container, flowrScreen, toolbarHandler, drawerHandler, resultPublisher);

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 easily only specify the parameters that we require. 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 and exitAnim: animation resource ID for the enter and exit fragment animation. The default values used here are R.anim.fragment_enter_anim and R.anim.fragment_exit_anim.

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

Flowr.open(DemoFragment.class)

 .setData(data)

 .skipBackStack(false)

 .clearBackStack(true)

 .replaceCurrentFragment(true)

 .setCustomTransactionAnimation(android.R.anim.fade_in, android.R.anim.fade_out, android.R.anim.slide_in_left, android.R.anim.slide_out_right)

 .displayFragment();

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 AbstractFragment 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:

@Override protected void onFragmentResults(int requestCode, int resultCode, Bundle data) {

  super.onFragmentResults(requestCode, resultCode, data);

if (requestCode == REQUEST_CODE) {

if (resultCode == Activity.RESULT_OK) {

 demoTextView.setText("Result OK");

}
 else {

 demoTextView.setText("Result CANCELED");

}

  
}
 
}

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

The 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 the Flowr syncScreenState() method. The syncScreenState() method is only required to be invoked manually when a change to one of these values has been made after the fragment has been already 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.

public class DemoFragment extends AbstractFragment<DemoPresenter> implements DemoScene {

....

@Override
  public int getScreenOrientation() {

return ActivityInfo.SCREEN_ORIENTATION_PORTRAIT;
  
}
 
}

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.

public class DemoFragment extends AbstractFragment<DemoPresenter> implements DemoScene {

....

@Override
  public int getNavigationBarColor() {

return navigationBarColor;
  
}
 
}

Toolbar Options

These values are only used if the parent activity has a toolbar and the 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 fragment should be visible or not. By default the toolbar is visible.
public class DemoFragment extends AbstractFragment<DemoPresenter> implements DemoScene {

....

@Override
  public boolean isToolbarVisible() {

return false;
  
}
 
}
  1. 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.
public class DemoFragment extends AbstractFragment<DemoPresenter> implements DemoScene {

....

@Override
  public NavigationIconType getNavigationIconType() {

return NavigationIconType.HAMBURGER;
  
}
 
}
  1. 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.
public class DemoFragment extends AbstractFragment<DemoPresenter> implements DemoScene {

....

@Override
  public Drawable getNavigationIcon() {

return navigationIcon;
  
}
 
}

Drawer Options

The 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 the 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.

public class DemoFragment extends AbstractFragment<DemoPresenter> implements DemoScene {

....

@Override
  public boolean isDrawerEnabled() {

return super.isDrawerEnabled();

  
}
 
}

Deep Link

FlowR support deep links. First, setup the deep link as explained in the documentation. Then annote your fragment with a @DeepLink annotation. That value will be the relative path...

@DeepLink("/path1/") public class TestFragment extends Fragment implement FlowrFragment

... or two.

@DeepLink({
"/path1/","path2"
}
) public class TestFragment extends Fragment implement FlowrFragment

You can also insert variable:

@DeepLink("/{
id
}
/details") public class TestFragment extends Fragment implement FlowrFragment . . . String url = getArguments().getString(Flowr.DEEP_LINK_URL,"");
 String id = getArguments().getString("id","");

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.

/** This will generate a MainDeepLinkHandlerImpl class */ @DeepLinkHandler public class MainDeepLinkHandler {
 
}

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.

/** This will generate a MyDeepLinkHandler class */ @DeepLinkHandler("MyDeepLinkHandler") public class MainActivity extends AbstractActivity {
 
}

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

/** This will generate a LibraryDeepLinkHandlerImpl class */ @DeepLinkHandler public class LibraryDeepLinkHandler {
 
}

Provide the list of generated deep link handlers to your flowr instance.

public class MainActivity extends AbstractActivity {

private Flowr flowr;
public void getFlowr() {

if (flowr == null) {

 flowr = new Flowr(...);

 flowr.setDeepLinkHandlers(new MainDeepLinkHandlerImpl(), new LibraryDeepLinkHandlerImpl());

}

 return flowr;  
}
 
}

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

public class MainActivity extends AbstractActivity {

@Override  protected void onCreate(Bundle savedInstanceState) {

...
getFlowr()

 .open(getIntent(), HomeFragment.class)

 .skipBackStack(true)

 .displayFragment();
  
}
 
}

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

getFlowr()
  .open("/path1/")
  .skipBackStack(true)
  .displayFragment();

variables work too:

getFlowr()
  .open("/1234/details")
  .skipBackStack(true)
  .displayFragment();

License

Copyright 2016 Fueled  Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License. You may obtain a copy of the License at
  http://www.apache.org/licenses/LICENSE-2.0  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. 

Resources

Tiny library for tracking screens and events with google analytics.

Kolumbus allows you to explore your Realm database from within your Android application.

CountryPicker is a simple library that can show a country picker.

Android library to get device information in a super easy way.

A library to serialize and deserialize objects with minimum memory usage.

Bubble View for Android with custom stroke width and color, arrow size, position and direction.

Topics


2D Engines   3D Engines   9-Patch   Action Bars   Activities   ADB   Advertisements   Analytics   Animations   ANR   AOP   API   APK   APT   Architecture   Audio   Autocomplete   Background Processing   Backward Compatibility   Badges   Bar Codes   Benchmarking   Bitmaps   Bluetooth   Blur Effects   Bread Crumbs   BRMS   Browser Extensions   Build Systems   Bundles   Buttons   Caching   Camera   Canvas   Cards   Carousels   Changelog   Checkboxes   Cloud Storages   Color Analysis   Color Pickers   Colors   Comet/Push   Compass Sensors   Conferences   Content Providers   Continuous Integration   Crash Reports   Credit Cards   Credits   CSV   Curl/Flip   Data Binding   Data Generators   Data Structures   Database   Database Browsers   Date &   Debugging   Decompilers   Deep Links   Dependency Injections   Design   Design Patterns   Dex   Dialogs   Distributed Computing   Distribution Platforms   Download Managers   Drawables   Emoji   Emulators   EPUB   Equalizers &   Event Buses   Exception Handling   Face Recognition   Feedback &   File System   File/Directory   Fingerprint   Floating Action   Fonts   Forms   Fragments   FRP   FSM   Functional Programming   Gamepads   Games   Geocaching   Gestures   GIF   Glow Pad   Gradle Plugins   Graphics   Grid Views   Highlighting   HTML   HTTP Mocking   Icons   IDE   IDE Plugins   Image Croppers   Image Loaders   Image Pickers   Image Processing   Image Views   Instrumentation   Intents   Job Schedulers   JSON   Keyboard   Kotlin   Layouts   Library Demos   List View   List Views   Localization   Location   Lock Patterns   Logcat   Logging   Mails   Maps   Markdown   Mathematics   Maven Plugins   MBaaS   Media   Menus   Messaging   MIME   Mobile Web   Native Image   Navigation   NDK   Networking   NFC   NoSQL   Number Pickers   OAuth   Object Mocking   OCR Engines   OpenGL   ORM   Other Pickers   Parallax List   Parcelables   Particle Systems   Password Inputs   PDF   Permissions   Physics Engines   Platforms   Plugin Frameworks   Preferences   Progress Indicators   ProGuard   Properties   Protocol Buffer   Pull To   Purchases   Push/Pull   QR Codes   Quick Return   Radio Buttons   Range Bars   Ratings   Recycler Views   Resources   REST   Ripple Effects   RSS   Screenshots   Scripting   Scroll Views   SDK   Search Inputs   Security   Sensors   Services   Showcase Views   Signatures   Sliding Panels   Snackbars   SOAP   Social Networks   Spannable   Spinners   Splash Screens   SSH   Static Analysis   Status Bars   Styling   SVG   System   Tags   Task Managers   TDD &   Template Engines   Testing   Testing Tools   Text Formatting   Text Views   Text Watchers   Text-to   Toasts   Toolkits For   Tools   Tooltips   Trainings   TV   Twitter   Updaters   USB   User Stories   Utils   Validation   Video   View Adapters   View Pagers   Views   Watch Face   Wearable Data   Wearables   Weather   Web Tools   Web Views   WebRTC   WebSockets   Wheel Widgets   Wi-Fi   Widgets   Windows   Wizards   XML   XMPP   YAML   ZIP Codes