Select menu field

The select menu field (also known as a dropdown list) offers the same sort of functionality as radio buttons offer: the select menu enables users to select a single value from a set of possible values. As a general rule, radio buttons are used if you have a limited number of options available (e.g., 4 or 5). If you have a larger number of options (for example, you need to ask users which of the 50 US states they live in), a select menu is typically recommended. (As you might expect, having 50 radio buttons, one for each state, might not be the most efficient and effective UI design.)


Select menu attributes and terminology

The select menu field, like other [Identity Cloud fields, provides a number of attributes (options) you can use when creating and formatting the field. Also like other Identity Cloud fields, the terminology used to represent these attributes in Console’s Registration Builder sometimes differs from the terminology required when using the Configuration APIs, which, in turn, sometimes differs from the terminology used if you view the underlying flow. 

Needless to say, this can be confusing at time. With that in mind, the following table shows the different select menu attributes and how they are referenced in Registration Builder, the Configuration API, and the flow; click the appropriate link in the flow column for more information about that attribute. Attributes highlighted in yellow are auto-generated when the field is created, and shouldn’t be referenced when making an API call (and can’t be accessed in Registration Builder).

Option used in Registration BuilderMember used when making an API call\ Property name used in the flow
Namenamename
Field Typetypetype
Schema AttributeschemaAttributeschemaId
Labellabellabel
Tiptiptip
Options -- Valuevaluevalue
Options -- Labeltexttext
Options -- Disableddisableddisabled
SelectedselectedPre-selected
Submit blank field values as nullemptyMeansNullemptyMeansNull
Ignore updates submitted to this fieldignoreUpdateignoreUpdate
Data Validationsvalidationvalidation
Formsformsforms
element

Create a select menu by using the Configuration API

If you’re using the Configuration APIs to create a select menu, you must include all the desired attributes and attribute values within the request body of your API call. That request body will look similar to one shown below (depending, of course, on the number of attributes you use). For example:

{
     "type": "select",
     "name": "testFieldSelect",
     "schemaAttribute": "primaryAddress.country",
     "ignoreUpdate": false,
     "emptyMeansNull": true,
     "label": {
          "key": "3d43b06fe00fa7cdc32e45ecc8399239"
     },
     "tip": {
          "key": "3d43b06fe00fa7cdc32e45ecc8399239"
     },
     "options": [{
               "selected": true,
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "US"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Canada"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Mexico"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Iceland",
               "disabled": "true"
          }
     ]
}

If you’re using Postman, your request body will look like this:

There are at least three things to keep in mind when creating the request body:

  • The request body must be formatted using JSON (JavaScript Object Notation). If you get the following error, that often means that your request body isn’t using valid JSON:

    400 Bad Request. The browser (or proxy) sent a request that this server could not understand.
    
  • The label, text, and tip attributes must be formatted as JSON objects; that is, you must start with the attribute name (e.g., tip) followed by a colon and a set of curly braces ({ }). Inside those curly braces, use the key member followed by the id of a translation key containing the text you want to use for the label/tip/placeholder. For example:

    "label": {"key": "352a99f1e9442568706468966749f1e9"}
    

    Note that you must reference a translation key (i.e., a  previously-defined piece of text) when creating a label or tip. Suppose you try defining your text within the API call:

    "label": "Preferred Contact Method"
    

    That’s going to result in an invalid syntax error. Instead, use the ID of an existing translation key. If you don't have a translation key that uses the string value Preferred Contact Method then you'll need to create one before you can create the select menu field.

  • The forms attribute must be formatted as a JSON array, with the form names configured as a comma-separated list between square brackets. For example,

    "forms": ["traditionalRegistrationForm", "socialRegistrationForm"]
    

When creating the individual items for your select menu, the following members are available for use:

  • label. Value that appears when the user clicks the dropdown list. For example, in the select menu shown at the beginning of this article, you'll see labels such as Email and Text message. This member is required.

  • value. Value written to the user profile. This can be the same value as the text assigned to the label (e.g., email) or it can be different from the label (for example, the Email option could write a 1 to the user profile).

  • selected. If set to true, indicates that the option that should be selected by default. Note that only one option can have the selected property set to true (which makes sense: you can only have one default value in a dropdown list). Setting the selected property of multiple items to true causes your API call to fail.

    By default, the selected value is set to false for each option. The selected member is not required.

  • disabled. When set to true, the option is “grayed out” and can’t be selected; in the sample dropdown list, Social media direct message has been disabled.

    The default value is false. The disabled member is not required.

A complete Curl command for creating a select menu will look similar to this:

curl -L -X POST \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/fieldExamples/fields' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
  --data-raw '{
     "type": "select",
     "name": "testFieldSelect",
     "schemaAttribute": "primaryAddress.country",
     "ignoreUpdate": false,
     "emptyMeansNull": true,
     "label": {
          "key": "3d43b06fe00fa7cdc32e45ecc8399239"
       },
     "tip": {
          "key": "3d43b06fe00fa7cdc32e45ecc8399239"
       },
     "options": [{
               "selected": true,
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "US"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Canada"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Mexico"
          },
          {
               "label": {
                     "key": "3d43b06fe00fa7cdc32e45ecc8399239"
               },
               "value": "Iceland",
               "disabled": "true"
          }
     ]
}'