Awesome
Square Cycler – a RecyclerView API
The Square Cycler API allows you to easily configure an Android RecyclerView declaratively in a succinct way.
Design principles
- It should be declarative. You tell us what you want, not what to do.
- It should have all the code regarding one type of row together. The less switch statements the better (some existing libraries and Android recycler itself group all creation together, and all binder together elsewhere; that's close to the metal but far from developer needs).
- It should be able to cover common needs, specially making adapter access unnecessary. Access to the
RecyclerView
for ad-hoc configuration is allowed. - It should be strongly typed.
- It should include common features: edge decoration, sticky headers, etc.
- It should make it easy to inflate rows or to create them programmatically.
- It should make it easy to create common custom items.
How to use it
- Configure the recycler view when you create your view.
- Provide data each time it changes.
Configuring block
The configuring block is the essence of the recycler view. It contains all the row definitions and how to bind data.
You can ask the API to create the RecyclerView object for you – using the create
method – or
configure an existing instance – through the adopt
method. The latter is useful if you already
have a layout which the recycler view is part of.
Examples:
val recycler = Recycler.create<ItemType>(context, id = R.id.myrecycler) {
...
}
val recycler = Recycler.adopt(findViewById(R.id.my_recycler)) {
...
}
In both cases you will receive a Recycler object which represents the RecyclerView and allows you to set data afterwards.
The configuring block will have some general configurations, for instance an item comparator, and a row definition for every type of row you need.
Generics
The generics used along this documentation are as follow:
I:
ItemType. General type for all the data items of the rows.S:
ItemSubType. Data item type for the particular row being defined.V:
ViewType. View type for the particular row being defined.
Row definitions
Using a layout:
row<I, S, V> {
forItemsWhere { subitem -> ...boolean... }
create(R.layout.my_layout) {
// you can get references to sub-elements inside view
val subView = view.findViewById(...)
bind { subItem ->
// assign values from subItem to view or sub-elements
}
}
...more row options...
}
The subtype S
will automatically make the row definitions
only be used for that type of item I
.
forItemsWhere
clause is optional. In case you need to filter
by an arbitrary predicate on S
(notice you don't need to cast).
create
will inflate the layout and assign it to a var view: V
.
You can get references to sub-components using findViewById
.
bind
receives the subItem (again, already cast to S
).
You can use view
and your own captured references from
the create
block to assign values. Notice that you don't need to
cast view as V
. It's already of that type.
General approach:
row<I, S, V> {
forItemsWhere { subitem -> ...boolean... }
create { context ->
view = MyView(context)
// you can get references to sub-elements inside view
val subView = view.findViewById(...)
bind { subItem ->
// assign values from subItem to view or sub-elements
}
}
...more row options...
}
This is the general case. Instead of inflating a layout, create
provides a context for you to create a view of type V
and assign
it to view
. As usual, you can use that view
reference or any
other reference you've obtained inside the bind
block.
Extra item definitions
Recycler views allow for the inclusion of one extra (but optional)
item. This is useful when you want to show your state.
For example: "no results" or "loading more...".
The extraItem
is independent from the main data list and
doesn't need to be of type I
.
Definitions for extraItem
s are analogous to normal rows
and follow the same convention. However, the definitions are only applied
to the extra item you provide along with the data (if any).
extraItem<I, S, V> {
forItemsWhere { subitem -> ...boolean... }
create { context ->
...
bind { subItem -> ... }
}
...more row options...
}
Notice that you can define several different extraItem
blocks, with the same or different sub-types S
and
optional forItemWhere
.
bind
is also provided in case your extra item has data.
Imagine you are filtering by fruit. If you've selected "apples"
you want to show "No more apples" instead of "No more fruits".
That can be achieved with an extra item of type
NoMore(val fruitName: String)
.
More row options
Recycler API offers an extension mechanism. Extensions are useful for cross-cutting concerns like edges or headers which will be discussed separately.
These extensions will be configured in the same way, through a definition block.
Extensions might offer special configuration for certain
types of rows. For example, edges can define a default
edge configuration, but use different values for the rows
of type Banana
. In that case the row<Banana>
definition
will include its special configuration.
See extensions section for more details.
General configuration
The RecyclerView uses certain general definitions that can be configured here as well.
stableIds { item -> ...long... }
If you provide a function that returns an id of type Long
for every item in the data, the recycler view will be able
to identify unchanged items when data is updated, and
animate them accordingly.
itemComparator = ...
When data is updated the RecyclerView compares both datasets to find which item moved where, and check if they changed any data at all.
Android's RecyclerView's can do that calculation but it needs
to compare the items. The developer must provide the comparison.
You can provide an ItemComparator
implementation which is
simpler than the required DiffUtil.Callback
one.
An ItemComparator
provides two methods:
areSameIdentity
returns true if they represent the same thing (even if data changed).areSameContent
tells if any data changed, requiring re-binding.
If your items are Comparable
or you have a Comparator
you can create an automatic ItemComparator
. Just use:
fun itemComparatorFor(Comparator<T>): ItemComparator<T>
fun naturalItemComparator(): ItemComparator<T>
ifT
isComparable<T>
It will implement both: identity and content-comparison
based on Comparator
or Comparable
. That means that items
will either be different or identical, therefore never updated.
But for immutable (or practically immutable) items
it works pretty well.
Data providing
Once you configured your recycler view you just need to give it data.
The Recycler
object returned by the configuring block
represents your recycler view. It has three properties:
view
: the RecyclerView. You can add it to your layout if it was created by the API.data
: the list of items to show.extraItem
: the extra item to add to the end (or null).
Notice that data
is of type DataSource<I>
.
DataSource
is a simplified List
interface:
interface DataSource<out T> {
operator fun get(i: Int): T
val size: Int
}
You can convert an Array
or a List
to a DataSource
using the extension method toDataSource()
:
arrayOf(1, 2, 3).toDataSource()
.
The advantage over requiring a Kotlin List
is that you
can implement your arbitrary DataSource without having to
implement the whole List
interface, which is bigger.
Extensions
Extensions are a mechanism to add simple-to-configure features to Recyclers without adding dependencies to this library.
Row type extensions
You can create extensions for common custom views in your project:
myCustomItem<I, S> {
forItemsWhere { ... }
bind { item, view ->
view.title = ...
view.message = ...
...
}
}
The extension method just needs to use a different row definition method that lets you define how to create the view by separate.
For instance:
/**
* Extension method for a custom item, allowing full control.
* ```
* myCustomItem<I, S> { // this: BinderRowSpec<...>
* // you can configure extra stuff:
* forItemsWhere { ... }
* // and then define your bind lambda:
* bind { item, view ->
* view.title = ...
* view.message = ...
* ...
* }
* }
* ```
*/
@RecyclerApiMarker
inline fun <I : Any, reified S : I> Recycler.Config<I>.myCustomItem(
crossinline specBlock: BinderRowSpec<I, S, CustomView>.() -> Unit
) {
row(
creatorBlock = { creatorContext ->
CustomView(creatorContext.context)
.apply { ... }
},
specBlock = specBlock
)
}
/**
* Extension method for passing just a bind lambda.
* ```
* myCustomItem<I, S> { item, view ->
* view.title = ...
* view.message = ...
* ...
* }
* ```
*/
@RecyclerApiMarker
inline fun <I : Any, reified S : I> Recycler.Config<I>.myCustomItem(
noinline bindBlock: (S, CustomView) -> Unit
) {
row(
creatorBlock = { creatorContext ->
CustomView(creatorContext.context)
.apply { ... }
},
bindBlock = bindBlock
)
}
Notice:
- You don't need to declare extension methods for each row. It's just a shorthand for those things your project uses repeatedly.
- You can also use analogous methods that provide the index of the item in binding.
Decoration extensions
TODO: code and documentation need to be added.
License
Copyright 2019 Square Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.