Home

• Overview
• Basic Usage
• Sample App

Overview

Epoxy helps you build complex RecyclerView adapters. Every item type is represented by an EpoxyModel, which controls the data and view binding for each item on screen. An EpoxyController implementation declares what models to add to the RecyclerView. Epoxy adds the glue for binding your models, computing diffs to find changes, saving view state, and other RecyclerView lifecycle tasks. Annotation processing is used to generate helper code to remove most of the boilerplate around the process.

Basic Usage

As an example, our PhotoController shows a header, a list of photos, and a loader (if more photos are being loaded). The controller's setData(photos, loadingMore) method is called whenever photos are loaded, which triggers a call to buildModels so models representing the state of the new data can be built. After models are rebuilt, Epoxy notifies the RecyclerView of any changes between the previous models and the new models. Epoxy manages creating new views and binding them to the corresponding model when necessary.

public class PhotoController extends Typed2EpoxyController<List<Photo>, Boolean> {
    @AutoModel HeaderModel_ headerModel;
    @AutoModel LoaderModel_ loaderModel;

    @Override
    protected void buildModels(List<Photo> photos, Boolean loadingMore) {
      headerModel
          .title("My Photos")
          .addTo(this);

      for (Photo photo : photos) {
        add(new PhotoModel(photo));
      }

      loaderModel
          .addIf(loadingMore, this);
    }
  }

The HeaderModel class might look something like this:

@EpoxyModelClass(layout = R.layout.view_model_header)
public abstract class HeaderModel extends EpoxyModel<HeaderView> {
  @EpoxyAttribute String title;
  @EpoxyAttribute String subtitle;
  @EpoxyAttribute(DoNotHash) View.OnClickListener clickListener;

  @Override
  public void bind(HeaderView view) {
    view.setTitle(title);
    view.setSubtitle(subtitle);
    view.setOnClickListener(clickListener);
  }
}

Visit the links in the sidebar to see more detailed examples, and for advanced usage tips and instructions.

Sample App

The sample app demonstrates an EpoxyController class with several different types of models. A grid layout manager is used to allow two columns of buttons. EpoxyModelGroups are used to group nested horizontal RecyclerViews with buttons on their left. There are buttons to add and shuffle the carousels, and within each carousel there are buttons to add, shuffle, and change colored blocks.

Epoxy saves the scroll position of the carousels, and manages the diffing of state changes to update the RecyclerView and allow for the animations.

Clicking on a colored block shows a star animation, which demonstrates the change payload feature. This allows a model to see what the changes in state are when it is bound to a view.

Check out the code!