User's guide for version 0.4

This user guide is for version 0.4 only.

A summary of the functional SuperSLiM components and how to use them.

Layout manager

The layout manager organises your content into sections, to lay out each section a SectionLayoutManager (SLM) is used. Configuration of the layout manager and any SLMs is done through attributes or layout parameters provided by your views from a recycler view adapter.

Attributes and parameters

Attributes and parameters provide both programmatic and declarative methods of configuration for the layout manager and section layout managers.

Layout parameters are used when you bind your data in your adapter:

@Override
public void onBindViewHolder(ViewHolder holder, int position) {
    /** << snip >> **/
    final LayoutParams params = holder.getLayoutParams();
    params.setSlm(LinearSLM.ID); 
    params.setFirstPosition(item.sectionFirstPosition);
    holder.setLayoutParams(params);
}

While you can do all your configuration using layout parameters, for many features it is often easier to mark up your xml layouts using attributes:

<Truncated
    app:slm_headerDisplay="start|sticky"
    app:slm_isHeader="true"
    app:slm_section_headerMarginStart="56dip"
    app:slm_section_sectionManager="linear"
/>

You can even configure the section layout through xml. For example a grid section with reflexive columns:

<Truncated
    app:slm_section_sectionManager="grid"
    app:slm_grid_columnWidth="96dip"
/>

Should you wish to update your layout parameters for any items in your adapter, you must notify recycler view of the data change:

public void updateItemConfiguration(int position) {
    /** do something that changes items layout parameters **/
    mRecyclerView.notifyItemChanged(position);
}

A reference is available with the complete documentation for layout parameters and attributes.

Implementation

See the [complete documentation](Layout Manager Implementation Details) for implementation details.

Section layout managers (SLM)

Section layout managers are responsible for the layout of non-header items in each section. Custom SLMs must added to the layout manager:

LayoutManager lm = LayoutManager.Builder(getActivity()).addSlm("my_special_layout", new MySlm()).build();

Once your custom SLM has been added, you need to let the layout manager with views use it. To do this you need to add it to the views layout params:

@Override
public void onBindViewHolder(ViewHolder holder, int position) {
    /** << snip >> **/
    final LayoutParams params = holder.getLayoutParams();
    params.setSlm("my_special_layout"); 
    params.setFirstPosition(item.sectionFirstPosition);
    holder.setLayoutParams(params);
}

or in xml:

<Truncated
    app:slm_section_sectionManager="my_special_layout"
/>

As you can see, the interface for custom SLMs is very nearly the same as for the provided ones.

It is important to make sure the right kind of layout params are set on your views. The layout manager only knows what kind of layout params to create if you set the view's section manager in xml. If you are setting the section manager in code you need to make sure you are using the right kind of layout params.

GridSLM.LayoutParams params = new GridSLM.LayoutParams(view.getLayoutParams());
params.setNumColumns(5);
view.setLayoutParams(params);

Implementations

SuperSLiM provides a number of SectionLayoutManager implementations. Each of the default implementations is stateless and can be used for multiple sections in the same layout manager.

LinearSectionLayoutManager
A ListView like linear layout. To use this layout simply add the following to your xml:

<Truncated
    app:slm_section_sectionManager="linear"
/>

or set the following in your layout params:

params.setSlm(LinearSLM.ID); 

GridSectionLayoutManager
A GridView like layout. To use this layout simply add the following to your xml:

<Truncated
    app:slm_section_sectionManager="grid"
/>

or set the following in your layout params:

params.setSlm(GridSLM.ID); 

Configuration options are also available in xml:

<Truncated
    app:slm_grid_columnWidth="96dip"
    app:slm_grid_numColumns="auto_fit"
/>

and layout params:

params.setNumColumns(GridSLM.AUTO_FIT); 
params.setColumnWidth(mColumnWidth);

StaggeredGridSectionLayoutManager
Not yet implemented.

A [reference](SLM Implementors Guide) is available if you wish to implement your own section layout manager.