Skip to content
A navigational roller track companion for RecyclerView lists
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo
gradle/wrapper
media
rollertrack
.gitignore
LICENSE
README.md
build.gradle
dependencies.gradle
gradlew
gradlew.bat
settings.gradle

README.md

RollerTrack

Release

This library allows attaching a roller track to a RecyclerView. The roller track provides faster navigation and visualisation for users facing long lists. It is designed to work with sorted lists of related content with fixed, pre-determined datasets. Example good use cases are a catalogue of items grouped alphabetically or a list of events grouped by starting time.

Gradle Setup

Add Jitpack to your project

repositories {
    maven { url 'https://jitpack.io' }
    jcenter()
}

Then add this library to your dependencies

dependencies {
    compile 'com.github.derek-cheung:RollerTrack:v1.0.0'
}

Usage

Start by adding your RecyclerView and RollerTrack to your layout file. You are free to position these however you want.

<LinearLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="horizontal"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.tofi.rollertrack.rollertrack.RollerTrack
        android:id="@+id/roller_track"
        android:layout_width="0dp"
        android:layout_height="match_parent"
        android:layout_weight="0.2"
        android:paddingTop="10dp"
        android:paddingBottom="10dp"
        android:paddingLeft="10dp"
        android:paddingRight="10dp"/>

    <android.support.v7.widget.RecyclerView
        android:id="@+id/list_track_items"
        android:layout_width="0dp"
        android:layout_height="match_parent"
        android:layout_weight="0.8"
        android:clipToPadding="false"/>

</LinearLayout>

Next have your data model implement AlphabeticalTrackItem

data class DemoTrackItem(var title: String = "",
                         var description: String = ""): AlphabeticalTrackItem {

    override fun getTrackItemName(): String = title
}

Then sort your list of items, set up your RecyclerView normally and attach it to an AlphabeticalTrackRollerHelper

val trackItems: List<DemoTrackItem> = loadTrackItems().sortedBy { it.title }

val adapter = RollerTrackAdapter(trackItems)
list_track_items.adapter = adapter

val layoutManager = LinearLayoutManager(this, LinearLayoutManager.VERTICAL, false)
list_track_items.layoutManager = layoutManager

val rollerTrackHelper: AlphabeticalRollerTrackHelper<DemoTrackItem> = AlphabeticalRollerTrackHelper()
rollerTrackHelper.attachToRecyclerView(list_track_items, roller_track, trackItems)

If you wish to create your own list of RollerTrackItems, just extend RollerTrackHelper and return your own items in generateRollerTrackItems.

class CityRollerTrackHelper: RollerTrackHelper<City>() {

    override fun generateRollerTrackItems(listItems: List<City>): MutableList<RollerTrackItem<City>> {
        val rollerTrackItems = mutableListOf<RollerTrackItem<City>>()

        var currentRollerTrackItemData: MutableList<City> = mutableListOf()
        var currentRollerTrackItem: RollerTrackItem<City> = RollerTrackItem("", currentRollerTrackItemData)
        listItems.forEach {
            val countryCode = it.countryCode
            
            if (currentRollerTrackItem.trackItemName != countryCode) {
                currentRollerTrackItemData = mutableListOf()
                currentRollerTrackItemData.add(it)
                currentRollerTrackItem = RollerTrackItem(countryCode, currentRollerTrackItemData)
                rollerTrackItems.add(currentRollerTrackItem)

            } else {
                currentRollerTrackItemData.add(it)
            }
        }

        return rollerTrackItems
    }
}

Customisation

You can customise the appearance of the RollerTrack with xml styling.

<com.tofi.rollertrack.rollertrack.RollerTrack
        xmlns:demo="http://schemas.android.com/apk/res-auto"
        android:id="@+id/roller_track"
        android:layout_width="0dp"
        android:layout_height="match_parent"
        android:layout_weight="0.2"
        android:paddingTop="10dp"
        android:paddingBottom="10dp"
        android:paddingLeft="10dp"
        android:paddingRight="10dp"
        demo:rollerTrackTrackLineColor="#FF5722"
        demo:rollerTrackCurrentTextColor="#4CAF50"
        demo:rollerTrackBackgroundTextColor="#4CAF50"
        demo:rollerTrackCurrentItemTextSize="40sp"
        demo:rollerTrackBackgroundItemTextSize="10sp"/>

Demo

A demo is provided under the demo module. Clone this repo and run the demo app to see it in action.

License

Provided with MIT license. See LICENSE for full details.

You can’t perform that action at this time.