{"id":17335845,"url":"https://github.com/aartikov/alligator","last_synced_at":"2025-05-16T13:07:21.149Z","repository":{"id":43754220,"uuid":"82198753","full_name":"aartikov/Alligator","owner":"aartikov","description":"Alligator is Android navigation library that will help to organize your navigation code in clean and testable way.","archived":false,"fork":false,"pushed_at":"2025-04-04T16:28:35.000Z","size":1157,"stargazers_count":299,"open_issues_count":3,"forks_count":16,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-12T10:57:41.265Z","etag":null,"topics":["android","android-library","clean-architecture","fragments","mvp","navigation"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aartikov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-02-16T16:03:13.000Z","updated_at":"2025-04-04T16:27:22.000Z","dependencies_parsed_at":"2023-12-18T09:26:02.797Z","dependency_job_id":"9bf56298-8709-4e89-8fe8-ca9943a25a83","html_url":"https://github.com/aartikov/Alligator","commit_stats":{"total_commits":218,"total_committers":7,"mean_commits":"31.142857142857142","dds":0.3669724770642202,"last_synced_commit":"1081210a0bd69cdd7ddd021e47cbe4b3586adde8"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aartikov%2FAlligator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aartikov%2FAlligator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aartikov%2FAlligator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aartikov%2FAlligator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aartikov","download_url":"https://codeload.github.com/aartikov/Alligator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535829,"owners_count":22087399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-library","clean-architecture","fragments","mvp","navigation"],"created_at":"2024-10-15T15:12:30.812Z","updated_at":"2025-05-16T13:07:21.129Z","avatar_url":"https://github.com/aartikov.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alligator\n[![Release](https://jitpack.io/v/aartikov/Alligator.svg)](https://jitpack.io/#aartikov/Alligator) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nAlligator is Android navigation library that will help to organize your navigation code in clean and\ntestable way. The library has a own new [Telegram's Community Group](https://t.me/+atfYhDAA4-84NmIy)\nOne of the best approaches and\nimplementation - [NavigationController](https://github.com/jamal-wia/NavigationController)\n\n## Features\n- Any approach you want: activity per screen, activity per flow, single activity.\n- Simple yet powerful navigation methods.\n- Lifecycle-safe (navigation is available even when an application is in background).\n- Passing screen arguments without boilerplate code.\n- Handling screen result in object oriented style.\n- Bottom navigation with separate back stack history.\n- Flexible animation configuring.\n\n## Gradle Setup\nAdd jitpack.io repository in project level build.gradle:\n\n```gradle\nrepositories {\n    ...\n    maven { url 'https://jitpack.io' }\n}\n```\n\nAdd the dependencies in module level build.gradle:\n\n```gradle\ndependencies {\n    implementation 'com.github.aartikov.Alligator:alligator:4.7.0'\n    annotationProcessor 'com.github.aartikov.Alligator:alligator-compiler:4.7.0'\n}\n```\nStarting from version 3.0.0 Alligator requires AndroidX.\n\n## Components to know\n[AndroidNavigator](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/AndroidNavigator.html) - the main library object. It implements `Navigator` and `NavigationContextBinder` interfaces and uses a command queue internally to execute navigation commands.\n\n[Navigator](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/Navigator.html) - 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 `Screen`s.\n\n[Screen](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/Screen.html) - a logical representation of an application screen. It is used to indicate a screen type and pass screen arguments.\n\n[NavigationContextBinder](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/NavigationContextBinder.html) - binds and unbinds `NavigationContext` to `AndroidNavigator`.\n\n[NavigationContext](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/NavigationContext.html) -  is used to configure `AndroidNavigator`. It contains a reference to the current activity and all the other things needed for command execution.\n\n[Command](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/commands/Command.html) - 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.\n\n[NavigationFactory](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/navigationfactories/NavigationFactory.html) - associates `Screen`s with theirs Android implementation. Alligator generates a navigation factory for you with annotation processor, but you can extend it if needed.\n\n[ScreenSwitcher](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/screenswitchers/ScreenSwitcher.html) - an object for switching between several screens without theirs recreation. There are ready to use implementations of `ScreenSwitcher` - [FragmentScreenSwitcher](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/screenswitchers/FragmentScreenSwitcher.html).\n\n[TransitionAnimation](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/animations/TransitionAnimation.html), [TransitionAnimationProvider](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/animations/providers/TransitionAnimationProvider.html) - are used to configure animations.\n\n## Quick start\n### 1. Declare screens\nScreens with arguments should be `Serializable` or `Parcelable`.\n\n```java\n// Screen without arguments\npublic class ScreenA implements Screen {}\n\n// Screen with an argument\npublic class ScreenD implements Screen, Serializable {\n  private String mMessage;\n\n  public ScreenD(String message) {\n     mMessage = message;\n  }\n\n  public String getMessage() {\n     return mMessage;\n  }\n}\n```\n\n### 2. Register screens\nMark your activities and fragments with `@RegisterScreen` annotation. Alligator looks for this annotations to create `GeneratedNavigationFactory`.\n\n```java\n@RegisterScreen(ScreenA.class)\npublic class ActivityA extends AppCompatActivity \n```\n```java\n@RegisterScreen(ScreenD.class)\npublic class FragmentD extends Fragment\n```\n\n### 3. Create AndroidNavigator\nIt should be a single instance in your application.\n```java\nandroidNavigator = new AndroidNavigator(new GeneratedNavigationFactory());\n```\n\n### 4. Set NavigationContext\nUse `NavigationContext.Builder` to create `NavigationContext`. In the simplest case just pass a current activity to it. You can also configure fragment navigation, a [screen switcher](https://github.com/aartikov/Alligator#switch-screens), [animation providers](https://github.com/aartikov/Alligator#configure-animations) and [listeners](https://github.com/aartikov/Alligator#listen-navigation).\n\nActivities 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).\n\n```java\n@Override\nprotected void onResumeFragments() {\n    super.onResumeFragments();\n    NavigationContext navigationContext = new NavigationContext.Builder(this, androidNavigator.getNavigationFactory())\n            .fragmentNavigation(getSupportFragmentManager(), R.id.fragment_container)\n            .build();\n    mNavigationContextBinder.bind(navigationContext);\n}\n\n@Override\nprotected void onPause() {\n    mNavigationContextBinder.unbind(this);\n    super.onPause();\n}\n```\n\n\n### 5. Call navigation methods\n```java\nmNavigator.goForward(new ScreenD(\"Message for D\"));\n// or\nmNavigator.goBack();\n```\n\n`Navigator` provides these navigation methods:\n1. `goForward(screen)` - adds a new screen and goes to it.\n2. `goBack()` - removes the current screen and goes back to the previous screen.\n3. `goBackWithResult(screenResult)` - goes back with [ScreenResult](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/ScreenResult.html).\n4. `goBackTo(screenClass)` - goes back to a given screen.\n5. `goBackToWithResult(screenClass, screenResult)` - goes back to a given screen with [ScreenResult](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/ScreenResult.html).\n6. `replace(screen)` - replaces the last screen with a new screen.\n7. `reset(screen)` - removes all other screens and adds a new screen.\n8. `finish()` - finishes a current [flow](https://github.com/aartikov/Alligator#flows) or a current top-level screen.\n9. `finishWithResult(screenResult)` - finishes with [ScreenResult](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/ScreenResult.html).\n10. `finishTopLevel()` - finishes a current top-level screen (that is represented by activity).\n11. `finishTopLevelWithResult(screenResult)` -  finishes a current top-level screen with [ScreenResult](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/ScreenResult.html).\n12. `switchTo(screen)` - switches a screen using a [ScreenSwitcher](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/screenswitchers/ScreenSwitcher.html).\n\nNavigation methods can be called at any moment, even when a `NavigationContext` is not bound. When a navigation method is called an appropriate `Command` is created 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.\n\nSee how navigation methods work in [simple navigation sample](https://github.com/aartikov/Alligator/tree/master/simplenavigationsample) an [navigation methods sample](https://github.com/aartikov/Alligator/tree/master/navigationmethodssample).\n\n### 6. Get screen arguments\nTo get screen arguments from an activity or a fragment use [ScreenResolver](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/ScreenResolver.html).\n```java\nmScreenResolver = SampleApplication.sAndroidNavigator.getScreenResolver();\nScreenD screen = mScreenResolver.getScreen(this); // 'this' is Activity or Fragment\nString message = screen.getMessage();\n```\n\n## Advanced topics\n### Configure animations\nCreate `TransitionAnimationProvider` and set it to `NavigationContext`.\n```java\npublic class SampleTransitionAnimationProvider implements TransitionAnimationProvider {\n    @Override\n    public TransitionAnimation getAnimation(TransitionType transitionType,\n                                            DestinationType destinationType,\n                                            Class\u003c? extends Screen\u003e screenClassFrom,\n                                            Class\u003c? extends Screen\u003e screenClassTo,\n                                            @Nullable AnimationData animationData) {\n        switch (transitionType) {\n            case FORWARD:\n                return new SimpleTransitionAnimation(R.anim.slide_in_right, R.anim.slide_out_left);\n            case BACK:\n                return new SimpleTransitionAnimation(R.anim.slide_in_left, R.anim.slide_out_right);\n            default:\n                return TransitionAnimation.DEFAULT;\n        }\n    }\n}\n```\n```java\n    NavigationContext navigationContext = new NavigationContext.Builder(this, navigationFactory)\n            .transitionAnimationProvider(new SampleTransitionAnimationProvider())\n            .build();\n```\n\nLollipop transition animations are also supported, see [shared element animation sample](https://github.com/aartikov/Alligator/tree/master/sharedelementanimationsample).\n\n### Switch screens\nA 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.\n\nTo 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.\n\n See how screen switching works in [simple screen switcher sample](https://github.com/aartikov/Alligator/tree/master/simplescreenswitchersample) an [advanced screen switcher sample](https://github.com/aartikov/Alligator/tree/master/advancedscreenswitchersample).\n\n### Flows\nFlow is a group of screen executing some common task. There are two ways to create flows. The first one is to use activities for flows and fragments for nested screens. There is nothing special here. The second way is to use [FlowScreen](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/FlowScreen.html)s. It allows to create fragment-based flows with nested child fragments. Screens marked with `FlowScreen` interface are considered to be flows. You can configure this type of navigation using `flowFragmentNavigation` and `fragmentNavigation` methods of `NavigationContext.Builder`.\n\nFor more details see [flow sample](https://github.com/aartikov/Alligator/tree/master/flowsample).\n\n### Open dialogs\nTo open a dialog register screen implemented by a dialog fragment and start it with `goForward` method.\n\n### Listen navigation\nThese types of listeners can be set to `NavigationContext`\n- [TransitionListener](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/listeners/TransitionListener.html) - is called when usual screen transition (not screen switching and not dialog showing) has been executed.\n- [DialogShowingListener](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/listeners/DialogShowingListener.html) - is called when a dialog fragment has been shown.\n- [ScreenSwitchingListener](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/listeners/ScreenSwitchingListener.html) - is called when a screen has been switched with a screen switcher.\n- [ScreenResultListener](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/listeners/ScreenResultListener.html) - is called when a screen that can return a result has finished.\n- [NavigationErrorListener](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/listeners/NavigationErrorListener.html) - is called when a navigation error has occurred.\n\n### Start external activity\nTo use an external activity (for example a phone dialer) extend `GeneratedNavigationFactory` and register a screen with a custom intent converter.\n```java\npublic class PhoneDialerConverter extends OneWayIntentConverter\u003cPhoneDialerScreen\u003e {\n    @Override\n    public Intent createIntent(Context context, PhoneDialerScreen screen) {\n        return new Intent(Intent.ACTION_DIAL, Uri.parse(\"tel:\" + screen.getPhoneNumber()));\n    }\n}\n```\n```java\npublic class SampleNavigationFactory extends GeneratedNavigationFactory {\n    public SampleNavigationFactory() {\n        registerActivity(PhoneDialerScreen.class, new PhoneDialerConverter());\n    }\n}\n```\n\nStart it with `goForward` method. Use [NavigationErrorListener](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/listeners/NavigationErrorListener.html) to check that an activity has been succesfully resolved.\n\n### Handle screen result\nA screen can return [ScreenResult](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/ScreenResult.html) to a previous screen. It is like `startActivityForResult`, but with Alligator there are no needs to declare request codes and handle `onActivityResult` manually. Alligator defines unique request codes for screens implemented by activities that can return results. For screens implemented by fragments Alligator uses usual listeners.\n\nDeclare and register screen result classes. Return a result with `goBackWithResult` or `finishWithResult` methods of `Navigator`. Use [ActivityResultHandler](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/ActivityResultHandler.html) and [ScreenResultListener](https://jitpack.io/com/github/aartikov/Alligator/alligator/4.7.0/javadoc/me/aartikov/alligator/listeners/ScreenResultListener.html) to handle screen result.\n\nSee how to do it in [screen result sample](https://github.com/aartikov/Alligator/tree/master/screenresultsample).\n\n## Developed by\nArtur Artikov \u003ca href=\"mailto:a.artikov@gmail.com\"\u003ea.artikov@gmail.com\u003c/a\u003e\u003c/br\u003eMikhail Savin \u003ca href=\"mailto:savinmike.u@gmail.com\"\u003esavinmike.u@gmail.com\u003c/a\u003e\n## License\n```\nThe MIT License (MIT)\n\nCopyright (c) 2017 Artur Artikov\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faartikov%2Falligator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faartikov%2Falligator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faartikov%2Falligator/lists"}