Type-Specific Field Attributes

In addition to common field attributes (supported by all field types) there are also type-specific attributes supported by some (but not by all) field types. These type-specific attributes include:

  • dateFormat
  • emptyMeansNull
  • socialProfileData
  • ignoreUpdate
  • placeholder
  • preChecked
  • submitVersion
  • options
  • value
  • yearEnd
  • yearStart

These attributes are described in more detail in the following sections.

dateFormat

Required: No

Enables you to change the format used in date select fields. By default, dates are displayed using the format mm/dd/yyyy (month/day/year). For example, December 19, 1989 looks like this:

12/19/1989

However, by using the dateFormat attribute you can change the way that December 19, 1989 is displayed. For example, you can configure the date format to look like this:

"dateFormat": "mm/dd/yyyy"

In turn, December 19, 1989 would look like this:

19/12/1989

You can use any combination of mm, dd, and yyyy (separated by /’s) in order to construct a date format. The syntax yyyy/mm/dd yields the following:

1989/12/19

When assigning the dateFormat attribute by using the Configuration API, your syntax will look similar to this:

{
  "type": "dateselect",
  "name": "birthdate",
  "schemaAttribute": "birthday",
  "dateFormat": "dd/mm/yyyy"
}

The dateFormat attribute can be used with the following field types:

  • date select

emptyMeansNull

Required: No

When set to true, allows the system to interpret empty (blank) values as being null values. This can be especially useful with unique attributes, because an empty is still a value: it’s just that the value is, effectively, nothing. By contrast, a null value means “There is no value here, not even a blank value.” That might seem like a trivial distinction , but because an empty value is a value, only one user in your entity type can have an empty value assigned to a unique attribute: multiple users can’t be assign the same value, not even an empty value. Because null values aren’t really values, however, a unique attribute can have multiple users assigned a null value.

The emptyMeansNull attribute can also useful when working with date fields: they enable you to reset a date field to a null value (e.g., the user has not specified their date of birth) as opposed to resetting that date to an empty value.

When assigning the emptyMeansNull attribute by using the Configuration API, your syntax will look similar to this:

{
  "type": "text",
  "name": "mobileNumber",
  "schemaAttribute": "mobileNumber",
  "validation": [
    {
      "rule": "unique",
      "value": true,
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
  ],
  "emptyMeansNull": true
}

The emptyMeansNull attribute can be used with the following field types:

  • text input
  • email
  • password
  • select menu
  • text area
  • date select
  • hidden

socialProfileData

Required: No

When a user logs in using a social provider, the Social Login service returns information obtained from the social provider in the form of a Portable Contact payload. You can use the socialProfileData attribute to specify which data from the social profile should be used to populate the value for this field in the user record. For example:

“socialProfileData": "profile.name.familyName"

The socialProfileData attribute can be used with the following field types:

  • text input
  • email
  • text area

ignoreUpdate

Required: No

When set to true, enables you to create a field that can be filled in by an end user but is not written to the user profile. The ignoreUpdate attribute is typically used with hidden/calculated fields.

When assigning the ignoreUpdate attribute by using the Configuration API, your syntax will look similar to this:

{
  "type": "hidden",
  "name": "optInHidden",
  "schemaAttribute": "optIn.status",
  "value": "null",
  "ignoreUpdate": true
}

The ignoreUpdate attribute can be used with the following field types:

  • text input
  • email
  • password
  • checkbox
  • radio buttons
  • select menu
  • text area
  • hidden

placeholder

Required: No

Used as the placeholder attribute on form elements when using the JavaScript SDK. A placeholder is text that appears in a field, but then disappears as soon as the user begins to type in that field. For example:

The placeholder must be a reference to a translation identifier; you can use the /config/{app}/flows/{flow}/locales/{locale} endpoint to return a list of valid identifiers. For example:

"placeholder": {
  "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
}

The placeHolder attribute can be used with the following field types:

  • text input
  • email
  • password
  • text area
  • multiIdentifierAuth

preChecked

Required: No

If set to true, the checkbox will be preselected on a form; users who do not want to accept that option will then have to manually clear the checkbox. For example:

"preChecked":true

The preChecked attribute can be used with the following field types:

  • checkbox

submitVersion

Required: No

Use this if you need to specify the submit value of a checkbox (in other words, if the checkbox should submit a value other than on). For example:

"submitValue": "true"

The submitVersion attribute can be used with the following field types:

  • checkbox

options

Required: Yes

For the radio and select fields, you must define the options to be displayed. Options have the following attributes:

  • disabled (optional). Set to true to disable the option.
  • label (optional). Label to display for the option. This must be a reference to a translation identifier; you can use the /config/{app}/flows/{flow}/locales/{locale} endpoint to return a list of valid identifiers.
  • selected (optional). Set to true to select this option by default. Only one option in a field can have this attribute.
  • value (optional). The value of this option.

For example:

"options": [
  {
    "selected": true,
    "label": {
      "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
    },
    "value": "waffles"
  }
]

The options attribute can be used with the following field types:

  • radio buttons
  • select menu

value

Required: No

Enables you to configure a default value for a field; default values can be configured either as a string or as a Boolean (true/false) value.

For example, the following code snippet sets the default value of the optInHidden field to false:

{
  "type": "hidden",
  "name": "optInHidden",
  "schemaAttribute": "optIn.status",
  "value": false
}

The value attribute can be used with the following field types:

  • text input
  • radio buttons
  • select menu
  • text area
  • hidden

Note that, with the checkbox field, preChecked is used instead of value.

yearEnd

Required: No

Enables you to specify the final year shown in a date select control. For example, in this date select control 2021 is configured as the final year:

That means that, with this control, you cannot select any date later than December 31, 2021.

When assigning the yearEnd attribute by using the Configuration API, your syntax will look similar to this:

{
  "type": "dateselect",
  "name": "childBirthdate",
  "schemaAttribute": "birthday",
  "yearEnd": "2021"
}

The yearEnd attribute can be used with the following field types:

  • date select

yearStart

Required: No

Enables you to specify the first year shown in a date select control. For example, in this date select control 2008 is configured as the earliest available year:

That means that, with this control, you cannot select any date earlier than January 1, 2008.

When assigning the yearStart attribute by using the Configuration API, your syntax will look similar to this:

{
  "type": "dateselect",
  "name": "childBirthdate",
  "schemaAttribute": "birthday",
  "yearStart": 2008
}

The yearStart attribute can be used with the following field types:

  • date select