# ListControl

Abstract

This topic describes how to use the ListControl component in SPEAK.

A ListControl control displays items. It does not contain any data itself, and it does not retrieve any items. You must use data binding to provide the items that the ListControl control shows. Typically, you bind a ListControl control to a data source component, such as the SearchDataSource component, in the Items property of the ListControl control.

A ListControl control represents items as icons (when you set the ViewMode property to Icon) or text in rows and columns (when you set the ViewMode property to DetailList). The DataSource property points to a configuration item that specifies which fields to show in the columns for the DetailList view mode.

The ListControl control displays all the items that the data source provides. Data source components, such as the SearchDataSource component, provide support for server-side pagination and infinite scrolling.

### Note

If you create your own data source and use it with the ListControl control, it is important that there is a field called itemId in the items this data source provides, and that the value of this field is unique in each item. This is necessary for, among other things, the MultiSelectList behavior.

Name

Description

Default

Appearance

AllowMultipleColumnSorting

If false, users can only sort the ListControl control columns one at a time. When the ListControl control sorts a column, it sets the other columns to the “unsorted” state.

True

Behaviors

The ListControl control supports a number of behaviors: EndlessPageScroll, MultiSelectList, and Scrollbar.

Height

Specify the height of the control in pixels.

None.

IconViewDisplayFieldName

Specify the text the control displays in IconList ViewMode.

$displayName IsActiveResizeEnabled If true, the ListControl control resizes columns dynamically when a user drags the border of a column. If false, the control resizes columns when a user stops dragging the border of the column. The control shows the position where it will place the border while the user is dragging. False. IsEndlessScrollEnabled If true, the ListControl control scrolls endlessly. See the ScrollMoreData event. False. MaxHeight Specify the maximum value of the Height property. MaxIconSize Set a maximum size of icons that the ListControl control uses for icons in IconView ViewMode. Specify the size in pixels. MinHeight Specify the minimum value of the Height property. Sorting You can bind a data source that can sort data (such as the SearchDataSource component) to ListControl.Sorting. When a user changes the sorting direction, the ListControl control notifies the data source. You can read and write the value of the Sorting property from JavaScript. The ListControl control uses this convention for the three distinct sorting values: • “a”+fieldname: ascending sort • “d”+fieldname: descending sort • empty: no sort direction You can set the sorting direction like this: javascript:app.ListControl1.set("sorting","aitemName");  If you specify more than one sortable field, the sorting value is a pipe-separated list of the sorting values. TileCssFileName Specify the name of the CSS stylesheet the ListControl control uses in TileList mode. TileHtmlFileName Specify the name of the HTML file the ListControl control uses in TileList mode. /sitecore/shell/client/Business Component Library/Layouts/Renderings/ListsAndGrids/ListControls/DefaultTile.cshtml ViewMode Specifies how the ListControl control displays items: • IconList – displays icons if items do not have Thumbnail fields and displays thumbnails for items that do have Thumbnail fields. • DetailList – displays the columns that you have set up in a configuration. • TileList – see Using the TileListViewMode property. DetailList. Data HasSelectedItem If this read-only property is true, one of the items the ListControl control displays is selected. SelectedItemId Sets or gets the ID of the currently selected item. You do not normally set the value because the control updates the value when the user makes a selection. Data bindings Items Points to the items that the control displays. You can use the drop-down list to select a binding to another control. You typically select a binding to the item property of a data source component. ### Note If you create your own data source, it is important that there is a field called itemId in the items that this data source provides. Events ScrollMoreData Specify the JavaScript that the control executes when IsEndlessScrollEnabled is true and the user scrolls to the end of the currently available data. You can, for example, specify “next:Datasource1” to tell the ListControl control to ask Datasource1 for the next page of data. State IsStateDiscarded If true, column widths that are set by a user are discarded and the widths are the same every time the page loads. False You can create a configuration item for a ListControl control by creating an item based on the ListControl Parameters template. The configuration item has these specific fields: • Value • ViewMode • Height • Sorting • Items • SelectedItemId It inherits these fields: • IsVisible • AccessKey • Tooltip • Behaviors • Id You specify some of the functionality of a ListControl control in a configuration item. This configuration is necessary if you use the DetailList view mode. To specify the configurations: • Add an item based on the ListControl template as a child of the PageSettings item. • Add an item based on the ColumnField template as a child of the item you just added, for each column of data you want to display. You do not have to edit anything in the item based on the ListControl template. The ColumnField template has these fields: Field Description HeaderText Specify a column heading. The control uses this in DetailList mode. DataField Specify the name of a data field for this column. Enter the name exactly as it is in the template of the items that you want the ListControl control to show. You can also use one of the following tokens instead of a data field: • itemId (the item ID) • itemName (the item name) •$displayName (the display name)

• $database (name of the database the item belongs to) •$language (the language of the item)

• $version (the version of the item) •$templateName (the name of the template the item is based on)

• $templateId(the item ID of this template) •$hasChildren (shows whether the item has child items or not)

• $path (the Sitecore path of the item) •$url (the Sitecore URL of the item)

• $mediaurl (the Sitecore URL of the icon asset of the item) •$icon (the Sitecore path of the icon of the item)

### Note

Links ("clickable URLs") in a tile do not work by default. You can use JavaScript to make such links work: subscribe to the click event, and implement the expected behavior. For example, you can extract the URL and set the window.location.href property.