Skip to content

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 Optional false
AllowEmptySelection boolean Optional true
AllowMultipleSelection boolean Optional
Caption string Optional
DataPaging DataPaging Optional
FilterProperty string Optional
FilterValue complex Optional
IsEditable boolean Optional true
IsPickerDismissedOnSelection boolean Optional false
IsSearchCancelledAfterSelection boolean Optional false
IsSelectedSectionEnabled boolean Optional false
IsVisible boolean Optional true
OnValueChange ActionOrRule Optional
PickerItems complex Optional
PickerPrompt string Optional
Search Search Optional
Styles object Optional
Value complex Optional
_Name string Required
_Type const Required
validationProperties ValidationProperties Optional

AllowDefaultValueIfOneItem

Enables automatic selection of default value for the List Picker if only one item is present.

  • 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.

  • type: boolean
  • default: true

AllowMultipleSelection

Disables or enables the selection of multiple entries.

  • type: boolean

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.


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"

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

OnValueChange

Action or rule to be performed after value is changed.


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.

Option 1

Option 2

Option 3

Option 4


PickerPrompt

Text to display when nothing is selected.

  • type: string


Styles

Set styles for Background, Caption and Value.

  • type: object with following properties.
Property Type Required Default
Background string Optional
Value string Optional
Caption string Optional

Background

The string value is a style class name for Background.

Value

The string value is a style class name for Value.

Caption

The string value is a style class name for Caption.


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

  • type: string

_Type

  • type: const

The value of this property must be equal to:

"Control.Type.FormCell.ListPicker"

validationProperties

The validation view properties.


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/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,
        "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,
        "validationProperties": {
          "ValidationMessage": "Validation Message",
          "ValidationMessageColor": "ff0000",
          "SeparatorBackgroundColor": "000000",
          "SeparatorIsHidden": false,
          "ValidationViewBackgroundColor": "fffa00",
          "ValidationViewIsHidden": false
        },
        "Styles": {
          "Background": "ListPickerFormCellBackground",
          "Caption": "ListPickerFormCellCaption",
          "Value": "ListPickerFormCellValue"
        }
      }]
    }]
  }]
}

Picker Items - Exmaple used in Filter Popover

{
  "_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: UIFontTextStyleBody;  /* iOS Only */
  font-typeface: bold;  /* Android Only */
  font-size: 16px;
}

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