Skip to end of metadata
Go to start of metadata

Android provides a new way of creating a list view using RecyclerView that available in Android.Support.v7 library. RecyclerView is a more advanced and flexible version of ListView. This widget is a container for displaying large data sets that can be scrolled very efficiently by maintaining a limited number of views. 

Creating and configuring the RecyclerView requires a lot of work, from creating the adapter, handling the selection, handling the group layout, handling contextual actions and many more. Crosslight Android Material provides a RecyclerViewFragment to simplify this process altogether. This fragment is inherited from Material Fragment, thus inherits all the necessary API to materialize your application such as enabling transition with shared elements, adding a Floating Action Button and many more. To learn more about Material Fragment see, Using Material Fragment.

RecyclerViewFragment provides comprehensive API to enable list specific features easily. The list of specific features are as follows.

  • Displaying List of Items
  • Grouping
  • Selection
  • Navigation
  • Contextual Actions
  • Swipe Gesture

On this page:

Basic Usage

RecyclerViewFragment has a predefined layout that contains the RecyclerView control along with other supporting elements such as empty view container, header container and footer container that allows you to easily create any kinds of list view layout. To learn more about the predefined layout of RecyclerViewFragment, see recycler_view_fragment.axml.

The following code shows how to create a list view using RecyclerViewFragment

After you create the fragment, you need to specify the binding provider for your RecyclerView. To bind the data to your RecyclerView, you can use the default registered ID, TableView, as its control ID in the binding registration for compliance with other platforms. For more information about data binding in Crosslight, see Understanding Binding Providers and to learn more about MVVM see Understanding Data Binding and MVVM Design Pattern.

Next, you will need to provide the data in your ViewModel. You can retrieve the data from web service, local storage or even from a text file in your ViewModel. To learn more how to provide the data in your ViewModel see Displaying Data, and to learn more how to work with data access services see, Working with Data.

Configuring Item Layout

RecyclerViewFragment has predefined item layout that you can choose from CellStyle property. There are five default cell style:

The following code shows you how to configure cell style for navigation drawer.

If you have more complex item layout instead of using CellStyle property, you can override the ItemLayoutId as follows.

If you have to bind any other elements aside from DisplayMemberPath, DetailMemberPath and ImageMemberPath, you can use additional ItemBinding as follows.

With the additional item binding, the DateLabel in your item layout will be bound to CreatedDate property in your item.

Furthermore, you can also use CellTemplateSelector to determine which item layout to chose for specific condition. The following code shows you how to configure CellTemplateSelector to display different layouts for alternating row.

Configuring Image Settings and Image Loader Settings

The layout of a list view item usually has a visual image to accentuate the viewing experience. The built-in layout has a predefined image view that will be shown when the ImageMemberPath is specified. RecyclerViewFragment provides a way to customize this image view further by providing ImageSettings property. Using this property you can define the corner radius of your image view as follows.

Furthermore when you use Uri as your image source, you might want to enable the animation transition from image place holder to the actual image. To enable this you can set the ImageLoaderSettings.AnimateOnLoad property as follows.

Adding Header and Footer

To add header and footer in RecyclerViewFragment, simply specify the HeaderLayoutId and FooterLayoutId as follows.

Enabling Grouping

Enable grouping in RecyclerViewFragment is similar with other platforms. The grouping of items itself is done in the ViewModel, all you need to provide is the GroupItems in the RefreshGroupItems method as follows.

To learn more how to prepare the data for grouping see, Displaying Data.

RecyclerViewFragment has predefined group layout, which consists of a separator at the top and a group text as shown in the figure below.

The separator on the first group item by default will not be visible, since it most likely will be at the top of the container. 
If needed, you can hide the group text using ShowGroupHeader property as follows.

Furthermore, you can also hide the group separator using ShowGroupSeparator property as follows.

If you prefer to use your own layout for group header, please override the GroupItemLayoutId and return the resource layout you desired.

Enabling Selection

To enable selection in RecyclerViewFragment, you can set the InteractionMode to ChoiceInput as follows.

To get the selected item value in your ViewModel, you must bind the SelectedItemProperty in the binding provider as follows.

For multiple selection behavior, you can set the ChoiceInputMode to Multiple and binding the SelectedItems property as follows.

And in the BindingProvider:

Enabling Navigation

To enable navigation when the item is selected or clicked, you need to set the InteractionMode to Navigation as follows.

Furthermore in the BindingProvider, specify the navigation target ViewModel that will be executed during navigation.

Enabling Contextual Actions

In RecyclerViewFragment contextual actions are set of actions that appears when user performs long press on an item. In such case, the list item will have checkboxes where user can then select one or multiple items, and in the toolbar, a "Check All" checkbox will be displayed that allows the user to select all the items easily. Furthermore, in the toolbar we also have contextual actions provided by the user.

The following code shows how to enable and specify contextual action in RecyclerViewFragment.

You can get the checked items by binding the SelectedItems property to your ViewModel, and for the contextual action you can bind the CommandProperty to your ViewModel.

Enabling Swipe Gesture

RecyclerViewFragment provides a way to enable swiping an item in the list to provide additional actions for that particular item. This additional actions can be add easily by specifying EditingActions as follows.

Here's an example code.

Afterward, please add EditActionCommandProperty binding your BindingProvider as follows.

In the ViewModel you will need to handle both CanExecuteEditAction and ExecuteEditAction method as follows.

The CanExecuteEditAction and ExecuteEditAction gives you an EditingParameter that contains both the contextual item and the edit action. You can use these to determine what action should be done to the contextual item. If a false value is returned in CanExecuteEditAction, users won't be able to perform swipe gesture on the item.

Understanding Empty View Layout

A RecyclerView without any items will render nothing to your screen. This empty screen might mislead the user when they navigate to a screen with empty RecyclerView. A RecyclerView might be empty at first when its currently loading the data from external services, or it can be empty after all the items has been deleted. Both scenarios require a visual hint that the RecyclerView is currently loading or currently empty.

RecyclerViewFragment provides a built-in mechanism to show an empty view layout when the RecyclerView has no items. This empty view layout can be further customized by overriding EmptyViewLayoutId property. The following code shows you how to provide empty layout view to your RecyclerViewFragment.


To check out the new RecyclerViewFragment in action, you can check out these samples: