A Kotlin DSL for Android RecyclerViews.

• Getting Started
• Usage
  • Basic
  • Mapper
  • Observable List
  • Static Views
  • Composite Adapter
    • Adapter Position Lookup
  • Conditional Adapter
  • Drag & Swipe
• Build
• License

1. Add the jcenter() repository to the project build.gradle file.

buildscript {  
 repositories { jcenter() }}  

2. Add the dependency to your module's build.gradle file.

Latest version:

dependencies {  
 implementation 'com.coenvk.android.zycle:zycle:1.0.0'}  

3. Migrate to AndroidX and enable Jetifier in the gradle.properties file.

android.useAndroidX=true  
android.enableJetifier=true  

4. Add the following dependency for extra kotlin extensions.

Latest version:

dependencies {  
 implementation 'com.coenvk.android.zycle:zycle-ktx:1.0.0'
}  

An adapter can be created by supplying a list of items and the layout resource for the item view. Bind data to the item view in the onBind and add extra event listeners such as the onClick. This can be done using the Builder as illustrated below or a custom Binder can be provided by extending the Binder class. To register event listeners the Binder needs to be Hookable.

recyclerView.zycle {
	adapterOf(list, layoutRes, [viewType]) { // Binder
		onCreate { /* */ }
		onBind { item -> /* */ }
		onRecycle { /* */ }
		stableId { item, position -> /* */ }
		onClick { item, position -> /* */ }
		onLongClick { item, position -> /* */ }
		onTouch { item, position, motionEvent -> /* */ }
		onDrag { item, position, dragEvent -> /* */ }
	}
}

If you want to use different layouts, multiple Binder objects can be created and combined into a Mapper.

recyclerView.zycle {
	adapterOf(list) { // Mapper
		map(layoutRes) { // Binder
			// ...
		}
	}
}

The ObservableList class can be used with the adapter to automatically update the item views when a change is applied to the list. The list extends the MutableList class, so it can be used with the same functionality. The items in the list can be of any type. For better performance, the item class can implement Diffable and implement the areItemsTheSame and areContentsTheSame methods to compare two items.

It is also possible to add static views which don't require binding data.

recyclerView.zycle {
	viewsOf(layoutRes...)
}

A composite adapter can be created consisting of multiple adapters. This way it's easy to add headers and footers to your item list.

recyclerView.zycle {
	adapterOf {
		viewsOf(headerRes)
		adapterOf(list) { // Mapper
			map(binder)
		}
		viewsOf(footerRes)
	}
}

Since adapters can be nested in composite adapters, the adapter position from the RecyclerView.ViewHolder will not (necessarily) match the index in the inner adapter. Therefore, the AdapterPositionLookup is provided that looks up this position.

An adapter can be shown or hidden based on a condition. In addition, a substitute view can be shown when the condition is not met.

val condition = Condition()
val isEnabled by condition
recyclerView.zycle {
	adapterOf {
		adapterOf(list) {
			map(binder)
		}
		postBuild {
			showIf(condition)
			showIfElse(condition, layoutRes)
		}
	}
}
isEnabled = false // hide the list

To add simple drag functionality a drag callback can be created.

val dragCallback = DragCallback(  
    object : OnDragListener {  
        override fun onDragged(fromPosition: Int, toPosition: Int) {  
            val fromIndex = adapterPositionLookup.innerPosition(fromPosition)  
            val toIndex = adapterPositionLookup.innerPosition(toPosition)  
            list.move(fromIndex, toIndex)  
        }  
    }  
)
recyclerView += ItemTouchHelper(dragCallback)

For this to work, the Binder should implement the Draggable interface.

Secondly, a swipe callback can be used to support swipe actions like swipe-to-delete.

val swipeCallback = SwipeCallback.Builder()  
	.left {  // When swiped left
		background(context, android.R.color.holo_red_dark)  
        text(context, "Delete", spSize = 20f)  
        onSwiped {  
			val index = adapterPositionLookup.innerPosition(it)  
            list.removeAt(index)  
        }  
	}.build()
recyclerView += ItemTouchHelper(swipeCallback)

The Binder needs to be Swipeable.

For more comprehensive example usages, checkout the sample application here.

The project can be build locally using the following commands:

$ git clone https://github.com/coenvk/zycle.git
$ cd zycle
$ ./gradlew clean build

Zycle is licensed under the Apache 2.0 License.