Skip to main content
Version: 8.1

Perspective - Dropdown

Component Palette Icon:

Description‚Äč

The Dropdown component is a great way to display a list of choices in a limited amount of space. The current selection is shown, and the choices are presented when the user clicks on the dropdown button. There is also the capability to search for an element by typing the name of that element in the dropdown field. If the element is present, it will appear as you are typing and you can select it. If the element doesn't exist, you can define text to display that the text is not found by configuring the noResultsText property.

The choices that are displayed in the Dropdown depend on what Elements are defined in the options property of the Property Editor. The placeholder property defines what text is shown before any of the choices are selected. For example, you can have the word 'Select...' to inform the user to select any of the Elements from the dropdown list.

There is also a multiSelect property which allows the user to select multiple elements from the dropdown. Selected elements can be deleted by clicking the 'x' icon.

New in 8.1.2

The DateTime Picker component has two pre-configured variants:

  • Single Selection - Default layout that displays a list of choices of which the user can select one.
  • Multi-Selection - Layout with a list of choices of which the user can select more than one.

Properties‚Äč

Most Properties have binding options. For more information on Bindings, see Types of Bindings in Perspective. This section only documents the Props Category of properties. The other Categories are described on the Perspective Component Properties page.

NameDescriptionProperty Type
valueThe result of current selections (input) after any processing.variable, based on which item in props.options property is selected.
optionsAnd array of objects for each dropdown option.
  • value: Actual value to be matched by the input or selection.

      The type of this property is initially a Value-type, but it can be converted to an Object-type or Array-type. Doing so will populate the PROPS.value property with the entire object/array, allowing a single selection on the dropdown to return multiple values. Property type is variable.

      Note: Each option must have a unique value.
  • label: Text to display in the menu representing this option. Value is string.
  • isDisabled: Whether this option is currently disabled from selection. If set to true, option will not be selectable, and will use a grey font assuming another text color isn't being applied. Value is boolean.
  • array
    multiSelectEnable multiple selected values. Default is false.value: boolean
    placeholderSettings for the text displayed when value is empty. Click to see the placeholder properties.object
    enabledIf set to false, component is disabled. Field will not focus and dropdown will not be interactive.

    Note: If the component is disabled, scripts can still run on the component. For example, if you add a script action to the onClick event, the script will fire when the user clicks on the Dropdown.
    value: boolean
    searchEnter text to start search.
  • enabled: Whether options are searchable by typing text into the field. Default is true. Value is boolean.
  • matching: Whether search string must match from the start or may match any position of an option: start or any. Value is string.
  • noResultsText: Text to display in dropdown when no option matches the search. Default is "No results found." Value is string.
  • searchParam: The text being searched for. Value is string.
  • object
    showClearIconWhether to display a button that the user can use to clear the selection. Default is false.value: boolean
    allowCustomOptionsWhether a user may enter a custom value to be submitted. Default is false.

    While set to True, typing a value that doesn't match one of the existing options from the session will provide the user with a "Create" option. Selecting the Create option will set props.value to the new option. Creating a custom option in this way does not change the value of props.options. The custom option is simply a means to allow the user to type a custom value into the component.
    value: boolean
    textAlign
    New in 8.1.19
    Aligns the value(s) and/or placeholder text displayed within the dropdown. Valid values are left, center, and right. textAlign within the dropdown modal itself may be overriden or set separately using props.dropdownOptionStyle.textAlign.
    value: string
    minMenuHeight
    New in 8.1.29
    Minimum height of the dropdown menu. If the minimum height is not available under the component, and space is available above the component, the dropdown will flip to display options above the component. Default value is 150.
    value: numeric
    maxMenuHeight
    New in 8.1.29
    Maximum height of the dropdown menu before it becomes scrollable. Default value is 350.
    value: numeric
    styleSets a style for this component. Full menu of style options is available for text, background, margin and padding, border, shape and miscellaneous. You can also specify a style class.object
    dropdownOptionStyleSets a style for the dropdown options. Full menu of style options is available for text, background, margin and padding, border, shape and miscellaneous. You can also specify a style class.object

    placeholder Properties‚Äč

    NameDescriptionProperty Type
    textPrompt text to display when no options are selected.value: string
    colorColor of placeholder text. Can be chosen from color wheel, chosen from color palette, or entered as RGB or HSL value. See Color Selector.color
    iconSettings for an icon used as a placeholder.
  • path: Shorthand path to the icon source. Format is library/iconName. The materials icon library is a the primary source for icons, see https://fonts.google.com/icons?selected=Material+Icons. Value is string.
  • color: Color of the placeholder icon, if it exists. Can be chosen from color wheel, chosen from color palette, or entered as RGB or HSL value. See Color Selector.
  • style: Sets a style for this component. Full menu of style options is available for text, background, margin and padding, border, shape and miscellaneous. Three additional available settings are as follows:
    • margin: Margin around the icon, in pixels. Default is 0px 8px -3px 0px. Value is numeric.
    • width: Width of the icon in pixels. Default is 16px. Value is numeric.
    • height: Height of the icon in pixels. Default is 16px. Value is numeric.
    object

    Component Events‚Äč

    The Perspective Event Types Reference page describes all the possible component event types for Perspective components. Not all component events support each Perspective component. The Component Events and Actions page shows how to configure events and actions on a Perspective component. Component scripting is handled separately and can be accessed from the Component menubar or by right clicking on the component.

    Examples‚Äč

    Example 1‚Äč

    PropertyValue
    props.options.0.value[default]Dairy/Bldg25/valve1
    props.options.0.labelValve 1
    props.options.1.value[default]Dairy/Bldg25/valve2
    props.options.1.labelValve 2
    props.options.2.value[default]Dairy/Bldg25/valve3
    props.options.2.labelValve 3
    props.options.3.value[default]Dairy/Bldg25/valve4
    props.options.3.labelValve 4
    props.placeholder.textSelect a Valve...
    props.placeholder.color#0000AC
    props.placeholder.icon.pathmaterial/grade
    props.placeholder.icon.color#008000
    props.style.borderStylesolid
    props.style.color#0000D9
    props.style.fontFamilygaramound
    props.style.fontSize16px
    props.style.fontWeightbold
    props.style.borderWidth2px
    props.style.borderColor#008000
    props.style.borderRadius8px
    props.dropdownOptionStyle.color#008000
    props.dropdownOptionStyle.fontSize14px
    props.dropdownOptionStyle.fontWeightbold
    props.dropdownOptionStyle.textAlignright

    Example 2‚Äč

    In this example, we have a dropdown list with an expression binding on the options property. There is also a label on the view with the word "Email" as its text.

    A default email address of j_smith@companyname.com is set as the starting value for the component.

    As the user starts entering characters for an email address, the dropdown list provides typeahead options of the entered text plus three possible email options, @'cn.com', '@companyname.com', or '@gmail.com'.

    PropertyValue
    valuej_smith@companyname.com
    options(Bound to an expression. See example below.)
    props.search.enabledtrue
    transform code
    # suggest auto-completed options for an email address
    options = []
    # skip if blank
    if value:
    # check for @ symbol and suggest email address if not present
    if "@" not in value:
    options.append({ "value":value+"@cn.com", "label":value+"@cn.com"})
    options.append({ "value":value+"@gmail.com", "label":value+"@gmail.com"})
    options.append({ "value":value+"@companyname.com", "label":value+"@companyname.com"})
    # check for extension (.com) and suggest extensions if not present
    elif ".com" not in value and ".net" not in value and ".org" not in value:
    options.append({ "value":value+".com", "label":value+".com"})
    options.append({ "value":value+".net", "label":value+".net"})
    options.append({ "value":value+".org", "label":value+".org"})
    # return a list of suggested options
    return options