Floating Tutorial Activity - Open Source

feature

Today, I pushed out a new open-source library:

https://github.com/klinker24/Android-FloatingTutorialActivity

After creating this style of UI for Pulse SMS, I decided that I really loved the way it worked, looked, and the functionality that it provided. It wasn't trivial to create or manage this type of Activity on your own, so I wanted to wrap it up in something that anyone could use.

The library is simple, easy-to-implement, and highly customizable when you start to get into it. For Pulse, I have used this UI for the login page, prompting the users to rate the app, as well as making a purchase.

Library Structure

The library is written and tested completely in Kotlin. I have been using Kotlin throughout my projects - personal and consulting - for quite awhile now, but I realized I had never put out any open-source work, with it.

Not into the Kotlin kick just yet? No problem. I have included a Java style readme, as well as a sample app using Java. Take your pick, but I highly recommend starting to dig into Kotlin by checking out that version of the sample app.

Usage

To include the library in your app, just add the gradle dependency:

dependencies {  
    compile "com.klinkerapps:floating-tutorial:1.0.2"
}

When you are ready to start using it, you will need to create a new Activity that extends FloatingTutorialActivity and implements the FloatingTutorialActivity#getPages function:

class ExampleActivity : FloatingTutorialActivity() {  
    override fun getPages(): List<TutorialPage> {
        ...
    }
}

That function will return the list of pages that the user will see. The simplest implementation of providing a page would look like this:

override fun getPages() = listOf(  
    object : TutorialPage(this@SimpleDialogExample) {
        override fun initPage() {
            setContentView(R.layout.simple_layout)
        }
    })
)

Check out the readme for a more in-depth look at what is available to the individual pages!

Animating the layouts

animation

In my examples, as well as my own usage of this library, I like to provide subtle animations the first time that a user views a TutorialPage. If they were to go backwards in the tutorial, then return to a page for a second time, I do not show the animation again. If you would like to animate your pages in this way, you can override the TutorialPage#animateLayout function.

object : TutorialPage(this@SimpleDialogExample) {  
    override fun animateLayout() {
        val view = findViewById<View>(R.id.example_view)

        // do some animation here. I have an example animation that you could use:
        // https://github.com/klinker24/Android-FloatingTutorialActivity/blob/master/sample-kotlin/src/main/java/xyz/klinker/floating_tutorial/util/AnimationHelper.kt
        AnimationHelper.quickViewReveal(view, 300)
    }
})

Providing TutorialPage and Activity Results

animation

Sometimes, you may need store and provide some kind of state within the tutorial. For example: if you are using the tutorial to log in a user, you will probably need the calling Activity to know if the login was successful or not.

Please see the SelectionDialogExample as an example of providing the calling Activity the result of your FloatingTutorialActivity.

Other times, you may need to know the result of the previous page, to display the UI for the next page. In the RateItExample, the first page asks the user to give a thumbs up or thumbs down.

  • If the user selects thumbs down, the second page will ask them if they want to provide feedback.
  • If the user selects thumbs up, the second page will ask them if they want to rate the app on the Play Store.

This is a good example of the need to communicate the previous page's result to the current page, and customizing the current page, based on that result.


If you have followed Jake and I's work in the past, you know we are passionate about open-source contributions. While we can't open-source everything we make, we do our best to get the highlights out there.

Not every Android developer is as fortunate as we have been. Our open source contributions are a great way to give back to the community that has given us so much.

I am really happy with the way that this turned out. It is easy to use, provides great functionality, has a decent amount of tests, and is written in Kotlin.

Sound off in the comments to let me know if this is something you will be implementing in your apps or what I can do to improve it. Enjoy!