Skip to end of metadata
Go to start of metadata

Almost all mobile apps involve working with data, even just presenting a simple list of data to the user interface. The Android platform ships with a flexible ListActivity(TViewModel) Class that allows you to present a list of items, and customize its cell template through the use of the LayoutInflater and specifying the layout resource you wish to inflate.

Crosslight for Android ships with a list activity which supports not only the use of fragments as in the default Android design, but also enhanced and streamlined to conform the Crosslight Framework design pattern. This enables consistency between cross-platform development, but also customizable at the same time, enabling you to build powerful data presentation apps in a relatively shorter time. The list activity also supports grouped display of items that also conforms to the Android UI guidelines. Crosslight list activity for Android was built and tested extensively to make sure that your apps will perform silky smooth and provides blazing fast user experience.

Dealing with list adapter with images can be tricky as inefficient implementation of the array adapter will cause lag and performance issues when the cell is reused during scrolling. Crosslight takes care most the details in the back-end implementation, enabling you to develop faster and deliver projects in a shorter time.

On this page:

Displaying Simple Data

Presenting data in Android with Crosslight is very easy. Start by defining a list activity that derives from ListActivity<TViewModel> -- a specialized list activity that supports ViewModel and automates most data-related tasks based on the supplied ViewModel.


This illustration is the result of code above,

You specify the ListViewInteraction by overriding the property and setting it into None. Then register the ListView at runtime to a view identifier called TableView as specified in the binding provider which is specified using the ImportBindingAttribute. The result is seen as an image to the right.

For more information about the basics of data binding in Crosslight, see Understanding Binding Providers.

Displaying Grouped Data

To present the list in the form of sections, you can define your own XML layout for the group style and supply it via overriding the GroupLayoutItemId property. You can use a combination of GroupItemLayoutId as well as  ContentLayoutId.

Keep in mind that the underlying ViewModel is required to supply the grouped data in the items source. For more information, see Displaying and Customizing Group List.

Customizing Group Style

Customizing group style is simply done by defining your own XML layout for the group style and supply it via overriding the GroupLayoutItemId property. Another variation is shown as follows. You can find the example in our Data Samples shipped after you have successfully installed Mobile Studio.


Showing Group Section Index

The ListActivity(TViewModel) Class shipped in Crosslight for Android allows for indexing a large number of groups. You can easily activate this feature by overriding the FastScrollEnabled property to true. To always show the fast scroll indicator on the right side, you can use override the FastScrollAlwaysVisible property and set it to true.

The following illustration shows the result.

Enable Searching

In most scenarios, mobile apps perform searching against a list. To enable the searching feature in Android, you need to subclass a special list class called SearchableListActivity and provide two information, which are SearchButtonId and SearchScope. The SearchButtonId indicates the android:id of the search button specified in the layout XML file while SearchScope specifies the scope on which data searching should be performed against. Typically, this is set up in the ViewModel.  Optionally, you can specify a SearchHint to specify the search hint that will be shown on the UI. Let’s take a look at the following code:


Notice that there is a slight difference in the Activity attribute specified. The LaunchMode = LaunchMode.SingleTop tells the Android system that after doing a search, do not create a new Activity. The MenuLayoutId needs to be specified, containing the search button menu item, it looks as follows

The android:id is the Id that will be used in the overridable SearchButtonId. The android:actionViewClass must be specified as this is the default Android search view class that will be inflated when the search button is activated. 

When user submits the search query, the searchable list activity automatically raises the Filter method of the ViewModel – if the ViewModel implements IFilteredSource Interface. By default, certain data-aware ViewModel base classes such as ListViewModelBase Class that ships with Crosslight has implemented the necessary interfaces to streamline the data operations.

For more information about filtering data in ViewModel, see Implement Searchable List. For more information about the ViewModel base classes available in Crosslight, see Selecting a ViewModel Base Class to Get Started.

The result is as follows:


Customizing Cell Styles

The list view comes with four predefined cell styles that you can quickly customize through a property configuration. The supported cell styles are: Right Detail, Left Detail, Subtitle, and Subtitle with Image.

To customize the cell style, use the predefined styles given in the Crosslight for Android resources and override the ListItemLayoutId property.

The predefined resources for the list view item styles are: Resource.Layout.tablecellleftdetail, Resource.Layout.tablecellrightdetail, Resource.Layout.tablecellsubtitle, Resource.Layout.tablecellsubtitlewithimage.

For presentation consistency, you should use only one kind of cell style at a time. Most list view configuration in particular and Android view programming in general perform initialization only once at object creation phase. Dynamic changes to the view elements at runtime are rare and not encouraged as this will disorient the users with UI inconsistency.

As a result, the ListItemLayoutId property, similar to many other properties, are designed in a way that prevents the value to be changed at runtime. These properties typically do not have setter. In order to change the value, override the property and provide the desired value in the getter.

The following illustrates the various predefined list item cell styles supported in Crosslight for Android.

Using Custom Cell Template

In addition to the predefined cell styles, you can also specify your own custom template as list view item template – also known as custom cell template. In Crosslight for Android, you can easily specify custom templates by providing custom XML layouts and override the ListItemLayoutId property. Look at the following custom template XML.

 The android:id set to each of the views must correspond to the view identifier set in the BindingProvider Class located in the shared core project for the bindings to work.

This illustration is the result of code above,

You will need to provide the correct android:id for each of the view to match the one specified in the binding provider of the activity as this is the contract that binds the view with the model. For more information about the basics of data binding in Crosslight, see Understanding Binding Providers

Customizing Item Styles

At some point, you will want to show changes to the UI when certain property has changed from the model. Crosslight provides a MVVM-technique to customize the item appearance called item style selector which enable you to easily customize item styles that automatically synchronizes to the view when the affected properties of the model has changed – this is made possible because of the two-way data binding in Crosslight.

To take advantage of this feature, create a class that implements the style selector logic in the shared application layer, then bind the class through a converter to the list view in the binding provider. There are no configurations required at the Android layer.

The following example shows how to set strikethrough text style for items marked as sold.

This illustration is the result of code above,

The definition for the label in the binding provider class looks as follows:

The ItemBindingDescription Class represents the binding information specific to the view elements in the cell template. In the above example, it binds the IsSold poperty to the TextView’s StyleAttributes. In the converter class, an appropriate style will be provided based on the value of the IsSold property. If the item’s IsSold is true, the label will be styled as strikethrough, otherwise the normal style will be used. 

Capturing Selection

In addition to display a list of items, the list view can also capture selection which is a common requirement in most data-drive apps. When users tap on one more or more items, a selection indicator (checkmark) appear on the right side of the item cell which indicates that the item is selected.

Capturing Single Selection

If you want to enable single selection for the list view, you will need to override the InteractionMode property to return ListViewInteraction.ChoiceInput and the ChoiceInput property to return ChoiceInputMode.Single. The RegisterViewIdentifier method in the InitializeView method is use to register a view identifier at runtime. Take a look at the following code.

This illustration is the result of code above,

Capturing Multiple Selection

To capture multiple selection, you will also set the same properties as you would in a single selection, but this time, you will need to override the ChoiceInput property to return ChoiceInputMode.Multiple. In this example you use the ListItemLayoutId from the default Android resource, which is the CheckableListView. 

This illustration is the result of code above,

Customizing Selection Appearance

You can also customize the appearance of the “checked” state in Android using a state-list drawable as shown in the Inventory Tracker sample. For more information on state-list drawable, please visit Android Developers documentation. The following code shows how to implement the custom selection indicator with a blue (holo-themed) background in Android.

You provide a list view background selector (/Resources/Color/listviewbackgroundselector.xml) to be used in the Styles.xml.


The Styles.xml file located in /Resources/Values/Styles.xml

The @color/listviewbackgroundselector means, use the file listbackgroundselector.xml from the Resources/Color folder as the list view background selector.

Then finally you can use it in the ItemListLayout.xml which is to be inflated in the ItemListActivity.

The ItemListActivity looks as follows. The list view layout is shown in bold.

This illustration is the result of code above,

Now whenever the list view item is “selected” it will have its background changed.

Editing List View

The list view is great for presenting data, however sometimes you need to make changes to the list view itself, for example, deleting one or multiple data. Typically, Android introduces multiple selection through a long press of the list item, in which a contextual action bar will be presented to the user, allowing them to edit the items on the list view. For this purpose, Crosslight for Android provides a ContextualActionBarSettings property that defines this contextual action bar. 

To enable the contextual action bar when the list item is long-pressed, you need to override the EditingOptions property to return EditingOptions.AllowEditing|EditingOptions.AllowMultipleSelection and override the ContextualActionBarSettings property and return the appropriate settings. The following code shows how to enable multiple delete on the list view.