LinkedIn
Copied!

Dropdown control in DX API

The Dropdown control (pxDropdown) helps you display a list of options, from which a user can select a single option. Learn about the JSON structure and elements of a sample Dropdown control, to understand how you can integrate the element into your custom application.

The following JSON code is a sample API response for the Dropdown control:

{
        "validationMessages": "",
        "visible": true,
        "labelReserveSpace": true,
        "readOnly": false,
        "control": {
            "modes": [
                {
                    "charWidthUnits": "px",
                    "charWidth": "170",
                    "dataPagePrompt": "pyLocalizedValue",
                    "groupOrder": "asc",
                    "listSource": "datapage",
                    "textAlign": "Left",
                    "tooltip": "",
                    "enableGrouping": false,
                    "groupBy": "",
                    "minChars": "",
                    "dataPageParams": [
                        {
                            "name": "startsWith",
                            "value": "E"
                        }
                    ],
                    "modeType": "editable",
                    "dataPageValue": "pyFieldValue",
                    "controlFormat": "Standard",
                    "dataPageTooltip": "",
                    "loadMode": "auto",
                    "options": [
                        {
                            "value": "Ecuador",
                            "key": "ECU"
                        },
                        {
                            "value": "Egypt",
                            "key": "EGY"
                        },
                        {
                            "value": "Eritrea",
                            "key": "ERI"
                        },
                        {
                            "value": "Estonia",
                            "key": "EST"
                        },
                        {
                            "value": "Ethiopia",
                            "key": "ETH"
                        },
                        {
                            "value": "Spain",
                            "key": "ESP"
                        },
                        {
                            "value": "Western Sahara",
                            "key": "ESH"
                        }
                    ],
                    "dataPageID": "D_GetCountryCodesFiltered",
                    "maxChars": "",
                    "placeholder": "Select",
                    "formatType": "none",
                    "specifySize": "auto"
                },
                {
                    "modeType": "readOnly",
                    "autoPrepend": "",
                    "tooltip": "",
                    "showReadOnlyValidation": "true",
                    "autoAppend": "",
                    "formatType": "text",
                    "obfuscated": false
                  }
            ],
            "actionSets": [],
            "type": "pxDropdown"
        },
        "label": "DropDownDPageParam",
        "type": "Text",
        "required": false,
        "validateAs": "",
        "reference": "DropDownDPageParam",
        "labelFormat": "Standard",
        "disabled": false,
        "testID": "20190828130020010900e88dcf-3937-4e81-8750-8db91e8f526b233",
        "value": "",
        "maxLength": 256,
        "expectedLength": "",
        "fieldID": "DropDownDPageParam",
        "customAttributes": {
            "key1": "val1"
          }
    }

The following examples show a sample configuration of the control with the relevant JSON elements:

Cell properties - General tab
Cell properties - General tab
  • When rules that are part of conditions, such as VisibilityDisable, or Required, return boolean values.

  • For conditions, such as Visibility, Disable, or Required, for the Condition (when rule) option, negation with the logical operator (!) is supported. For example, !pzVisibleWhen.
  • Fields, such as Placeholder or Helper text, return the corresponding value from the associated Pega rules.
  • For conditions, such as VisibilityDisable, or Required, only the Always and Condition (when rule) options are supported.
Cell properties - General tab, continued
Cell properties - General tab, continued
  • If the list source is a data page, the response includes the following values:
    • dataPageID - The ID of the data page. To obtain the values for the list, call the GET/data/{datapageID} endpoint.
    • dataPageValue - The key of the value selected from the list of values in the data page.
    • dataPagePrompt - The visible label of the value selected from the list of values in the data page.
      See the following example of a data page as the list source:
      "control": { "modes": [{ "dataPagePrompt": "TeamName", "dataPageValue": "TeamName", "listSource": "datapage", "dataPageID": "D_GetTeams" }], "type": "pxDropdown" }
  • If the list source is prompt list or local list, the response includes the following key-value pairs:
    "control": { "modes": [{ "listSource": "promptlist", "options": [{ "value": "Critical", "key": "Critical" }, { "value": "High", "key": "High" }, { "value": "Medium", "key": "Medium" }, { "value": "Low", "key": "Low" }] }], "type": "pxDropdown" }
  • For the Type field, the Report definition option is not supported.
Cell properties - General tab, continued
Cell properties - General tab, continued

The values in the Dropdown control are represented by the control.modes[0].options: array element.

DX API attributes
DX API attributes

The response returns the name-value pairs that you add to the DX API attributes of the control as part of the customAttributes element.

Property referenced in the control - General tab
Property referenced in the control - General tab
Property referenced in the control - Advanced tab
Property referenced in the control - Advanced tab

The message in the validationMessages element is displayed when the validation in the validateAs element fails.

Cell properties - Presentation tab
Cell properties - Presentation tab
  • The Edit options field returns a boolean value.
  • The value of the Read-only value field is displayed in the value key in the JSON response.
Cell properties - Presentation tab, continued
Cell properties - Presentation tab, continued
Suggest Edit
Did you find this content helpful?

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.