Quickstart

Welcome to Magellan! We're working hard on an update; this is the work-in-progress documentation for that update. For the old documentation, see our old wiki page, Magellan 1.x Home. If you have questions/comments/suggestions for the new documentation, please submit an issue and we'll explain ourselves better.

In this page, we’ll walk through setting up your first Magellan app. It is recommended that you read through Thinking in Magellan (Published) before going through this, but it's not necessary.

Gradle

Add the dependencies you need in your build.gradle:

Core library

implementation "com.wealthfront:magellan-library:2.1.2"

Optional add-ons

def magellanVersion = '2.1.2'
implementation "com.wealthfront:magellan-library:${magellanVersion}"

// For interoperation with Magellan 1.x:
implementation "com.wealthfront:magellan-legacy:${magellanVersion}"

// For RxJava support (coroutine support is built in)
implementation "com.wealthfront:magellan-rx:${magellanVersion}"
implementation "com.wealthfront:magellan-rx2:${magellanVersion}"

ViewBinding support

Follow the instructions on the Android Developers website, or just add the following to your app's build.gradle:

android {
    // ...
    buildFeatures {
        viewBinding true
    }
}

Create your root Journey

The first step is to create your top-level container for Magellan, which is your root Journey and is sometimes called the Expedition. It doesn't have to do anything yet, though.

In our example, we'll assume you have Dagger 2 set up. If not, feel free to make Expedition an object for easy reference until you have a proper dependency injection setup.

Expedition.kt

@Singleton
class Expedition @Inject constructor() : Journey<ExpeditionBinding>(
  ExpeditionBinding::inflate,
  ExpeditionBinding::magellanContainer
)

layout/expedition.xml

<com.wealthfront.magellan.ScreenContainer
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/magellanContainer"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />

Attach to the Android lifecycle

Your Expedition won't do anything until it's attached to the Android lifecycle. This can be accomplished using Activity.setContentScreen(…)

class MainActivity : ComponentActivity() {

  @Inject lateinit var expedition: Expedition

  override fun onCreate(savedInstanceState: Bundle) {
    super.onCreate(savedInstanceState)
    /* Inject with dagger here */
    setContentScreen(expedition)
  }
}

Add your first Step

A very simple “Hello world” Step can be found below.

MyFirstStep.kt

class MyFirstStep : Step<MyFirstStepBinding>(MyFirstStepBinding::inflate)

my_first_step.xml

<TextView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:text="Hello world!"
    />

To set your initial screen, you can use Navigator.goTo(…) in your Expedition's onCreate().

@Singleton
class Expedition @Inject constructor() : Journey<ExpeditionBinding>(/* ... */) {

  override fun onCreate(context: Context) {
    navigator.goTo(FirstStep())
  }
}

Navigation

In Magellan, Steps do not directly navigate to their siblings, but rather ask their parent to do so. So, in order to navigate, pass in a navigation labmda into our FirstStep as a constructor argument.

class MyFirstStep(
  val goToNextStep: () -> Unit
) : Step<MyFirstStepBinding>(MyFirstStepBinding::inflate) {

  override fun onShow(context: Context, binding: MyFirstStepBinding) {
    binding.text.setOnClickListener { goToNextStep() }
  }
}

@Singleton
class Expedition @Inject constructor() : Journey<ExpeditionBinding>(/* ... */) {

  override fun onCreate(context: Context) {
    navigator.goTo(FirstStep(goToNextStep = ::goToStepTwo))
  }

  private fun goToStepTwo() = navigator.goTo(StepTwo())
}

Note: ::goToStepTwo here is a handy concise functional reference.

The destination can be any Navigable, e.g. a Step or a Journey. Nesting Journeys is a great way to encapsulate related Steps, making code easier to reason about and more reusable.

Next steps

That should be everything you need to get started making an app with Magellan! If you still want to know more about the library, check out:

• Thinking in Magellan, if you haven't already, for an overview of key concepts in the library.
• Library architecture and design for a deeper dive into how Magellan is structured, and how you can extend it.
• Provided and custom components for a list of what components are available to you and how to make your own.
• Migrating from Magellan 1.x if you are already using the 1.x version of Magellan in your project.
• Create an issue if there's something else you have questions about. We're happy to help!