😔 Due to the nature of my job and growing popularity of Jetpack Compose, I lack the motivation to keep this project alive.
Recyclerview is one of the powerful widgets inside android framework. But creating adapters with multiple view types is always exhausting. Not anymore. MultiViewAdapter makes it easy for you to create adapter with multiple view types easily. Using the library you will be able to build composable view holders, which can be re-used across your app. Apart from this, MultiViewAdapter adds many other useful features into the library as add-ons.
🎉🎉 MultiViewAdapter v3.0 supports AndroidX. v3.0 is identical to v2.0 except for package name changes and androidx support.
- Why this library
- Feature Showcase
- Gradle Dependency
- Core Concepts
- Basic Usage
- Advanced Usage
- Learn More
- Changelog
- Contribution
- Credits
- Hall of fame
- License
Have you ever displayed multiple view types inside a single adapter? Have you ever added selection mode to an adapter? Have you ever set different span size to different items inside a single adapter? Have you ever added swipe-to-dismiss / drag & drop / infinite scrolling features to your adapter?
If you answered yes, then you must know how hard it is to do any one of these. What if you had to add all of these inside a single adapter. Phew.
- In default adapter approach, code is not re-usable as it is.
- If you have to add multiple viewtypes the code grows painfully.
- If the data needs to be updated, its hard to write the updation logic and call the correct notify method.
To solve the above problems, you can also use a different library or libraries. But such libraries have a common restrictions - Your data model will be polluted with the view logic.
- Your data objects should extend/implement from library's model, which can interfere with your object hierarchy.
- View holder creation and binding has to be written inside the data model. You are forced to keep layout and view references inside the model class itself.
- For complex lists, generic notifyDataSetChanged method will be called during updation. Also these libraries don’t take advantage of DiffUtil.
- You have to write switch cases, if you want to have different item-decorations/span-size/selection-modes/expansion-modes for different view types.
- You lose the 'type' information when accessing objects ie., you need to cast the object every time you need it.
MultiViewAdapter solves all of these requirements. The library was specifically designed in a way to not interfere with your object modeling and hierarchy.
Here are the few features which are possible with this library.
| Multiple Viewtypes | Multiple Spans | Other Features |
|---|---|---|
 |
|
 |
| Selection | Item Expansion | Section Expansion |
|---|---|---|
 |
 |
 |
The library is available via JCenter. JCenter is the default maven repository used by Android Studio. The minimum API level supported by this library is API 14.
dependencies {
implementation 'dev.ahamed.mva2:adapter:2.0.0'
}
dependencies {
implementation 'dev.ahamed.mva2:ext-databinding:2.0.0' // DataBinding
implementation 'dev.ahamed.mva2:ext-decorator:2.0.0' // Decorators
implementation 'dev.ahamed.mva2:ext-diffutil-rx:2.0.0' // RxDiffUtil
}Just add '-SNAPSHOT' to the version name
dependencies {
implementation 'dev.ahamed.mva2:adapter:2.0.0-SNAPSHOT' // Library
}To use the above snapshot version add the following to your project's gradle file
allprojects {
repositories {
maven {
url 'https://oss.jfrog.org/artifactory/oss-snapshot-local'
}
}
}Core mantra of MultiViewAdapter - Separation of view logic from data management logic. You get two different components which are :
- Section - Component to hold your data. All data related updates will run here and proper notify method will be called on the adapter.
- ItemBinder - Component which creates and binds your view holder. All view related logic should go here.
Section is the building block for MultiViewAdapter. Section will hold your data which needs to be displayed inside the recyclerview - data can be a single item or list of items. When the underlying data is changed the section will calculate the diff and call the correct notify method inside the adapter. You can add as many as Section to an adapter.
There are different types of sections.
| Name | Description |
|---|---|
| ItemSection | Section to display single item |
| ListSection | Section to display list of items |
| HeaderSection | Section to display list of items along with a header |
| NestedSection | Section which can host other section |
| TreeSection | Section which can display items in tree fashion. Ex: Comment list |
ItemBinder is the class where all view related code should be written. ItemBinder is responsible for creating and binding view holders. The method signatures are kept close to the default RecyclerView.Adapter method signatures. For each viewtype inside the recyclerview, you need to create an ItemBinder.
ItemBinder allows you to have different decoration for different view types. Apart from this, with ItemBinder you will be able to add Swipe-to-dismiss, drag and drop features.
Lets create an adapter which displays a list of cars. Follow these steps.
- You need to create an ItemBinder for your model. ItemBinder is responsible for creating and binding your view holders. Following is the code snippet of ItemBinder for CarModel class.
public class CarBinder extends ItemBinder<CarModel, CarBinder.CarViewHolder> {
@Override public CarViewHolder createViewHolder(ViewGroup parent) {
return new CarViewHolder(inflate(R.layout.item_car, parent));
}
@Override public boolean canBindData(Object item) {
return item instanceof CarModel;
}
@Override public void bindViewHolder(CarViewHolder holder, CarModel item) {
holder.tvCarName.setText(item.getName());
}
static class CarViewHolder extends ItemViewHolder<CarModel> {
TextView tvCarName;
public CarViewHolder(View itemView) {
super(itemView);
tvCarName = findViewById(R.id.tv_car_name);
}
}
}- Now create an adapter and use the ItemBinder created above. Since we are displaying a list of items we need to create an ListSection object and add the data items to it. Now add this section to adapter. Done.
class CarListActivity extends Activity {
private RecyclerView recyclerView;
private List<CarModel> cars;
public void initViews() {
// Create Adapter
MultiViewAdapter adapter = new MultiViewAdapter();
recyclerView.setAdapter(adapter);
// Register Binder
adapter.registerBinders(new CarItemBinder());
// Create Section and add items
ListSection<YourModel> listSection = new ListSection<>();
listSection.addAll(cars);
// Add Section to the adapter
adapter.addSection(listSection);
}
}Yay!! We are done.
The USP of MultiViewAdapter is adding multiple viewtypes to a single adapter easily. For each view type you need to create an ItemBinder and register it with the adapter. You don't need to manage the viewtypes yourself or write crazy if-else-if conditions.
adapter.registerBinders(new Binder1(), new Binder2(), ...);Sections are building blocks of MultiViewAdapter. You can add as many as sections to the adapter and you can nest the sections within another section as well. Each section represents a data set. If you want to display multiple data set inside a single adapter you can do so by adding any number of sections.
adapter.addSection(new ItemSection());
adapter.addSection(new ListSection());
adapter.addSection(new NestedSection());
// And so on...
MultiViewAdapter provides easy way to add selection/choice mode for the recyclerview. There are four types of mode available
- SINGLE - Only one item can be selected.
- MULTIPLE - Multiple items can be selected.
- INHERIT - Inherits the property from the parent. This the default value for sections.
- NONE - Disables the selection mode.
Set selection mode to your adapter or section.
adapter.setSelectionMode(Mode.SINGLE);
// You can set selection mode for section as well
section1.setSelectionMode(Mode.MULTIPLE); // Different mode than adapter
section2.setSelectionMode(Mode.NONE); // Disables selection for this sectionTo select an item, inside the viewholder call ItemViewHolder.toggleItemSelection() method. For example,
static class ViewHolder extends BaseViewHolder<SelectableItem> {
ViewHolder(View itemView) {
super(itemView);
itemView.setOnClickListener(new View.OnClickListener() {
@Override public void onClick(View view) {
toggleItemSelection();
}
});
}
}
MultiViewAdapter allows you to expand/collapse a single item or an entire section. There are four types of expansion mode available.
- SINGLE - Only one item/section can be expanded.
- MULTIPLE - Multiple items/sections can be expanded.
- INHERIT - Inherits the property from the parent. This the default value for sections.
- NONE - Disables the expansion mode.
Set expansion mode to the adapter.
// Expanding single item
adapter.setExpansionMode(Mode.SINGLE);
section1.setExpansionMode(Mode.MULTIPLE); // Different mode than adapter
section2.setExpansionMode(Mode.NONE); // Disables expansion for this section
// Expanding Sections
adapter.setSectionExpansionMode(Mode.SINGLE);To expand/collapse an item, inside the viewholder call ItemViewHolder.toggleItemExpansion() method. Similarly to expand/collapse a section, call ItemViewHolder.toggleSectionExpansion() method. For example,
static class ViewHolder extends BaseViewHolder<SelectableItem> {
ViewHolder(View itemView) {
super(itemView);
itemView.setOnClickListener(new View.OnClickListener() {
@Override public void onClick(View view) {
toggleItemExpansion();
// or
toggleSectionExpansion();
}
});
}
}
You can display items inside the adapter with different span count. You can customise the span count either by ItemBinder or Section.
Each ItemBinder can customise the span count by overriding a method like this. maxSpanCount is the span count of parent.
public class SampleBinder extends ItemBinder<SampleModel, SampleViewHolder> {
@Override public int getSpanSize(int maxSpanCount) {
return YOUR_SPAN_COUNT;
}
}You can also set span count for individual sections. Call section.setSpanCount(int) to set the span count for sections.
Swipe to dismiss gesture can be added in two simple steps.
Attach your RecyclerView to the adapter's ItemTouchHelper.
adapter.getItemTouchHelper().attachToRecyclerView(recyclerView);Override getSwipeDirections() inside your viewholder class.
@Override public int getSwipeDirections() {
return ItemTouchHelper.LEFT | ItemTouchHelper.RIGHT;
}
You can drag and drop the items inside or across sections. An item can be moved to any place of another item - only constraint is view type should be same for both items. Drag and drop gesture can be added by two simple steps,
Attach your RecyclerView to the adapter's ItemTouchHelper.
adapter.getItemTouchHelper().attachToRecyclerView(recyclerView);Override getDragDirections() inside your viewholder class.
@Override public int getDragDirections() {
return ItemTouchHelper.LEFT
| ItemTouchHelper.UP
| ItemTouchHelper.RIGHT
| ItemTouchHelper.DOWN;
}
Infinite loading is a add-on feature available in MultiViewAdapter ie., you don't need to create a separate adapter. You can use it with existing MultiViewAdapter, by creating an InfiniteLoadingHelper object and setting it to adapter.
protected void setUpAdapter() {
// Only 10 pages will be loaded
infiniteLoadingHelper = new InfiniteLoadingHelper(recyclerView, R.layout.item_loading_footer, 10) {
@Override public void onLoadNextPage(int page) {
// Load next page
}
};
adapter.setInfiniteLoadingHelper(infiniteLoadingHelper);
}
The library allows you to draw decoration for individual items or sections. You can create a decoration by extending Decorator which can be added to any ItemBinder or Section.
MultiViewAdapter adapter = new MultiViewAdapter();
recyclerView.addItemDecoration(adapter.getItemDecoration());
// Add to itembinder
itemBinder.addDecorator(new SampleDecoration());
// or you can add it to a Section
section.addDecorator(new SampleDecoration());Decoration and its api's are powerful feature of this library. Kindly read the full documentation to understand the complete feature. Decoration Documentation
- Documentation Website - If you would like to learn more about various other features, kindly read the documentation. All features are documented with sample code which should help you set-up complex recyclerview adapters.
- Sample App - Sample app showcases all the features of the library. Also it is an excellent reference for creating most complex use cases.
- JavaDocs
| Type | Stability | Date |
|---|---|---|
| Major | Stable | 29-October-2019 |
After being in development for more than a year and being in beta for more than three months, the library is moved to stable release.
- NestedSection visibility flags are passed down to its children. This fixes incorrect selection/expansion toggles on child views.
| Type | Stability | Date |
|---|---|---|
| Major | Beta | 3-July-2019 |
All public API's are finalized for v2.0.0 release, only bug fixes will be added in further beta's.
- Added
OnItemClickListenermethod inside the ItemSection class.
- Fixed NPE thrown by ItemSection when the item is null and expansion/selection is toggled.
- HeaderSection is has been changed to host ItemSection and NestedSection. Previously it was hosting ItemSection and ListSection.
| Type | Stability | Date |
|---|---|---|
| Major | Alpha | 31-May-2019 |
- Implemented
onDrawOvermethod inside the decoration api
- Fixed incorrect adapter position being sent to notify while calling
clearAllSelections()method - Issue - Fixed incorrect 'selection' and 'expansion' behaviour - Issue
- Pre-defined payload is sent when item's selection/expansion is toggled
- TreeSection decoration behavior is changed
- TreeSection when created, will be either expanded or collapsed by user flag
- Sample app updated is with new showcases for decoration and TreeSection api's
- Automation for app releases is enabled. Now app is pushed to playstore with a git-tag push
- Project contribution guidelines and templates are added
| Type | Stability | Date |
|---|---|---|
| Major | Alpha | 20-April-2019 |
- Initial release for v2.x refactor
Alternatively, you can visit the project's releases page for complete changelog. (View Releases) Also if you watch this repository, GitHub will send you a notification every time there is an update.
We welcome any contribution to the library. This project has a good infrastructure which should make you comfortable to push any changes. When you make a pull request CI builds the project, runs the test cases and reports the test coverage changes, so you will know whether your pull request is breaking build.
You can contribute to any of the following modules:
- Core Library
- Library Extensions
- Sample App
- Documentation
- Design assets
We are looking for project maintainers, who have made prior contributions to this project can get in touch if interested. You can contact the project owner here.
This project stands on the shoulders of open source community. It is a must to credit where it is due.
- AOSP - Android Open Source Project
- Artifactory OSS - Repository manager to host snapshot builds
- Bintray - Distribution platform
- Bitrise - CI & CD service
- Codecov - Code coverage hosting service
- Docsify - Documentation generator
- Github - Version control & issue management platform
Also this library uses following open source gradle plugins
- Bintray Release - Plugin to release the library artifacts to bintray
- Artifactory Publish - Plugin to release snapshots to artifactory oss
If this library does not suit your needs create an issue/feature request. Meanwhile check these awesome alternatives as well.
- MultipleViewTypesAdapter - Original inspiration for this library
- AdapterDelegates
- Groupie
- Epoxy
If you are using MultiViewAdapter in your app and you are happy with it, you can create a pull request to include your app information here. We will display it here.
Copyright 2017 Riyaz Ahamed
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.
