Walkthrough: Customize the ListControl

Abstract

This topics shows how to set up the SPEAK ListContro.l.

For a ListControl to display any content and not just gray boxes, you need to customize it.

This walkthrough outlines how to:

  • Set the ViewMode property

  • Define columns

  • Specify how the control gets data

  • Enable sortable columns

Note that the ListControl has many properties and that you can customize many different things. This topic gives enough information to get you started, but you can find more details in the SPEAK Component Reference.

You use the ViewMode property to specify how the ListControl shows item.

  • In the ListControl property sheet, select one of the three values in the ViewMode property.

    • To display content in a table format, click DetailList.

    • To display content as a grid of images and associated titles, click IconList,

    • To format your content freely, select TileList.

If you select DetailList, the ListControl shows your content in a table with rows and columns:

9A844D9A4156433C8CD0809400F4DBB8.png

You can gain more control over the way the ListControl displays each item in the DetailList mode by using an HTML Template.

If you select IconList, the ListControl shows content as a grid of images and associated titles:

E48C455CE6D2437796E4CC8EC903C0E5.png

If you select TileList, you can format the content quite freely. When you use DetailList, you can use HTML Templates to format the content given the limitations of the table format, but when you use TileList, you provide an HTML file with placeholders and (optionally) a CSS file. You are not bound to a strict tabular format.

You can change the ViewMode programmatically, for example in the Click event of a button. You use this when have content that can appear in different ViewModes, and you want users to be able to change the ViewMode setting.

When you use the DetailList ViewMode, you have to specify the fields that the ListControl shows as columns (the "column fields"). The ListControl does not show any content if you do not specify the column fields.

To define your column fields:

  1. Create a configuration item based on the ListControl template.

  2. Copy the Sitecore ID of this configuration item to the DataSource property of the ListControl.

  3. For each of your columns, create a configuration item based on the ColumnField template. You create these items as children of the ListControl configuration item.

  4. In each of the column field items, specify the following:

    • A Header Text – the ListControl shows this as the column heading.

    • The field name of the data that the column displays. You must specify the field name exactly as it appears in the template for the items shown in the ListControl.

The ListControl only shows items.

To tell the ListControl how it gets data:

  • Specify the items the ListControl shows in the Items property

A common pattern is to bind the Items property of the ListControl to the Items property of a data source component, such as the SearchDataSource component. The ListControl automatically shows the items that the SearchDataSource retrieves.

The ListControl does not retrieve, filter, or sort data. Most of this setup is in the data source component. The ListControl can communicate to the data source how the data source should sort data.

You enable sorting by making one or more columns sortable and setting up sorting in the data source that provides the items:

  1. In the column field items, for each column field item that you want users to be able to sort on, select the Sortable field.

  2. Bind the Sorting property of the data source to the Sorting property of the ListControl.

The ListControl lets users sort on the columns where you have enabled sorting. When users change the sort order, the data source updates immediately because of this binding.