chuross/mori-router

Annotation based Android router library. (with Shared Element support)

MoriRouter

Annotation based Android router library.

This library for single activity application.

And This library provide easy implementation for SharedElement.

Futures

• Auto generate routing codes
• Auto generate Fragment builder codes
• DeepLink support
• Shared element support

Download

Gradle

1. add JitPack repository to your project root build.gradle.

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

2. add the dependency

dependencies {
    implementation 'com.github.chuross.mori-router:annotation:x.x.x'
    annotationProcessor 'com.github.chuross.mori-router:compiler:x.x.x' // or kpt
}

Usage

Basic

1. Add annotations in your screen fragment.

@RouterPath(name = "main")
class MainScreenFragment : Fragment() {

    @Argument
    lateinit var param1: String

    @Argument(name = "ieei")
    lateinit var param2: Int

    @Argument(required = false)
    var param3: ArrayList<String> = arrayListOf()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        MoriBinder.bind(this) // MoriBinder is auto generated class.
    }

    ....
}

2. Execute build command, Then MoriRouter class is auto generated.

val transitionFactory = DefaultTransitionFactory { /* return `android.support.transition` or `android.transition` */ }

val options = MoriRouterOptions.Builder(R.id.container)
                .setEnterTransitionFactory(transitionFactory)
                .setExitTransitionFactory(transitionFactory)
                .build()

val router = MoriRouter(supportFragmentManager, options) // MoriRouter is auto generated class.

router.main("required1", 1000) // main(String param1, Integer ieei)
    .param3(arrayListOf("fuga")) // optional value
    .launch() // launch main screen


// pop screen
router.pop()

Fragment builder support

Also can use @WithArguments annotation. This library generate {class_name}Builder code.

@WithArguments
class HogeFragment : Fragment() {

    @Argument
    lateinit var hogeName: String

    ....
}

val fragment: Fragment = HogeFragmentBuilder(hogeName).build() // HogeScreenFragmentBuilder is auto generated class

override enter / exit transition

@RouterPath(
    name = "main",
    overrideEnterTransitionFactory = MainScreenTransitionFactory::class,
    overrideExitTransitionFactory = MainScreenTransitionFactory::class
)

DeepLink support

1. If use deepLink support, uri parameter add to @RouterPath, and add @UriArgument parameters in your screen fragment.

@RouterPath(
  name = "second",
  uris = [
    "example://hoge/{hoge_id}/{fuga}",
    "https://example.com/hoge/{hoge_id}/{fuga}" //also can use multiple uri
  ]
)
class SecondScreenFragment : Fragment() {

    @UriArgument(name = "hoge_id")
    var hogeId: Int

    @UriArgument
    var fuga: String

    // If use `@UriArgument`, Don't use `required = true`.
    @Argument(required = false)
    var piyo: String? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        MoriBinder.bind(this)
    }
}

2. MoriRouter has dispatch method. Then call dispatch with Uri.

router.dispatch(Uri.parse("example://hoge/123/test")) // launch SecondScreenFragment (hogeId = 123, fuga=test)
router.dispatch(Uri.parse("https://example.com/hoge/123/test")) // launch SecondScreenFragment (hogeId = 123, fuga=test)

SharedElement support

Basic

1. set transition name in your XML layout or in your code.

XML

<YourLayout
    ....
    android:id="@+id/your_id" <!-- must have view id -->
    android:transitionName="your_transition_name" />

Code

// yourView must has view id
// ex) yourView.setId(R.id.your_id)
ViewCompat.setTransitionName(yourView, "your_transition_name");

2. add sharedEnterTransitionFactory and sharedExitTransitionFactory to @RouterPath.

@RouterPath(
    name = "third",
    sharedEnterTransitionFactory = ThirdScreenSharedTransitionFactory::class,
    sharedExitTransitionFactory = ThirdScreenSharedTransitionFactory::class
)
class ThirdScreenFragment : Fragment() {
   ....

   override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        // ThirdScreenFragment must has `R.id.your_id` view
        // this id is same before screen's shared element id
        MoriBinder.bindElement(this, R.id.your_id)
   }
}

3. add SharedElements when before transition third screen.

// yourView has `R.id.your_id`
router.third().addSharedElement(yourView).launch()

Dynamic Shared Element transition

if you need dynammic sharedElement transition, you should use this option.

1. set transition name in your code.

ViewCompat.setTransitionName(yourView, "your_transition_name");

2. add manualSharedViewNames to @RouterPath

@RouterPath(
    name = "third",
    manualSharedViewNames = ["shared_view_image"],
    sharedEnterTransitionFactory = ThirdScreenSharedTransitionFactory::class,
    sharedExitTransitionFactory = ThirdScreenSharedTransitionFactory::class
)
class ThirdScreenFragment : Fragment() {
   ....

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       val callback = ThirdSharedElementCallBack() // auto generated class
                        .sharedViewImage({ /* get shared element view from ViewPager */ })

       setEnterSharedElementCallback(callback)
   }
}

3. setExitSharedElementCallback when before transition third screen.

@RouterPath(
    name = "second"
)
class SecondScreenFragment : Fragment() {
   ....

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       val callback = ThirdSharedElementCallBack() // auto generated class
                        .sharedViewImage({ /* get shared element view from RecyclerView */ })

       setExitSharedElementCallback(callback)
   }

   ....

   override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        ....

        // call manualSharedMapping
        router.third().manualSharedMapping(context).launch()
   }
}

License

Copyright 2018 chuross

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.

mori-router's Issues

Auto generation don't work

for reproduce just replace in your sample project app:
// project dependency implementation project(':annotation') kapt project(':compiler')
to
implementation 'com.github.chuross.mori-router:annotation:1.0.1' kapt 'com.github.chuross.mori-router:compiler:1.0.1'
and rebuild

add android support annotation

migrate AndroidX

add Parcelable support