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)

You can only use $itemName, $itemTemplate, and $path for sorting

Sortable

If you select this field, the ListControl control is sortable and it displays a sorting button that users can click. This button has three states that it will cycle through when a user clicks it: no direction, ascending, and descending.

The ListControl control does not do the actual sorting: a data source component (such as the SearchDataSource component) can bind to the Sorting property to listen to the sorting direction. It is up to the data source component to use this information.

SortField

Specify the name of the index field if it is different from the content field name. If the fields do not have the same name, sorting will not work unless you specify SortField.

Formatter

Specify formatting strings. You use yy, yyyy, m, mm, d, and dd to format date values. For example: “m-d-y” formats a date as “11-23-14”, and “dd/mm/yyyy” as “02/09/2011”. Use these tokens:

  • yy and yyyy: the year as either two digits or four digits.

  • m and mm: the month without or with a leading zero when needed.

  • d and dd: the day without or with a leading zero when needed.

  • h and hh: the hour without or with a leading zero when needed.

  • m and mm: minutes without or with a leading zero when needed.

You can also specify date formatting in the data source component. If you specify formatting in the data source, it will overrule the formatting that you specify in a ColumnField Formatter field.

HTML Template

See Using an HTML template.

HeaderAlignment

Specify the alignment of the header text of the column. You can use Center, Left, and Right.

ContentAlignment

Specify the alignment of the content of the column. You can use Center, Left, and Right.

Width

Specify the width of the column in pixels or in percent of the width of the complete table.

You can format the DetailList view with an HTML template. In this way, you can control the formatting yourself and you can create hyperlinks, for example.

To specify an HTML template you must:

  • Add a configuration item based on the ColumnField template for each column you want in the table that the ListControl control creates.

  • Specify the HeaderText field but not the DataField field in these items. This is the column heading.

  • Specify a formatting string in the HTML Template field. You can insert fields from the retrieved items like this: {{<fieldname}} where fieldname is the exact name of the field in the template that the retrieved item is based on. The name is case-sensitive.

Note

You can freely use any fields from the retrieved items in each HTML template.

If the items that the ListControl control displays do not all have the same fields, it is possible that some items do not have a field you specified in the HTML template. In this case, the ListControl control outputs the field placeholder as it is (for example: {{Dimensions}}).

If, for example, the retrieved items have fields called url, _Created, Alt, image, and itemName, the following HTML template creates a hyperlink with the image and the itemName as the visible part, and the url as the destination:

<a href=”{{url}} title=”Item was created{{_Created}}”><img alt=”{{Alt}}” src=”{{image}} /> {{itemName}}</a>

You can use the TileListViewMode property to gain more control over the HTML and the CSS that the ListControl control uses to render items:

  • Set the ViewMode property to TileList.

  • Create an HTML file and specify this file in the TileHtmlFileName property. You use this file to design the HTML that the ListControl control renders.

  • Create a CSS file and specify this file in the TileCssFileName property. You use this file to style the HTML rendered by the file you specify in the TileHtmlFileName property.

There is a default TileHtmlFileName file at: /sitecore/shell/client/Business Component Library/Layouts/Renderings/ListsAndGrids/ListControls/DefaultTile.cshtml. There is no default CSS file.

You specify the item fields the ListControl control outputs with data binding, for example: data-bind="text: $displayName". The bindings use the same syntax as knockout.js does.

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.