1. Component library

AdvancedComboBox

Version:

The AdvancedComboBox control shows a drop-down list of items. When a user selects an item from the list, the AdvancedComboBox control returns the value of the selected item (as selectedValue).

You bind the AdvancedComboBox control to a data source in the Items property, and the AdvancedComboBox control shows all the items that the data source retrieves.

By default, the AdvancedComboBox control shows the display names of the items, but you can use the DisplayFieldName property of the AdvancedComboBox control to select another item field to show.

SPEAK selects the first (top) item in the AdvancedComboBox control by default. This means that the selectedItem member never returns null if the AdvancedComboBox control has any items at all.

You can set the properties of an AdvancedComboBox control in different ways. We recommend that you use the rebind function with the following syntax:

rebind (items, selectedItem, selectedValue, displayFieldName, valueFieldName)

If you provide both the selectedValue and selectedItem properties, the AdvancedComboBox control will use selectedItem.

The AdvancedComboBox control is similar to the ComboBox control, but it has these additional features:

  • The AdvancedComboBox control shows a search box in the drop-down list. Users enter search strings in this search box, and the control filters the items it shows with this string as the user is typing (incremental search).
  • If you specify a field name in the GroupFieldName property, the AdvancedComboBox control groups the items in the list by this field and shows the field name as a label for each group. You can specify a field name or a token (for example: $templateName).

Properties
NameDescriptionDefault
Appearance
WidthPolicySpecify how SPEAK interprets the width of the control. You can specify:

  • Default: the default width of the control is used.
  • BlockLevel: the width is set relative to the width of the container.
Default
Data
DisplayFieldNameSpecify the name of the item field that the AdvancedComboBox control displays.$displayName
GroupFieldNameSpecify the name of the item field that the AdvancedComboBox control uses to group items. You can enter the name of a field, or one of these tokens:

  • 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 Sitecoore 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)
ItemsYou can bind the control to a data source and the AdvancedComboBox control shows the items retrieved by this data source.itemId
SelectedItemSpecify the selected item by name.The first (top) item
SelectedValueSpecify the selected item by value (ID).
ValueFieldNameSpecify the item field that the AdvancedComboBox control uses as the option value (and returns as selectedValue).ID of the item

Configuration

You can create a configuration item for an AdvancedComboBox control by creating an item based on the AdvancedComboBox Parameters template.

The configuration item has these specific fields:

  • DisplayFieldName

It inherits these fields:

  • IsEnabled
  • IsVisible
  • AccessKey
  • Tooltip
  • Behaviors
  • Id
If you have suggestions for improving this article, let us know!