kompass

A boilerplate free router concept for android, written in Kotlin

Support

I am happy to help you with any problem on gitter, as fast as I can!
The goal is to investigate any reported issue within 2 days.

Why you should use Kompass

• Powerful router which works great with MVP, MVVM and almost any other architecture
• Boilerplate free routing: No more bundle.putInt(ARG_SOMETHING, something)
• Very simple and clean architecture for applying custom transitions
• Generic fragment transitions
• Routing with multiple screen (which are called ships)
• Kotlin

Setup

Step 1: Enable Annotation Processing

Add this at the top of your build.gradle

apply plugin: 'kotlin-kapt'


kapt {
    generateStubs = true
}

Step2: Add Kompass Dependencies

dependencies {
    ...
    implementation 'io.sellmair:kompass:0.0.10'
    implementation 'io.sellmair:kompass-annotation:0.0.10'
    kapt 'io.sellmair:kompass-processor:0.0.10'
}

Usage

Example

I highly recommend having a look at the example app built with Kompass

Gif

Basic

Kompass makes extensive use of ship-vocabulary for its API's. Here are the main analogies:

• The Kompass is the upper most object and contains ships
• A Ship is the entity which can route to a certain Destination. This might represent a certain area of your
  activity where fragments can be loaded.
• A Sail is the actual area where fragments can be placed in. Your activity therefore sets the
  sails for a certain ship, which then 'sails' to the destination.
• A Destination represents one certain 'scene' of your app. It also holds all necessary arguments for
  the fragment/activity. For example: You might have a
  'LoginDestination', 'HomeDestination', 'SettingsDestination', ... in your application.
• A Map knows how to display a certain Destination (meaning which Fragment or Activity to load for it).
  A map (AutoMap) is automatically created for you
• A Cran knows how to push a Destination object into a Bundle. A Cran (AutoCran) is automatically
  created for you
• A Detour can implement custom transitions for certain routes.
• A DetourPilot knows about a bunch of Detours and knows when to apply which Detour

Create a Kompass

Creating the Kompass is very simple using the provided builder:

Create a Kompass: Trivial

This example is the most trivial Kompass that can be built. It accepts any object implementing
KompassDestination as Destination. We will talk about the .autoMap() part later.
It is easy, I promise :bowtie:

val trivialKompass = Kompass.builder<KompassDestination>(context)
                     .autoMap() // we will talk about this later
                     .build()

Create a Kompass: Real World Example

Here is a real-world example of Kompass, where MyCustomDestinationType is just a basic
sealed class and 'autoMap', 'autoCrane' and 'autoPilot' are extension functions automatically
generated by the KompassCompiler. But as you can see: It is very easy to create a Kompass object :blush:

val kompass = Kompass.builder<MyCustomDestinationType>(context)
                     .autoMap()
                     .autoCrane()
                     .autoPilot()
                     .build()

Create your Destinations

Destinations are simple classes or data classes which hold very simple data like

• Int
• String
• List< Int >
• Parcelable

(Everything that can be represented inside android.os.Bundle)

Destinations are typically annotated with

@Destination(target = [MyFragmentOrActivity::class])

OR implement the KompassDestination Interface (if you do not want to use the Kompass-Compiler)

I consider it a good idea implemented a sealed superclass for groups of Destinations and restrict
the Kompass object to this superclass.

Example: Annotated Destination

@Destination
class HomeDestination(val user: User)

Example: Implemented KompassDestination

class HomeDestination(val user: User): KompassDestination {
    override fun asBundle(): Bundle {
        val bundle = Bundle()
        // store user in bundle
                ...
    }

Set sails to a Ship

Once your activity has started, you have to provide a sail for the ship which should route to certain
destinations. You can do this whenever you want to (even after you routed your ship to a certain
destination). The following example will show how the FrameLayout with id 'R.id.lisa_container' will
be used for the ship called Lisa as Sail:

class MainActivity : AppCompatActivity() {
    private lateinit var sail: KompassSail

    @SuppressLint("MissingSuperCall")
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        // Step 1: Get the kompass instance (Dagger, Kodein, Singleton?, ...)
        val kompass = ...
        
        // Step 2: Get the ship called 'lisa'
        val lisa = kompass["lisa"]
        
        // Step 3: Set the sail and store the reference
        this.sail = lisa.setSail(this, R.id.lisa_container)
       
    }

    
    override fun onDestroy() {
        super.onDestroy()
        
        // Step 4 Release the sail when no longer needed
        sail.release()
    }
}

Route to a Destination

Now it is time to route to a certain destination. The following example will show how the routing
for a login-screen could look like:

    companion object {
        const val MAIN_SHIP = "main"
    }
    
    @SuppressLint("MissingSuperCall")
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val user = getUser()

        sail = kompass[MAIN_SHIP].setSail(this, container.id)
        kompass[MAIN_SHIP].navigateTo(if(user!=null) HomeDestination(user) else LoginDestination())
        
    }

Recreate Destination from Bundle

One of the strongest parts of Kompass is the elimination of hassle with bundles and arguments.
You can easily recreate the original Destination from an intent or bundle using the automatically
generated extension functions.

Example: Fragment

If you routed to a certain fragment you can easily recreate the destination from the arguments Bundle

class HomeFragment: Fragment() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val homeDestination = arguments.asHomeDestination() // Function was automatically generated
        val user = homeDestination?.user
        // ... Do something with your user object
    }
}

Example: Activity

class HomeActivity: AppCompatActivity(){
    override fun onCreate(savedInstanceState: Bundle?, persistentState: PersistableBundle?) {
        val homeDestination = intent?.extras?.asHomeDestination()
        val user = homeDestination?.user
        // ... Do something with your user object
    }
}

Advanced

The Map

Maps contain informations about how to display a certain Destination. This can be done by
starting a new Activity or creating a new Fragment. If you want to use a custom Map element, add it to the KompassBuilder

Kompass.builder(context)
       .addMap(myCustomMap)
       ...

The Cran

A cran knows how to pack a Destination object into a bundle. If you want to use a custom Cran,
add it to the KompassBuilder

Kompass.builder(context)
       .addCran(myCutomCran)

The Detour / The DetourPilot

It is a very common thing to apply transitions when one fragment is replaced by another fragment.
A Detour can very easily implement such a transition genericly.

Consider we want every fragment to slide in, when entered and slide out, when exited. We just
have to write a Detour class like this:

    @Detour
    class FragmentSlide: KompassDetour<Any, Fragment, Fragment>{
        override fun setup(destination: Any,
                           currentFragment: Fragment,
                           nextFragment: Fragment,
                           transaction: FragmentTransaction) {
            currentFragment.exitTransition = Slide(Gravity.RIGHT)
            nextFragment.enterTransition = Slide(Gravity.LEFT)
        }

    }

Every Detour will automatically be applied if the types of 'destination', 'currentFragment' and 'nextFragment'
can be assigned from the current route and

Kompass.builder(context)
       .autoPilot() // <-- will be available if you have some class annotaged with @Detour

is used!

AutoMap, AutoCran, AutoPilot

The functions

Kompass.builder(context)
       .autoMap()
       .autoCran()
       .autoPilot()

are automatically generated if possible.

• .autoMap() will be available after you specified one target for at least one @Destination
• .autoCran() will be available after you annotated at least one class with @Destination
• .autoPilot() will be available after you annotated at least one class with @Detour

BackStack

Kompass comes with an own back-stack. You should override your Activities 'onBackPressed' like:

    override fun onBackPressed() {
        if (!kompass.popBackImmediate())
            finish()
    }

GitHub