Skip to end of metadata
Go to start of metadata

Displaying data is one of the most crucial objectives in mobile business apps. In essence, a mobile business app typically include these data-aware functions: listing data, filtering data, and updating data. Crosslight was designed with a vast array of powerful features that make displaying data a breeze, enabling you to build mobile business apps as easy and as rapid as possible.

For more information about accessing and managing data from a source, whether locally or remotely, please refer to Working with Data.

On this page:

Displaying Simple List

To start with a simple list, create a new ViewModel class that derives from ListViewModelBase(T) Class. The ListViewModelBase(T) Class contains several pre-built features to make it easy to present a list of data.

See the following class diagram to explore the members exposed in the ListViewModelBase(T) Class.

In the simplest implementation, you only need to provide the SourceItems property with the data source, refer to the following code example.

The SourceItems property represents the raw data source which means it is not necessary sorted or filtered. To present sorted data, override the OnSourceItemsChanged method and set the sorting expression using LINQ.

The next step is to define which property of the model that you wish to display in the list, which is commonly known as DisplayMemberPath. To set the display member path, you add a binding description to the binding provider, such as shown below.

You should use the AddBinding with isDirectSource overload which instructs the binding to retrieve the source directly from the specified value which in the above example is ProductName.

Now that you have the ViewModel class ready, you need to create the view context in the desired platforms. The view context consumes the shared ViewModel in loosely-coupled fashion and automatically perform data operations based on the application logic in the ViewModel.

To learn more how to implement the platform-specific view for data presentation, see Platform-specific Guides.

Displaying Grouped List

To display a list of items, you would normally provide the items to the SourceItems property of the ListViewModelBase(T) Class. In order to display the grouped items properly, create a model that inherits the GroupItem(T) Class to provide the grouping information.

Then provide the group items information to the GroupItems property of the ListViewModelBase(T) Class, then call the RefreshGroupItems method in the constructor of the view model as well as right after the items has changed in the OnSourceItemsChanged method.

When the data control in each target platform detects a valid data source from the GroupItems property, the control will be automatically display the grouped data instead of the plain one.

To learn more about the behavior of presenters in each specific platform, you may want to refer the Understanding Presenter Services section for each platform in Platform-specific Guides.

Implementing Searchable List

In addition to sorting and grouping, the ListViewModelBase(T) Class also supports data filtering since it implements the IFilteredSource Interface.

The data filtering can be easily implemented by overriding the Filter method. Similar to the grouping, you can write LINQ to build the filtering expression and set its result to the FilterItems property.

See the following code for an example.

The Filter method will be automatically called by the data control in each supported platform. For instance, when users type on the SearchBar control that is attached to the table view in iOS, it invokes the Filter method and pass the query and optionally the active scope to obtain the filtered results.

To learn more how to configure data filtering and view-related settings, see Platform-specific Guides – Data Presentation Overview.

Configuring List Interaction Mode

When a list of data are presented to the screen, users will be most likely expect to be able to tap on the item and perform one of these interactions:

  • Navigate to detail
  • Perform a custom action
  • Single selection
  • Multiple selection

The following examples show how to configure the interaction mode in the shared application layer. Through the binding provider, the configuration will be applied across all platform-specific views.

Set Detail Navigation

Perform A Custom Action Through Command

Responding to Single Selection

Repsonding to Multiple Selection

The example code above basically register the binding between the source which is the ViewModel and the target which is agreed through the view identifier contract. To learn more about the Crosslight binding concept, see Understanding Data Binding and MVVM Design Pattern – Part 2.

The user interaction is made possible in the ListViewModelBase(T) Class because the class conforms to the ViewModel implementation, i.e., implements INotifyPropertyChanged interface. Furthermore, the ListViewModelBase is packed with selection-related properties and methods override that will be seamlessly raised by the corresponding view based on the binding definition – thanks to the two-way data binding feature in Crosslight. To learn more about the data binding feature, see Crosslight Data Binding Features.

Although you can get the selection through the available selection properties, you might want to capture the selection changes immediately by overriding the selection methods you interested in. See the following examples.

Once the shared configuration are set, the remaining step is to configure the interaction mode property of the view context in each platform. For more information about view specific settings, see Platform-specific Guides – Data Presentation Overview.

Customizing List Template and Appearance

In the previous sections, you’ve learnt how to display a data list that presents a single information. While the grid or tabular style data presentation is less common in mobile business apps, the ideal way to show more information is by customizing the template of the item. As you have seen in popular mobile apps, it’s possible to show an image with two or three lines of text in a single row.

Crosslight lets you easily achieve this scenario by customizing the item template and appearance in the view, then defines the binding description in the shared binding provider.

The following example shows how to configure the binding for pre-built templates, while allowing you to add additional binding descriptions that match the identifier contract in your view.

The ItemBindingDescription Class represents numerous properties that affect the presentation of the items in data control. As seen in the example above, three of the most essential properties are:

The item binding description was modeled in such a way that conforms to the common mobile UI design pattern and best practices. As the results, this makes data binding on item template really easy and elegant.

The following illustration visualizes how each member path is bound to the item template.

In addition to the pre-built templates, it’s also possible to add custom controls to the item template and add the binding associated to each custom control. To add additional binding descriptions for the item template, use the AddBinding method available in the ItemBindingDescription Class class and specify the target view and the property to be bound.

To learn more how to create a custom item template in platform-specific views, see Platform-specific Guides – Data Presentation Overview.

Implementing Editable List

In addition to navigation, editing the list is considered a common user interaction in mobile business apps. Crosslight provides powerful features that make it easy to implement editable list – allowing users to add new items to the list, select one or more items for deletion, or perform custom actions on the particular items.

The items collection in Crosslight apps automatically react to the collection changes – thanks to the powerful MVVM and binding framework in the Crosslight Foundation. This means that you can simply insert new items or remove items from the collection in the ViewModel, while the view context recognizes the changes and update the user interface – all automatically.

The two-way binding support on a collection is crucial to create reliable data-driven mobile apps. This enables you to write user interaction logic completely in the shared application layer without concerning the view technologies that will consume the shared application code. 

The following illustration explains how two-way collection binding and views work together seamlessly in Crosslight.

In addition to the programmatic collection changes, you may also want to present user interface that allows users to make changes to the list. This is typically done through buttons that appear on the toolbar. Crosslight provides a specialized ViewModel class called EditableListViewModelBase(T) Class that provides pre-built commands and members to make it easy to respond to the editing actions.

To get started, derive your ViewModel class from EditableListViewModelBase(T) Class. Make sure the items you provided to the SourceItems is of observable collection type. Then override the methods of each action that you wish to support such as shown in the example code below.

Once the programming with the ViewModel is completed, as usual, you need to register the binding description in the binding provider class which is associated to the view through ImportBindingAttribute Class. See the following examples to register the required binding for editing commands.

Using List as Navigation Interface

In addition to display a list of data, it’s also a common practice to use the list design pattern as navigation interface. Since the list control accepts any IEnumerable kind of source, you can provide the navigation items and set it as the SourceItems property in the ViewModel. This allows you to easily create dynamic, data-driven navigation menu.

Crosslight provides NavigationItem Class that represents the model for navigation source that you can directly consume in your apps. The NavigationItem Class contains several members commonly used in navigation.

The following example shows how to use NavigationItem as the source for the navigation interface.

In the binding provider, you can easily register the item binding for the display, navigation as well as the image member path which will be used by the data controls, see the following example.

In summary, Crosslight offers a vast array of time-saving features that let you easily build beautiful data-driven mobile apps. Many cross-platform challenges related to data management that were previously difficult to address – or took lot of time with tedious workarounds – are now elegantly addressed with Crosslight. In this guide, you have learnt how to work with data, from simple list and grouped list to item template customization and list editing. Note that this guide is focused on the shared application layer that are independent to the view platform. For more information about platform-specific features related to data presentation, see Platform-specific Guides – Data Presentation Overview.

Implementing Incremental Loading

Loading large amount of data on a mobile device could be exhaustive, not only just for the mobile data quota, but also battery life. As an enterprise-level mobile framework, Crosslight has built in a native support to allow loading of data in small chunks, instead of loading all of them at once. As most built-in list view comes with native virtualization, we can take advantage of the feature by loading data incrementally. This page discusses how to enable the incremental loading in Crosslight-powered apps.

The incremental loading is the process of loading data in small chunks instead of the entire set of data. Imagine you a small number of records, perhaps 10,000 records. When the user navigates to the view model, then the process of loading 10,000 records data starts, it will take a long time for the operation to complete. The incremental loading technique is an excellent approach to tackle this scenario. Instead of loading everything at once, it is more preferable loading data in small chunks. The incremental loading technique is used because of several advantages:

  • Takes a less toll on the server in providing the data to the client.
  • Takes a better toll on battery life.
  • Lightweight data loading, therefore using lighter bandwidth.
  • Provides data just when the user needs it.

To enable incremental loading on Crosslight-powered projects, start from the core view model. Enable the ISupportIncrementalLoading interface to your ViewModel, then the list view will automatically detect the interface and enables the incremental loading by default. Therefore, customizing the data loading process can be intercepted from the ViewModel layer.

The ISupportIncrementalLoading interface defines the members such as shown in the following class diagram.

As the list view is scrolled near to its most bottom edge, it checks for the HasMoreItems property specified in the ViewModel. If the value is true, the LoadDataIncremental method will be invoked. You will need to handle the IsDataLoading property by setting its value to true when the data is loading asynchronously, then consequently set it to false when the data loading is finished.

The following code example shows how to implement ISupportIncrementalLoading interface in a ViewModel.

The above sample code illustrates the basic usage of the incremental loading. In the real world scenarios, the implementation must take account several parameters such as the start position of the data to load and the items count to retrieve. In dynamic view scenarios, you will also need to take account the query parameters that describe the view such as the sort and filter information. To simplify common data operations for cross-platform apps development, Crosslight provides built-in data components such as query descriptors and query definitions. 

Crosslight 2 includes Enterprise App Framework which provides data access design patterns and best practices for building enterprise mobile apps with Crosslight. It includes DataListViewModelBase class which implements the ISupportIncrementalLoading interface and provides many common data features. It is recommended that you start building your data-driven apps by deriving from the base classes available in the Enterprise App Framework. For more information, see Building Business Apps with Enterprise App Framework.

In addition to the data framework, Crosslight also provided built-in UI components on each platform to support the incremental loading feature. This means that you don't have to write an additional line-of-code, it just works. See the following topics for more information on the Crosslight incremental loader UI components:

Crosslight has provided several samples that comes with the built-in incremental loading techniques as outlined earlier. The samples that exhibit this feature is WebAPI-enabled Inventory Tracker. The Business Template that comes with the Crosslight Project Wizard also supports this feature in the "Page 3" view with ported Inventory Tracker built right into the template.

Implementing Pull-to-Refresh

To fully support various data loading scenarios, Crosslight now comes with the pull-to-refresh feature, which allows the user to refresh the data inside a list view by pulling the list view to the bottom. This page discusses how to enable pull to refresh in the view model layer. 

Built with conformance to MVVM pattern, the pull to refresh feature is automatically enabled when the ViewModel of the table view controller implements ISupportRefresh interface. This design provides the utmost flexibility for developers to control the data loading process which is also written in the ViewModel layer.

The ISupportRefresh interface defines the members such as shown in the following class diagram.

When users pull the table view to a certain extent, the user interface will show an animated loading indicator. Crosslight automatically take care the user experiences and view behaviors for pull to refresh, so you generally do not need to make additional efforts to implement these behaviors.

All you need to do is simply implementing the RefreshData method which will be called by the view component and bind the RefreshCommand in the binding provider.

In the RefreshData implementation, you set the IsDataLoading to true to indicate that the asynchronous data loading has started, then set it back to false when the data has been successfully refreshed. The view component captures the changes of the IsDataLoading property and automatically updates the user interface at the right time.

The following code example shows how to implement ISupportRefresh interface in a ViewModel.



Crosslight 2 includes Enterprise App Framework which provides data access design patterns and best practices for building enterprise mobile apps with Crosslight. It includes DataListViewModelBase class which implements the ISupportRefresh interface and provides many common data features. It is recommended that you start building your data-driven apps by deriving from the base classes available in the Enterprise App Framework. For more information, see Building Business Apps with Enterprise App Framework.

Since v2, Crosslight is shipped with UI counterparts to support the pull-to-refresh feature. To learn more about the pull-to-refresh component for platform-specific Crosslight framework, checkout the following pages: