Alligator is a modern Android navigation library that will help to organize your navigation code in clean and testable way.
- Screens based on activities, fragments and dialog fragments.
- Simple yet powerful navigation methods.
- Independence from activity lifecycle (navigation is available even when an application is in background).
- Passing screen arguments without boilerplate code.
- Handling activity result in object oriented style.
- Screen switching with nested navigation.
- Flexible animation configuring.
Add jitpack.io repository in project level build.gradle:
repositories {
...
maven { url 'https://jitpack.io' }
}Add the dependency in module level build.gradle:
dependencies {
compile 'com.github.aartikov:Alligator:1.0.0'
}AndroidNavigator - the main library object. It implements Navigator and NavigationContextBinder interfaces and uses a command queue internally to execute navigation commands.
Navigator - has navigation methods such as goForward, goBack, replace and so on. It does not depend on Android SDK, so code that uses it can be tested easily. Navigator operates with Screens.
Screen - a logical representation of an application screen. It is used to indicate a screen type and pass screen arguments.
NavigationContextBinder - binds and unbinds NavigationContext to AndroidNavigator.
NavigationContext - is used to configure AndroidNavigator. It contains a reference to the current activity and all the other things needed for command execution.
Command - a command executed by AndroidNavigator. The library has a bunch of implemented commands corresponding to navigation methods. You don’t need to create a command manually, AndroidNavigator creates it when a navigation method is called.
NavigationFactory - converts Screens to theirs Android representation (intents, fragments, dialog fragments) and vice versa. There is ready to use implementation of NavigationFactory - RegistryNavigationFactory.
ScreenSwitcher - an object for switching between several screens without theirs recreation. There are ready to use implementations of ScreenSwitcher - FragmentScreenSwitcher.
TransitionAnimation, TransitionAnimationProvider, DialogAnimation, DialogAnimationProvider - are used to configure animations.
// Screen without arguments
public class ScreenA implements Screen {}
// Screen with an argument
public class ScreenD implements Screen, Serializable {
private String mMessage;
public ScreenD(String message) {
mMessage = message;
}
public String getMessage() {
return mMessage;
}
}Register your screens in RegistryNavigationFactory. In this sample the default converting functions will be used that serialize and deserialize screen arguments if a screen is Serializable or Parcelable. See about converting functions in Java docs.
public class SampleNavigationFactory extends RegistryNavigationFactory {
public SampleNavigationFactory() {
registerActivity(ScreenA.class, ActivityA.class);
registerActivity(ScreenB.class, ActivityB.class);
registerFragment(ScreenC.class, FragmentC.class);
registerFragment(ScreenD.class, FragmentD.class);
}
}It should be a single instance in your application.
sAndroidNavigator = new AndroidNavigator(new SampleNavigationFactory());Use NavigationContext.Builder to create NavigationContext. In the simplest case just pass a current activity to it. You can also set a fragment container, a fragment manager (which by default is taken from an activity), a screen switcher, animation providers and listeners.
Activities are responsible to bind and unbind NavigationContext. Bind it in onResumeFragments (when state of an activity and its fragments is restored) and unbind in onPause (when an activity becomes inactive).
@Override
protected void onResumeFragments() {
super.onResumeFragments();
NavigationContext navigationContext = new NavigationContext.Builder(this)
.containerId(R.id.fragment_container)
.build();
mNavigationContextBinder.bind(navigationContext);
}
@Override
protected void onPause() {
mNavigationContextBinder.unbind();
super.onPause();
}mNavigator.goForward(new ScreenD("Message for D"));
// or
mNavigator.goBack();Navigator provides these navigation methods:
goForward(screen)- Adds a new screen and goes to it.goBack()- Removes the current screen and goes back to the previous screen.goBackTo(screenClass)- Goes back to a screen with the given class.replace(screen)- Replaces the last screen with a new screen.reset(screen)- Removse all other screens and adds a new screen.finish()- Finishes the last screen or the group of screens executing some common task (implemented as finishing of the current activity).finishWithResult(screenResult)- Finishes with ScreenResult.switchTo(screen)- Switches a screen using a ScreenSwitcher.
Navigation methods can be called at any moment, even when a NavigationContext is not bound. When a navigation method is called an appropriate Command is generated and placed to a command queue. AndroidNavigator can execute commands only when a NavigationContext is bound to it, in other case a command will be postponed. You can combine navigation methods arbitrarily (for example call two goBack() one by one). This works for activities too because AndroidNavigator unbinds a NavigationContext by itself after activity finishing or starting.
See how navigation methods work in simple navigation sample an navigation methods sample.
To get screen arguments from an activity or a fragment use ScreenResolver.
ScreenD screen = mScreenResolver.getScreen(this); // 'this' is Activity or Fragment
String message = screen.getMessage();Create TransitionAnimationProvider and set it to NavigationContext.
public class SampleTransitionAnimationProvider implements TransitionAnimationProvider {
@Override
public TransitionAnimation getAnimation(TransitionType transitionType, Class<? extends Screen> screenClassFrom,
Class<? extends Screen> screenClassTo, boolean isActivity, @Nullable AnimationData animationData) {
switch (transitionType) {
case FORWARD:
return new SimpleTransitionAnimation(R.anim.slide_in_right, R.anim.slide_out_left);
case BACK:
return new SimpleTransitionAnimation(R.anim.slide_in_left, R.anim.slide_out_right);
default:
return TransitionAnimation.DEFAULT;
}
}
} NavigationContext navigationContext = new NavigationContext.Builder(this)
.transitionAnimationProvider(new SampleTransitionAnimationProvider())
.build();Lollipop transition animations are also supported, see shared element animation sample.
A navigation method switchTo is similar to replace. The difference is that during screen switching screens can be reused. For example if there are three tabs in your application and each tab screen is represented by a fragment, there are no reason to create more than three fragments. Screen switching is especially useful if you want to create a nested navigation where each tab has its own backstack.
To make screen switching posible a special object ScreenSwitcher should be created and set to NavigationContext. The library provides a ScreenSwitcher implementation called FragmentScreenSwitcher. Screens passed to FragmentScreenSwitcher are used as keys to identify fragments so they must have equals and hashCode methods correctly overridden.
See how screen switching works in simple screen switcher sample an advanced screen switcher sample.
To use a dialog fragment as a screen register it with registerDialogFragment method and start it with goForward method.
These types of listeners can be set to NavigationContext
TransitionListener- is called when usual screen transition (not screen switching and not dialog showing) has been executed.DialogShowingListener- is called when a fragment dialog has been shown.ScreenSwitchingListener- is called when a screen has been switched with a screen switcher.NavigationErrorListeneris called when a navigation error has occurred.
To use an external activity (for example a phone dialer) register a screen with a custom intent creation function.
registerActivity(PhoneDialerScreen.class, null, (context, screen) ->
new Intent(Intent.ACTION_DIAL, Uri.parse("tel:" + screen.getPhoneNumber())));Start it with goForward method. Use NavigationErrorListener to check that an activity has been succesfully resolved.
Starting an activity for result is necessary to get a result from external activities such as image gallery or contact picker. You can also use it to pass data between your own activities. With Alligator there are no needs to declare request codes and handle activity result manually.
Declare and register screen result classes. Use ScreenResultResolver to handle activity result.
See how to do it in screen result sample.
Artur Artikov [email protected]
The MIT License (MIT)
Copyright (c) 2017 Artur Artikov
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent