SPEAK

MultiSelectList

Abstract

This topic describes how to use the MultiSelectList behavior in SPEAK.

The MultiSelectList component is a behavior. This means that the component does not do anything by itself. Instead, it adds capabilities to another component.

The MultiSelectList component is only a relevant behavior for the ListControl control. You use the MultiSelectList behavior by adding a MultiSelectList component to your page, and adding MultiSelectList to the list of behaviors in the Behaviors property of the ListControl control.

The MultiSelectList behavior makes it possible for users to select multiple items in a ListControl control.

The MultiSelectList behavior extends the ListControl control with two properties:

  • checkedItems - contains an array of the raw objects that the user has checked.

  • checkedItemIds - contains an array of the IDs of the items that the user has checked.

Note

You must add the MultiSelectList component to the main page of your application – even if the ListControl control you want to add the behavior to is on a subpage.

It does not matter what the ID of the MultiSelectList control is – you always enter MultiSelectList as the name of behavior.

You only need one MultiSelectList component for a page – even if you have multiple ListControl controls.

The MultiSelectList behavior also extends the ListControl control with eight methods. You use these methods to control how and when items are checked and unchecked when the default functionality is not enough for your requirements.

The methods and their arguments are:

  • checkItem(item)

  • checkItem(itemId)

  • checkItems(array of items)

  • checkItems(array of itemIds)

  • uncheckItem(item)

  • uncheckItem(itemId)

  • uncheckItems(array of items)

  • uncheckItems(array of itemIds)

Usage

You use the MultiSelectList behavior as follows:

ListControl.viewModel.checkItem("{EB443C0B-F923-409E-85F3-E7893C8C30C2}")

When you call the checkItem() method like this, the MultiSelectList behavior:

  • adds the ID of the specified item to the checkedItemIds array, and

  • if ListControl contains a row for the specified item, then it adds this item to the checkedItems array and marks the row as checked.

The MultiSelectList behavior scans the checkedItemIds array when a new row is added to the ListControl control, and it marks the appropriate rows as checked. It also updates the checkedItems array.

This means that the checkedItemIds array contains IDs of items that have been requested to be checked, and the checkedItems array refers to items that are actually checked and displayed in the ListControl control.