Comment on page

Dropdown Menu

A dropdown menu is a static list of items that appears whenever a piece of text or a button is clicked. This is a graphical approach presented to users from which they can choose one or several values from the list presented.
A dropdown menu is also known as a pull-down menu, pull-down list, dropdown list or dropdown box.
The dropdown menu is represented by the <select> tag which provides a menu of <options>.
Each <option> element should have a value attribute containing the data value to submit to the server when that option is selected; You can also include a selected attribute on an <option> element to make it selected by default when the page first loads.
Attributes
Attribute
Type
Required?
Description
name
String
Yes
Required attribute of the <select> tag. It identifies the dropdown menu.
required
Boolean
No
Optional attribute of the <select> tag. it is a Boolean attribute indicating that an option with a non-empty string value must be selected.
value
String
Yes
Required attribute of the <option> tag. It contains the data value to submit to the server when that option is selected.
selected
Boolean
Optional
You can include a selected attribute on an <option> element to make it selected by default when the page first loads. Accepted values: true and false.
data-placeholder
String
Optional
Text displayed in the dropdown menu before an option is selected. It can be a short hint or a title for the dropdown menu.
title
It accepts a simple text and \n for line breaks
Optional
The description that will be displayed when clicking the tooltip icon located on top of the Masked Text Field Element. Max length: 256 characters.
label
String
Not required but it is recommended if title is defined
Definition of the label that will be displayed on top of the Masked Text Field Element.
multiple
String
Boolean
Optional
Default is false
Allows users to select multiple values and the developer to send dropdown with multiple preselected options.
min
String
Integer ≥ 2 and ≤ max attribute
Optional
Can be used only if multiple attribute is set to true
Minimum number of options to be selected by the Symphony user.

NB: If undefined, no minimum option needs to be selected. Please use required attribute if you want to set min to 1.
max
String
Integer ≥ 2
Optional
Can be used only if multiple attribute is set to true
Maximum number of options to be selected by the Symphony user.

NB: If undefined, user will be able to select as many options as wished. Please use multiple attribute set to false if you want to set max to 1.
auto-submit
Boolean
Optional
Default is false
When enabled, selecting a value will submit the form.
Rules and Limitations
The <select> tag:
The <select> tag stands for our dropdown parent tag, which has <options> as its children; one for each select.
Select tags only accept <option> tags as children. The <select> tag must contain at least one <option> tag.
The only valid attributes of the <select> tag are name and required.
Note that, by default, Symphony users will only be able to select one option from the dropdown menu. However, using the attribute multiple set to true together with min and max attributes, users will be able to select several options from the dropdown. Please see below the examples to know how to use these attributes.
The <option> tag:
The <option> tag cannot have other <option> tags as children. The only valid child of a <option> tag is a text node, which specifies the text that will be displayed for that option inside the dropdown menu. The text node is also required.
The only valid attributes of the <option> tag are value and selected.
Only one <option> of a given select can have the attribute selected as true.
If neither the selected or data-placeholder attributes are set, the default text (title) of the dropdown menu will be "Dropdown".
Message Size Limit:
When designing forms with dropdowns within it be aware that there is a chance of reach the characters limit if too many dropdown options are included in the message. For more information about message size limits, refer to MessageML.
Examples
The following examples show dropdown menus being used as follows:
The first dropdown (init) shows how to display a default preselected option ("opt2": "With selected option"). Note that the preselected option is sent to the payload when submitting the form.
The second dropdown (data-placeholder) shows how a placeholder text ("Only data-placeholder") is displayed in the UI. Please note the placeholder text is not sent in the payload if no option from the dropdown menu has been selected by the enduser.
The third dropdown (noreq) shows how a user can interact with a non-required field. Even no option is selected by the user, it does not prevent the enduser from submitting the form.
The fourth dropdown (req) shows the behaviour of the unique required field of the form, which cannot be submitted in case no option from the dropdown menu is selected by the user; an error is displayed under the field in case the user submits the form with this empty field.
The fifth dropdown (label) shows how a label text ("My Label") is displayed.
The sixth dropdown (tooltip) shows how a title text ("My Tooltip/n With a second line") is inserted in the UI under the (i) icon, and how the text entered in the title parameter is displayed when the enduser clicks on the icon.
The seventh dropdown (multiple) shows how to combine multiple attribute with min/max rules to guide users selecting between 3 and 5 options.
MessageML
Datafeed Payload
<messageML>
  <form id="form_id">
    <h2>dropdown menus</h2>
      <select name="init"><option value="opt1">Unselected option 1</option><option value="opt2" selected="true">With selected option</option><option value="opt3">Unselected option 2</option></select>
      <select name="data-placeholder" data-placeholder="Only data-placeholder"><option value="opt1">Unselected option 1</option><option value="opt2">Unselected option 2</option><option value="opt3">Unselected option 3</option></select>
      <select name="noreq" data-placeholder="Not required"><option value="opt1">First</option><option value="opt2">Second</option><option value="opt3">Third</option></select>
      <select name="req" required="true" data-placeholder="Required"><option value="opt1">First</option><option value="opt2">Second</option><option value="opt3">Third</option></select>
      <select name="label" label="My Label" data-placeholder="With Label"><option value="opt1">Unselected option 1</option><option value="opt2">Unselected option 2</option><option value="opt3">Unselected option 3</option></select>
      <select name="tooltip" title="My Tooltip\n With a second line" data-placeholder="With Tooltip"><option value="opt1">Unselected option 1</option><option value="opt2">Unselected option 2</option><option value="opt3">Unselected option 3</option></select>
      <select name="multiple" label="With multiple select options - between 3 and 5" multiple="true" min="3" max="5"><option value="opt1" selected="true">Preselected option 1</option><option value="opt2" selected="true">Preselected option 2</option><option value="opt3" selected="true">Preselected option 3</option><option value="opt4">Unselected option 4</option><option value="opt5">Unselected option 5</option><option value="opt6">Unselected option 6</option></select>
      <button name="dropdown">Submit</button>
  </form>
</messageML>
[    
    {
        "id": "JQgymy",
        "messageId": "h53CRuPWoInmYbfw2T8dkn___pNK27l7bQ",
        "timestamp": 1566407149188,
        "type": "SYMPHONYELEMENTSACTION",
        "initiator": {
            "user": {
                "userId": 7078106482890,
                "firstName": "User",
                "lastName": "Bot",
                "displayName": "User",
                "email": "[email protected]",
                "username": "user_bot"
            }
        },
        "payload": {
            "symphonyElementsAction": {
                "actionStream": {
                    "streamId": "0YeiA-neZa1PrdHy1L82jX___pQjntU-dA"
                },
                "formStream": {
                    "streamId": "YuK1c2y2yuie6+UfQnjSPX///pQEn69idA=="
                },
                "formMessageId": "RfqsxcfTHCV08+UcO03HQH///pIqaO6fdA==",
                "formId": "form_id",
                "formValues": {
                    "action": "dropdown",
                    "init": "opt2",
                    "data-placeholder": "",
                    "noreq": "",
                    "req": "opt2",
                    "label": "",
                    "tooltip": "",
                    "multiple": ["opt1", "opt2", "opt3", "opt5", "opt6"]
                }
            }
        }
    }
]
Versions and Compatibility
Main features introduced
Agent needed to parse message sent by the bot
Client 2.0 release
Backward client-compatibility behavior (e.g. external rooms)
Initial release
2.55.9
Since first version
Not working
Label
20.6
Since first version
Label displayed and form can still be submitted
Tooltip (title)
20.7
Since first version
Tooltip not displayed but form can still be submitted
Multiple (with min and max) attributes
20.14
21.12
-
auto-submit
23.11
23.12
Not working

Last modified 15d ago

Attribute	Type	Required?	Description
`name`	String	Yes	Required attribute of the `<select>` tag. It identifies the dropdown menu.
`required`	Boolean	No	Optional attribute of the `<select>` tag. it is a Boolean attribute indicating that an option with a non-empty string value must be selected.
`value`	String	Yes	Required attribute of the `<option>` tag. It contains the data value to submit to the server when that option is selected.
`selected`	Boolean	Optional	You can include a selected attribute on an `<option>` element to make it selected by default when the page first loads. Accepted values: `true` and `false`.
`data-placeholder`	String	Optional	Text displayed in the dropdown menu before an option is selected. It can be a short hint or a title for the dropdown menu.
`title`	It accepts a simple text and `\n` for line breaks	Optional	The description that will be displayed when clicking the tooltip icon located on top of the Masked Text Field Element. Max length: 256 characters.
`label`	String	Not required but it is recommended if `title` is defined	Definition of the label that will be displayed on top of the Masked Text Field Element.
`multiple`	String Boolean	Optional Default is false	Allows users to select multiple values and the developer to send dropdown with multiple preselected options.
`min`	String Integer ≥ 2 and ≤ `max` attribute	Optional Can be used only if `multiple` attribute is set to true	Minimum number of options to be selected by the Symphony user. NB: If undefined, no minimum option needs to be selected. Please use `required` attribute if you want to set min to 1.
`max`	String Integer ≥ 2	Optional Can be used only if `multiple` attribute is set to true	Maximum number of options to be selected by the Symphony user. NB: If undefined, user will be able to select as many options as wished. Please use `multiple` attribute set to false if you want to set max to 1.
`auto-submit`	Boolean	Optional Default is false	When enabled, selecting a value will submit the form.

Main features introduced	Agent needed to parse message sent by the bot	Client 2.0 release	Backward client-compatibility behavior (e.g. external rooms)
Initial release	2.55.9	Since first version	Not working
Label	20.6	Since first version	Label displayed and form can still be submitted
Tooltip (title)	20.7	Since first version	Tooltip not displayed but form can still be submitted
Multiple (with min and max) attributes	20.14	21.12	-
auto-submit	23.11	23.12	Not working