Cicerone Android Navigation Library

Cicerone follows a specific flow to ensure lifecycle-safe navigation:

1. Presenter calls a navigation method on the Router (e.g., router.navigateTo(SomeScreen())).
2. Router converts the call into one or more Command objects and sends them to the CommandBuffer.
3. CommandBuffer checks for an active Navigator:
   • If a Navigator is active, it passes the commands to it immediately.
   • If no Navigator is active, it queues the commands and applies them once a new Navigator becomes active.
4. Navigator processes the commands to perform the actual UI transition (e.g., Fragment transactions or Activity starts).

To make Cicerone accessible throughout your app, initialize it in your Application class. You should expose the Router and NavigatorHolder so they can be used by presenters and activities.

class App : Application() {
    private val cicerone = Cicerone.create()
    val router get() = cicerone.router
    val navigatorHolder get() = cicerone.getNavigatorHolder()

    override fun onCreate() {
        super.onCreate()
        INSTANCE = this
    }

    companion object {
        internal lateinit var INSTANCE: App
            private set
    }
}

Add the Cicerone dependency to your build.gradle file to use it in your Android application.

dependencies {
    //Cicerone
    implementation("com.github.terrakok:cicerone:X.X.X")
}

A Navigator is typically implemented as an anonymous class inside an Activity. You must provide the Navigator to the NavigatorHolder during onResume and remove it during onPause to ensure lifecycle safety.

Note: If using FragmentActivity, use onResumeFragments() instead of onResume().

private val navigator = AppNavigator(this, R.id.container)

override fun onResumeFragments() {
    super.onResumeFragments()
    navigatorHolder.setNavigator(navigator)
}

override fun onPause() {
    navigatorHolder.removeNavigator()
    super.onPause()
}

Cicerone uses Command objects to describe screen transitions. These commands are processed by a Navigator to execute navigation logic. The primary commands are:

• Forward(screen): Opens a new screen.
• Replace(screen): Replaces the current screen with a new one.
• Back(): Rolls back the last transition in the screen chain.
• BackTo(screen): Rolls back to a specific screen in the chain. If the specified screen is not found, behavior depends on the Navigator implementation, but returning to the root is recommended.

You can extend AppNavigator to customize fragment transactions (e.g., for animations) or to perform actions like hiding the keyboard before navigation.

private val navigator = object : AppNavigator(this, R.id.container) {
    override fun setupFragmentTransaction(
        screen: FragmentScreen,
        fragmentTransaction: FragmentTransaction,
        currentFragment: Fragment?,
        nextFragment: Fragment
    ) {
        //setup your animation
    }

    override fun applyCommands(commands: Array<out Command>) {
        hideKeyboard()
        super.applyCommands(commands)
    }
}

Screens are defined as objects that return a Screen instance. You can use FragmentScreen for fragment-based navigation or ActivityScreen for starting new activities via Intent.

object Screens {
    fun Main() = FragmentScreen { MainFragment() }
    fun AddressSearch() = FragmentScreen { AddressSearchFragment() }
    fun Profile(userId: Long) = FragmentScreen("Profile_$userId") { ProfileFragment(userId) }
    fun Browser(url: String) = ActivityScreen { Intent(Intent.ACTION_VIEW, Uri.parse(url))  }
}

To use Cicerone, instantiate it using the Cicerone.create() method. This creates an instance using the default Router. You can then retrieve the NavigatorHolder via getNavigatorHolder() to manage your navigation commands.

If you have a custom implementation of BaseRouter, use Cicerone.create(customRouter) instead.

The BackTo command rolls back the screen chain to a specific Screen. If the provided screen is null or not found in the chain, the Navigator implementation determines the fallback behavior (returning to the root is the recommended implementation).

data class BackTo(val screen: Screen?) : Command

The Back command triggers a rollback of the last transition in the screen chain.

class Back : Command