A powerful Kotlin Multiplatform Router for Android and iOS
Support
I am happy to help you with any problem on gitter
Feel free to open any new issue!
What Kompass can do for you
- Perfect fit for
MVVM,MVI,MVP,MVXarchitectures - Powerful routing concept that targets multiple platforms like Android, JVM & iOS
- Easy to use API's
- Highly configurable implementations
Android
- Flexible routing with fragments
- Built in solution for passing arguments to fragments
- Very easy support for transitions/animations
- No XML configuration
- Built in
DSLto configure theFragmentRouter - Survives configuration changes
- Can restore the "routing stack" after process death
What Kompass can't do for now
While the core module is currently built and published for multiple platforms (JVM, iOS), there are no default Router implementations for any other platforms than Android yet. Those are currently "work in progress". Kompass can still be used as a common API for routing by providing custom implementations of a Router for your platform!
Setup
Step 1: Add the repository
Artifacts are linked to jCenter. Add jCenter repository to your root build.gradle
build.gradle
allprojects {
repositories {
jcenter()
}
}
Step 2: Add the dependency (Multiplatform)
build.gradle.kts
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("io.sellmair:kompass-core:0.2.0-alpha.5")
}
}
/* Optional Android module */
val androidMain by getting {
dependencies {
implementation("io.sellmair:kompass-android:0.2.0-alpha.5")
}
}
}
}
Step 2: Add the dependency (Android Only)
build.gradle.kts
dependencies {
implementation("io.sellmair:kompass-android:0.2.0-alpha.4")
}
Optional Step 3: (Android: Highly encouraged) Enable Kotlin's Android extensions (with @Parcelize)
build.gradle.kts
plugins {
// ...
id("org.jetbrains.kotlin.android.extensions")
}
// ...
// Currently still necessary for @Parcelize annotation
androidExtensions {
isExperimental = true
}
Usage
Example
I recommend having a look at the example app built with Kompass
Gif
Defining routes
Routes can easily be represented by data classes. Let's say your App has three routes that you might want to display: A LoginRoute, ContactListRoute and a ChatRoute:
sealed class AppRoute : Route, Parcelable
@Parcelize
class LoginRoute: AppRoute()
@Parcelize
data class ContactListRoute(val contacts: List<Contact>): AppRoute()
@Parcelize
data class ChatRoute(val contact: Contact): AppRoute()
All the arguments necessary to display a certain route should be present in the route itself. The example above uses the @Parcelize feature from the Kotlin's Android extensions
Creating a router instance (Android)
A FragmentRouter for Android can be configured quite easily by using the built in DSL for configuration.
router = FragmentRouter {
transitions {
register(LoginToContactListTransition())
register(ContactListToChatTransition())
}
routing {
route<LoginRoute> { LoginFragment::class }
route<ContactListRoute> { ContactListFragment::class }
route<ChatRoute> { ChatFragment::class }
}
}
The above DSL shows two configurations:
transitions: configures animations/transitions that should be running when routingrouting: configures whichFragmentshould be displayed for a certain route
Setting up a router instance (Android)
A FragmentRouter needs a ViewGroup to place the fragments in. This can be setup like this:
class MainActivity : AppCompatActivity(), KompassFragmentActivity {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
router.setup(savedInstanceState, R.id.container)
}
override fun onBackPressed() {
router.popRetainRootImmediateOrFinish()
}
}
Please note: In order to call the setup method, one needs to either implement KomapssFragmentActivity or KompassFragment!
Routing (Simple push)
Let's assume that the user taps on a certain contact in the contact list displayed by the ContactListRoute:
class ContactListViewModel {
private val router = TODO("Maybe use DI?")
fun onContactClicked(contact: Contact) {
router.push(ChatRoute(contact))
}
}
The code above will push the ChatRoute onto the "routing stack" and results in the ChatFragment being shown. Popping the "routing stack" will result in the ContactListFragment being displayed again.
Routing (Replacing the current route)
Let's assume the user successfully logged into your app. This should result in the current LoginRoute being replaced by the ContactListRoute
class LoginViewModel {
private val router = TODO("What about Dagger?")
fun onLoginSuccessful(user: User) {
router.replaceTopWith(ContactListRoute(user.contacts))
}
}
Wrapping multiple instructions into one lambda block will bundle them to one single operation on the routing stack. So you could alternatively write something like
fun onLoginSuccessful(user: User) {
router { pop().push(ContactListRoute(user.contacts)) }
}
Routing (Arbitrary)
Kompass supports arbitrary routing: A instruction to the router is nothing more than a function from a list of routes to a new list of routes. Let's say your app would like to remove all ChatRoute with a certain contact
fun removeContactFromStack(contact: Contact) {
router {
with(filter { it.route.contact == contact })
}
//or
router.plainStackInstruction { filter { it.route.contact == contact } }
}
Receiving the current route inside a Fragment
Accessing the route from within the any Fragment implementation is easily done by conforming to the KompassFragment interface:
class ContactListFragment : Fragment(), KompassFragment {
override val router: FragmentRouter<AppRoute> = TODO()
private val route: ContactListRoute by route()
override fun onCreate(savedInstanceState: Bundle?) {
val contacts = route.contacts
//...
}
}
Fragment Transitions
In order to support animations (fragment transitions) when routing you just need to implement a FragmentTransition. Example: Your chat app should show a Slide transition when going from the ContactListFragment to the ChatFragment and back. Simply implement the transition, check for your constraints and apply the transitions to the fragment. It is also possible to apply generic constraints to your transition using the GenericFragmentTransition API.
class ContactListToChatTransition : FragmentTransition {
@SuppressLint("RtlHardcoded")
override fun setup(
transaction: FragmentTransaction,
exitFragment: Fragment, exitRoute: Route,
enterFragment: Fragment, enterRoute: Route
) {
if (exitFragment is ContactListFragment && enterFragment is ChatFragment) {
exitFragment.exitTransition = Slide(Gravity.LEFT)
enterFragment.enterTransition = Slide(Gravity.RIGHT)
}
if (exitFragment is ChatFragment && enterFragment is ContactListFragment) {
exitFragment.exitTransition = Slide(Gravity.RIGHT)
enterFragment.enterTransition = Slide(Gravity.LEFT)
}
}
}
After the transition is implemented, just add it to the configuration of the FragmentRouter like seen above!
FragmentRouter {
transitions {
register(LoginToContactListTransition())
}
}
![[73] LoginProcessingFragment stuck loading](https://avatars.githubusercontent.com/u/18519051?v=4)
460 Dec 31, 2022
288 Nov 29, 2022
301 Dec 25, 2022
538 Dec 13, 2022
103 Dec 2, 2022
23 Dec 5, 2022
13 Nov 2, 2022
0 Jul 16, 2022
42 Dec 23, 2022
25 Jul 21, 2022
60 Dec 5, 2022
14 Sep 2, 2022
2 Mar 13, 2022
1 Apr 17, 2022
4 Jul 15, 2022
5 Dec 1, 2022
0 Oct 14, 2021
25 Nov 29, 2022
82 Dec 23, 2022