ListPicker¶

A list picker allows the selection of one or more options among values within a defined category.

If ObjectCell is used in PickerItems, then the Title property is required (to dispaly value in listpicker form cell and search), and the following properties / events are not supported: AccessoryType, ProgressIndicator, OnPress, OnAccessoryButtonPress.

ListPicker Properties¶

Property	Type	Required	Default
AllowDefaultValueIfOneItem	`boolean`	No	`false`
AllowEmptySelection	`boolean`	No	`true`
AllowMultipleSelection	`boolean`	No	`true`
Caption	`string`	No
DataPaging	DataPaging	No
FilterProperty	`string`	No
FilterValue	complex	No
HelperText	`string`	No
IsEditable	`boolean`	No	`true`
IsPickerDismissedOnSelection	`boolean`	No	`false`
IsSearchCancelledAfterSelection	`boolean`	No	`false`
IsSelectedSectionEnabled	`boolean`	No	`false`
IsVisible	`boolean`	No	`true`
Label	`string`	No
OnValueChange	ActionOrRule	No
PickerItems	complex	No
PickerPrompt	`string`	No
Search	Search	No
Separator	`boolean`	No	`true`
Styles	`object`	No
Validation	Validation	No
Value	complex	No
_Name	`string`	Yes
_Type	`const`	Yes
validationProperties	ValidationProperties	No

AllowDefaultValueIfOneItem¶

Enables automatic selection of default value for the List Picker if only one item is present. If AllowDefaultValueIfOneItem is true, the List Picker OnValueChange event will be triggered when the default value is selected automatically.

type: boolean
default: false

AllowEmptySelection¶

Disables or enables the selection of empty value set.

In Android, this is not supported. Empty selection is always possible on List Pickers that AllowMultipleSelection and never possible otherwise. Please avoid to set this property as false if you intend to use FilterFeedbackBar as well.

In iOS, the back button will be hidden if this property is set to false, and it will only become visible when an item is selected.

In Web, setting this property to false automatically selects the first item, ensuring one item is always selected and cannot be deselected.

type: boolean
default: true

AllowMultipleSelection¶

Disables or enables the selection of multiple entries. Please avoid to set this property as false if you intend to use FilterFeedbackBar as well.

type: boolean
default: true

Caption¶

Displays label on the control.

type: string

DataPaging¶

Configure the loading indicator shown at the end of the list, when loading next page of data.

type: DataPaging

FilterProperty¶

The name of the property for filter on. This property only has effect when the List Picker is used in a Filter page (see Filter Action for details).

In a Filter Page, every ListPicker or Filter must have a unique FilterProperty.

type: string

FilterValue¶

This is a read-only property. This property is only valid when the List Picker is used in a Filter page, and should be only used in TargetPath to retrieve filter value. See example below on how to read this property via TargetPath.

type: complex

FilterValue Example¶

"#Page:ProductFilterPage/#Control:CategoryListPicker/#FilterValue"

HelperText¶

Helper text to be displayed if there is no validation view.

type: string

IsEditable¶

Disables or enables interaction.

type: boolean
default: true

IsPickerDismissedOnSelection¶

Enables automatic dismission of lisk view after selecting an entry of the list.

This only takes effect when AllowMultipleSelection is false. Otherwise, automatic dismission of list view is not enabled.

type: boolean
default: false

IsSearchCancelledAfterSelection¶

Enables the List Picker to exit the search mode automatically after users select/deselect an item under search mode.

This property only takes effect when AllowMultipleSelection is false.

When IsPickerDismissedOnSelection is true, the automatic dismission of list view overrides the effect of exiting the search mode.

type: boolean
default: false

IsSelectedSectionEnabled¶

Enables the section containing the selected entries at the top of the list.

In Android, this is only supported on List Pickers that AllowMultipleSelection. Otherwise, the selected section is never displayed.

type: boolean
default: false

IsVisible¶

Sets the visibility of the control.

type: boolean
default: true

Label¶

Displays label when being displayed as selected item on filter feedback bar.

type: string

OnValueChange¶

Action or rule to be performed after value is changed.

type: ActionOrRule
Formatter and Binding are not supported

PickerItems¶

An array of items for this picker. It can be simple key and value items or Object Cell items.

type: complex

PickerItems Value¶

Any following options needs to be fulfilled.

PickerPrompt¶

Text to display when nothing is selected.

type: string

Search¶

type: Search

Separator¶

Sets the visibility of the separator line below the control. This property will take precedence over the ControlSeparator in section, only supported for Form Cell control in Sectioned Table and not supported in Form Cell Container.

type: boolean
default: true

Styles¶

Set styles for Background, Caption and Value.

type: object with following properties.

Property	Type	Required
Background	string	No
Value	string	No
Caption	string	No

Background¶

The string value is a style class name of Background.

Background style class

Value¶

The string value is a style class name of Value.

Value style class

Caption¶

The string value is a style class name of Caption.

Caption style class

Validation¶

The validation view properties.

type: Validation

Value¶

When not specified or not found in the PickerItems no selection is made. An array of the above values can be used to specify multiple selection.

type: complex

Value Value¶

Any following options needs to be fulfilled.

Option 1¶

string

Option 2¶

Array type:

All items must be of the type: string

_Name¶

The _Name value will also function as CustomQueryGroup to match with FastFilters in FilterFeedbackBar.

type: string

_Type¶

type: const

The value of this property must be:

"Control.Type.FormCell.ListPicker"

validationProperties¶

Deprecated. Please use Validation property. The validation view properties.

type: ValidationProperties

Targeting Items in a List¶

The following target paths can be evaluated from a page which has a list picker control with name "ListPicker".

#Control:ListPicker/#Value/#First -> Returns the first item in the control.
#Control:ListPicker/#Value/#Last -> Returns the last item in the control.
#Control:ListPicker/#Value/5 -> Returns the 5th item in the control.
#Control:ListPicker/#Value/5/BindingObject -> Returns the BindingObject property from the 5th item in the control if the ListPicker is bound to an EntitySet, which contains the full binding object.
#Control:ListPicker/#Value/5/DisplayValue -> Returns the DisplayValue property from the 5th item in the control.
#Control:ListPicker/#SelectedTarget -> Returns the data associated with the currently selected list item.
#Control:ListPicker/#SelectedRow -> Returns the currently selected rows index.
#Control:ListPicker/#SelectedValue -> Returns the selected value (ReturnValue) associated with the currently selected item from the ListPicker control.

Examples¶

Picker Items - Literal¶

{
  "_Type": "Page",
  "_Name": "FormCellsPage",
  "Value": "FormCell Example",
  "Controls": [{
    "_Type": "Control.Type.FormCellContainer",
    "_Name": "FormCellContainer",
    "Sections": [{
      "Caption": "Section1",
      "Controls": [{
        "_Type": "Control.Type.FormCell.ListPicker",
        "_Name": "ListPickerFormCell",
        "AllowMultipleSelection": false,
        "IsSelectedSectionEnabled": true,
        "AllowEmptySelection": true,
        "Caption": "Picker",
        "PickerItems": ["One", "Two", "Three"],
        "PickerPrompt": "Picker",
        "Value": ["One"],
        "IsEditable": true,
        "HelperText": "This is helper text",
        "FilterProperty":"Priority"
      }]
    }]
  }]
}

Picker Items - Binding¶

{
  "_Type": "Page",
  "_Name": "FormCellsPage",
  "Value": "FormCell Example",
  "Controls": [{
    "_Type": "Control.Type.FormCellContainer",
    "_Name": "FormCellContainer",
    "Sections": [{
      "Caption": "Section1",
      "Controls": [{
        "_Type": "Control.Type.FormCell.ListPicker",
        "_Name": "ListPickerFormCell",
        "AllowMultipleSelection": false,
        "Caption": "Picker",
        "PickerItems": {
          "DisplayValue": "{EquipmentDesc}",
          "ReturnValue": "{EquipmentId}",
          "Target": {
            "EntitySet": "WOHeaders",
            "Service": "/MDKApp/Services/Amw.service"
          },
         "IsEditable": true
        },
        "PickerPrompt": "Picker",
        "Value": "/MDKApp/Rules/PickerSelection.js"
      }]
    }]
  }]
}

Picker Items - Global¶

{
  "_Type": "Page",
  "_Name": "FormCellsPage",
  "Value": "FormCell Example",
  "Controls": [{
    "_Type": "Control.Type.FormCellContainer",
    "_Name": "FormCellContainer",
    "Sections": [{
      "Caption": "Section1",
      "Controls": [{
        "_Type": "Control.Type.FormCell.ListPicker",
        "_Name": "ListPickerFormCell",
        "AllowMultipleSelection": false,
        "Caption": "Picker",
        "PickerItems": "/MDKApp/Globals/OneTwoThree.global",
        "PickerPrompt": "Picker",
        "Value": "/MDKApp/Globals/One.global",
        "IsEditable": true
      }]
    }]
  }]
}

Picker Items - Rule¶

{
  "_Type": "Page",
  "_Name": "FormCellsPage",
  "Value": "FormCell Example",
  "Controls": [{
    "_Type": "Control.Type.FormCellContainer",
    "_Name": "FormCellContainer",
    "Sections": [{
      "Caption": "Section1",
      "Controls": [{
        "_Type": "Control.Type.FormCell.ListPicker",
        "_Name": "ListPickerFormCell",
        "AllowMultipleSelection": false,
        "Caption": "Picker",
        "PickerItems": "/MDKApp/Rules/OneTwoThree.js",
        "PickerPrompt": "Picker",
        "Value": "/MDKApp/Rules/One.js",
        "IsEditable": true
      }]
    }]
  }]
}

Picker Items - ObjectCell Binding¶

{
  "_Type": "Page",
  "_Name": "FormCellsPage",
  "Value": "FormCell Example",
  "Controls": [{
    "_Type": "Control.Type.FormCellContainer",
    "_Name": "FormCellContainer",
    "Sections": [{
      "Caption": "Section1",
      "Controls": [{
        "_Type": "Control.Type.FormCell.ListPicker",
        "_Name": "ListPickerFormCell",
        "AllowMultipleSelection": false,
        "Caption": "Picker",
        "PickerItems": {
          "ObjectCell": {
            "Title": "{OrderDescription}",
            "Subhead": "{OrderId}",
            "DetailImage": "/MDKApp/Images/workorder.png",
            "Icons": [
              "/MDKApp/Images/icon_severity_medium.png",
              "/MDKApp/Images/open.png"
            ],
            "StatusImage": "/MDKApp/Images/workorder_details.png"
          },
          "ReturnValue": "{OrderId}",
          "Target": {
            "EntitySet": "MyWorkOrderHeaders",
            "Service": "/MDKApp/Services/Amw.service",
            "QueryOptions": "$expand=Operations&$orderby=OrderId"
          },
         "IsEditable": true
        },
        "PickerPrompt": "Picker",
        "Value": "/MDKApp/Rules/PickerSelection.js"
      }]
    }]
  }]
}

Picker Items - ObjectCell Literal¶

{
  "_Type": "Page",
  "_Name": "FormCellsPage",
  "Value": "FormCell Example",
  "Controls": [{
    "_Type": "Control.Type.FormCellContainer",
    "_Name": "FormCellContainer",
    "Sections": [{
      "Caption": "Section1",
      "Controls": [{
        "_Type": "Control.Type.FormCell.ListPicker",
        "_Name": "ListPickerFormCell",
        "AllowMultipleSelection": false,
        "IsSelectedSectionEnabled": true,
        "AllowEmptySelection": true,
        "Caption": "Picker",
        "PickerItems": [
          {
            "ObjectCell": {
              "Title": "Distance",
              "Subhead": "Distance Unit",
              "Description": "Distance Description",
              "DetailImage": "/MDKApp/Images/workorder.png",
              "Icons": [
                  "/MDKApp/Images/icon_severity_medium.png",
                  "/MDKApp/Images/open.png"
              ],
              "StatusImage": "/MDKApp/Images/workorder_details.png"
            },
            "ReturnValue": "Distance"
          },
          {
            "ObjectCell": {
              "Title": "Touch ID",
              "Subhead": "Touch ID & Passcode",
              "Description": "Touch ID Description",
              "DetailImage": "/MDKApp/Images/icon.png",
              "Icons": [
                  "/MDKApp/Images/icon_severity_medium.png",
                  "/MDKApp/Images/open.png"
              ],
              "StatusImage": "/MDKApp/Images/workorder_details.png"
            },
            "ReturnValue": "Touch ID"
          }
        ],
        "PickerPrompt": "Picker",
        "Value": ["Distance"],
        "IsEditable": true
      }]
    }]
  }]
}

Validation¶

{
  "_Type": "Page",
  "_Name": "FormCellsPage",
  "Value": "FormCell Example",
  "Controls": [{
    "_Type": "Control.Type.FormCellContainer",
    "_Name": "FormCellContainer",
    "Sections": [{
      "Caption": "Section1",
      "Controls": [{
        "_Type": "Control.Type.FormCell.ListPicker",
        "_Name": "ListPickerFormCell",
        "AllowMultipleSelection": false,
        "Caption": "Picker",
        "PickerItems": [
          "One",
          "Two",
          "Three"
        ],
        "PickerPrompt": "Picker",
        "Value": [
          "One"
        ],
        "IsEditable": true,
        "Validation": {
          "Message": "This is validation view message",
          "Visible": true,
          "SeparatorVisible": true,
          "Styles": {
            "Message": "ValidationMessage",
            "ValidationView": "ValidationView"
          }
        },
        "Styles": {
          "Background": "ListPickerFormCellBackground",
          "Caption": "ListPickerFormCellCaption",
          "Value": "ListPickerFormCellValue"
        }
      }]
    }]
  }]
}

{
  "_Type": "Page",
  "_Name": "FilterPage",
  "Value": "Filter Page with ListPicker Example",
  "Result": [
    "{#Page:FilterPage/#Control:PriorityFilter/#FilterValue}"
  ],
  "Controls": [{
    "_Type": "Control.Type.FormCellContainer",
    "_Name": "FormCellContainer",
    "Sections": [{
      "Caption": "Filter",
      "Controls": [{
        "_Type": "Control.Type.FormCell.ListPicker",
        "_Name": "PriorityFilter",
        "AllowMultipleSelection": false,
        "IsSelectedSectionEnabled": true,
        "AllowEmptySelection": true,
        "Caption": "By Priority",
        "PickerItems": [{
          "DisplayValue": "Low",
          "ReturnValue": "1"
         },
         {
           "DisplayValue": "Medium",
          "ReturnValue": "2"
         },
         {
          "DisplayValue": "High",
          "ReturnValue": "3"
         }],
        "PickerPrompt": "Picker",
        "Value": ["One"],
        "IsEditable": true,
        "FilterProperty": "Priority"
      }]
    }]
  }]
}

List Picker - Allow Default Value when One item is present¶

{
  "_Type": "Page",
  "_Name": "FilterPage",
  "Value": "Filter Page with ListPicker Example",
  "Result": [
    "{#Page:FilterPage/#Control:PriorityFilter/#FilterValue}"
  ],
  "Controls": [{
    "_Type": "Control.Type.FormCellContainer",
    "_Name": "FormCellContainer",
    "Sections": [{
      "Caption": "Filter",
      "Controls": [{
        "_Type": "Control.Type.FormCell.ListPicker",
        "_Name": "PriorityFilter",
        "IsSelectedSectionEnabled": true,
        "AllowEmptySelection": true,
        "AllowDefaultValueIfOneItem": true,
        "Caption": "By Priority",
        "PickerItems": [{
          "DisplayValue": "Low",
          "ReturnValue": "1"
         }],
        "PickerPrompt": "Picker",
        "IsEditable": true,
        "FilterProperty": "Priority"
      }]
    }]
  }]
}

Style Classes Definition¶

/* ListPicker Form Cell - Background */
.ListPickerFormCellBackground {
  background-color: yellow;
}

/* ListPicker Form Cell - Caption */
.ListPickerFormCellCaption {
  background-color: #0000FF;
  color: black;
  font-style: body;  /* iOS Only */
  font-typeface: bold;  /* Android Only */
  font-size: 16px;
}

/* ListPicker Form Cell - Value */
.ListPickerFormCellValue {
  background-color: #0000FF;
  color: black;
  font-style: body;  /* iOS Only */
  font-typeface: bold;  /* Android Only */
  font-size: 16px;
}

/* Validation view */
.ValidationView {
  background-color: #83AF9B;
  border-top-color: #ff00ee;
}

/* Validation message */
.ValidationMessage {
  font-size: 16;
  font-color: #0000ff;
}

ListPicker¶

ListPicker Properties¶

AllowDefaultValueIfOneItem¶

AllowEmptySelection¶

AllowMultipleSelection¶

Caption¶

DataPaging¶

FilterProperty¶

FilterValue¶

FilterValue Example¶

HelperText¶

IsEditable¶

IsPickerDismissedOnSelection¶

IsSearchCancelledAfterSelection¶

IsSelectedSectionEnabled¶

IsVisible¶

Label¶

OnValueChange¶

PickerItems¶

PickerItems Value¶

Option 1¶

Option 2¶

Option 3¶

Option 4¶

PickerPrompt¶

Search¶

Separator¶

Styles¶

Background¶

Value¶

Caption¶

Validation¶

Value¶

Value Value¶

Option 1¶

Option 2¶

_Name¶

_Type¶

validationProperties¶

Targeting Items in a List¶

Examples¶

Picker Items - Literal¶

Picker Items - Binding¶

Picker Items - Global¶

Picker Items - Rule¶

Picker Items - ObjectCell Binding¶

Picker Items - ObjectCell Literal¶

Validation¶

Picker Items - Example used in Filter Popover¶

List Picker - Allow Default Value when One item is present¶

Style Classes Definition¶