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. If ListPicker is used in Tabs page (non modal parent page), the list page is opened as a new modal. However if the ListPicker is used in Tabs page inside a Modal page, the list page would be opened as outer navigation.

When assigning a rule to a property of ListPicker, the rule will be passed an instance of the following proxy class as an argument:

ListPickerFormCellProxy

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
PlaceHolder	`string`	No
RequiredIndicator	BooleanOrString	No	`false`
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¶

Allows the user to close the picker without selecting a value or to clear all existing selections.

iOS: If this property is set to false, the back button will be hidden, and the user must make a selection to close the picker.

Android: This behavior is not supported. The user can always deselect any previously selected value.

Web: If this property is set to false, the first item is automatically selected. This ensures that one item is always selected and cannot be deselected.

type: boolean
default: true

AllowMultipleSelection¶

Allows user to select more than one value from the list.

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 at the bottom of the picker list.

type: string

PlaceHolder¶

Text to display when the value is empty.

type: string

RequiredIndicator¶

Specifies whether a field is mandatory by displaying a visual indicator. This property accepts either a Boolean (true / false) or a single character (e.g., '!') as its value.

By default, the indicator is a red asterisk (*) displayed at the end of the field's caption. You can customize the indicator character by setting this property. Additionally, the appearance (e.g., color or size) can be styled through metadata as well.

Note:

This indicator is purely visual—it does not enforce that the user must fill out the field.
If more than one character is defined, the system will revert to using the default indicator.

type: BooleanOrString
default: false

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
RequiredIndicator	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

RequiredIndicator¶

The string value is a style class name of RequiredIndicator.

RequiredIndicatorColor 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",
        "PlaceHolder": "PlaceHolder",
        "Value": ["One"],
        "IsEditable": true,
        "HelperText": "This is helper text",
        "FilterProperty":"Priority",
        "RequiredIndicator": true,
        "Styles": {
          "Background": "ListPickerFormCellBackground",
          "Caption": "ListPickerFormCellCaption",
          "Value": "ListPickerFormCellValue",
          "RequiredIndicator": "RequiredIndicatorColor"
        }
      }]
    }]
  }]
}

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",
        "PlaceHolder": "PlaceHolder",
        "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",
        "PlaceHolder": "PlaceHolder",
        "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",
        "PlaceHolder": "PlaceHolder",
        "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",
        "PlaceHolder": "PlaceHolder",
        "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",
        "PlaceHolder": "PlaceHolder",
        "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",
        "PlaceHolder": "PlaceHolder",
        "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",
        "PlaceHolder": "PlaceHolder",
        "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",
        "PlaceHolder": "PlaceHolder",
        "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;
}

/* Required indicator's color - font-color / color can be used */
.RequiredIndicatorColor {
  font-color: blue;
}

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¶

PlaceHolder¶

RequiredIndicator¶

Search¶

Separator¶

Styles¶

Background¶

Value¶

Caption¶

RequiredIndicator¶

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¶