Skip to main content

Fields

To implement Dromo in your application, you must first define a schema. A schema is an array of field objects. These fields will be matched to columns during the import process, and define the properties of the JSON payload passed back in the results.

Basics

The most basic field consists of only a key and label. The field's key is its unique identifier, and will be the key of that field in the result JSON object. The field's label is how it will be displayed to the user.

A basic schema could look like this:

fields: [
{
label: "First name",
key: "firstName"
},
{
label: "Last name",
key: "lastName"
},
{
label: "Membership ID",
key: "memberId"
}
]

Field object reference

  • labelstringRequired

    The human-friendly name of the field, shown to the user in the Dromo Uploader interface

  • keystringRequired

    The field's unique identifier, used as the key in the JSON results

  • typeFieldType
    Default: "string"

    The field's type.

    Can be supplied in two formats:

    • As a string corresponding to a valid field type. If the field type accepts options, defaults will be used.
    • For field types which accept options, as a two element array where the first element is the string corresponding to a valid field type, and the second element is an object with type options.

    For more details, see field types.

  • descriptionstring

    An optional description of this field for the user. If you specify a value for this field, Dromo will show a ? icon in the importer that users can hover over to see this message.

  • alternateMatchesstring[]

    An array of alternate matches that this field to map to. See column matching.

  • validatorsValidator[]

    An array of validator objects to validate this field. See validators.

  • selectOptions{ label: string, value: string }[]

    For select fields only, an array of possible picklist values. See the select field type.

  • readOnlyboolean
    Default: false

    If true, the user will not be able to edit the data in this field.

    This is useful if you want to exclusively populate a virtual field using hooks.

  • hiddenboolean
    Default: false

    If true, the field will be hidden from the user at all times. A hidden field can be set only using hooks.

    A user will not be able to match a column of data to the field. A user will not see the field in the review screen. The field will only be added to the submitted final result.

    Since a user cannot change the value of a hidden field, no validations can be set on a hidden field.

Field types

Dromo offers many field data types to parse and transform data, display it to the user, validate it, and output the data in a useful format.

The field type is set by passing a type parameter in the field object. This can be a string referring to one of the field types, explained below. Alternatively, some field types can take additional options controlling their behavior and format. In this case, you can provide the type parameter with a 2-element array, where the first element is the type name and the second element is any options that field type takes.

Here is an example of a few different valid field type configurations:

fields: [
{
label: "Email address",
key: "email",
type: "email"
},
{
label: "Subscription fee",
key: "subscriptionFee",
type: ["number", "eur"]
}
{
label: "Subscribed since",
key: "subscriptionStart",
type: ["date", { locale: "de-DE" }]
}
]

String

type: "string"

By default (if no field type is specified), all fields in Dromo have the string type. This is the simplest field type, and does not do any validation or transformation of the data – the data is output as a string exactly as it was entered.

The string type does not take any options.

Number

type: "number"

type: ["number", <preset name string>]

type: [
"number",
{
preset: <preset name string>,
round: <integer>,
displayFormat: <format object>,
outputFormat: <format object>
}
]

For all kinds of numeric values

The field type parses many common number formats and displays the number in a user-friendly format.

If the input data is unable to be parsed as a number, a validation error is added to the cell.

Unless an output format is specified, the number is output to the result JSON as a number.

Presets

The number type has several presets available to handle the most common number formats. You can use a preset by passing the name of the preset with the field type, such as type: ["number", "usd"].

Here are all of the presets that Dromo provides:

Preset NameSource valueDisplay value
default
(used if no display settings are given)
1234567.12345671,234,567.1234567
percent0.1234
0.56
12.34%
56%
plain1234567.1231234567.123
usd1234.567
-3456.78
$ 1,234.57
- $3,456.78
usd_accounting1234.567
-3456.78
$ 1,234.57
$ (3,456.78)
eur1234.567
-3456.78
1,234.57 €
-3,456.78 €
gbp1234.567
-3456.78
£ 1,234.57
- £3,456.78
decimal_0 or
integer
234.567235
decimal_1234.567
123
234.6
123.0
decimal_2234.567
123
234.57
123.00
decimal_3234.5678
123
234.568
123.000
decimal_4234.56789
123
234.5679
123.0000
percent_00.125613%
percent_10.1256
0.34
12.6%
34.0%
percent_20.12567
0.34
12.57%
34.00%
percent_30.123456
0.34
12.346%
34.000%
percent_40.12345678
0.34
12.3457%
34.0000%

Custom configuration

If none of the presets meet your needs, you can define your own rounding, display format and output format behavior.

The round setting takes an integer which defines how many digits after the decimal point the value will be rounded to. Negative values will round to digits before the decimal.

The displayFormat and outputFormat settings can be used for creating your own custom formats. The displayFormat is used for displaying the number to the user on the review screen. The outputFormat, if set, will determine how the number is output in the result JSON, as a string.

For more information on using displayFormat and outputFormat, see the number formatting page.

Date

type: "date"

type: [
"date",
{
locale: <locale string>,
displayFormat: <format string>,
outputFormat: <format string>
}
]

For handling date values (with no time)

The date type parses dates in several formats: ISO-8601, RFC-2822, and the configured display format in the configured locale. If a time is also given, it is allowed, but ignored. If a input date cannot be parsed, a validation error will be added to the cell.

By default, dates are output to the results in ISO-8601 format (e.g. "2022-03-27").

You can specify a locale for the date field, which must be a valid BCP 47 locale string. If not provided, the locale defaults to "en-US".

The locale will change how the date is displayed to the user with the display format. The locale will also affect the output format if a custom format is used.

The default display format is the standard short form in the configured locale, for example:

LocaleDefault format example
en-US3/27/2022
ar-SY٢٧/٣/٢٠٢٢
de-DE27.3.2022
pt-BR27/03/2022
th-TH27/3/2565
zh-CN2022/3/27

You can define your own display and/or output formats with a format string. For more information, see the datetime formatting page.

Datetime

type: "datetime"

type: [
"datetime",
{
locale: <locale string>,
displayFormat: <format string>,
outputFormat: <format string>,
withSeconds: <boolean>
}
]

For handling a date and time together in one field

The datetime type parses datetimes in several formats: ISO-8601, RFC-2822, and the configured display format in the configured locale.

By default, dates are output to the results in ISO-8601 format, with no time zone offset (e.g. "2022-03-27T15:20").

By default, seconds are neither displayed nor output. You can change this by providing withSeconds: true in the field settings.

You can specify a locale for the datetime field, which must be a valid BCP 47 locale string. If not provided, the locale defaults to "en-US".

The locale will change how the datetime is displayed to the user with the display format. The locale will also affect the output format if a custom format is used.

The default display format is the standard short form in the configured locale, for example:

LocaleDefault format example
en-US3/27/2022, 3:20 PM
ar-SY٢٧/٣/٢٠٢٢, ٣:٢٠ م
de-DE27.3.2022, 15:20
pt-BR27/03/2022 15:20
th-TH27/3/2565 15:20
zh-CN2022/3/27 下午3:20

You can define your own display and/or output formats with a format string. For more information, see the datetime formatting page.

Time

type: "time"

type: [
"time",
{
locale: <locale string>,
displayFormat: <format string>,
outputFormat: <format string>,
withSeconds: <boolean>
}
]

For handling a time-of-day independent of date (i.e., a clock time)

The time type parses datetimes in several formats: ISO-8601, RFC-2822, and the configured display format in the configured locale.

By default, times are output to the results in ISO-8601 format (e.g. "15:20").

By default, seconds are neither displayed nor output. You can change this by providing withSeconds: true in the field settings.

You can specify a locale for the datetime field, which must be a valid BCP 47 locale string. If not provided, the locale defaults to "en-US".

The locale will change how the time is displayed to the user with the display format. The locale will also affect the output format if a custom format is used.

The default display format is the standard time format in the specified locale, for example:

LocaleDefault format example
en-US3:20 PM
ar-SY٣:٢٠ م
de-DE15:20
zh-CN下午3:20

You can define your own display and/or output formats with a format string. For more information, see the datetime formatting page.

Select

type: "select",
selectOptions: [{ label: <string>, value: <string> }, ...]

Select fields allow you to provide a pick list of values that the user can choose from.

When creating a select field, you must provide an array of valid selectOptions, where each option is an object with the label and value keys. The label will be what is displayed to the user, and the value is what will be output to the results for that option.

Select fields provide several special features as the user is going through the import process.

During the column matching process, the user will be able to map all of the values occurring in the column to the select options.

Select option matching during column mapping

On the review screen, the field will show as a dropdown menu that the user can pick an option from.

Select dropdown on the review screen

A validation error will be shown if a value was not matched and does not equal one of the option labels.

Checkbox

type: "checkbox"

The checkbox field type is useful when you want to import a boolean (yes/no) field.

The field will be displayed to the user as a checkbox and output as a JSON boolean (true or false).

When importing, the following case-insensitive values are considered false: "" (empty cell), "0", "off", "n", "no", "false", "disabled".

All other values are considered true.

Email

type: "email"

An email field is a string field with a built-in email address validation.

A validation error will be added to a cell if it contains an invalid email address.

The email validation is equivalent to that specified by the HTML5 spec, with the additional constraints that single domains are not allowed (such as contact@dromo, with no TLD) and IP addresses are not allowed in the host portion.

Validators

Indepedent of field types, Dromo provides a number of validators that you can use to ensure that get clean data in exactly the format you want them. You can use validators to highlight errors for the user and ensure that they fix the errors before submitting an import.

You can specify validators for a field by providing the validators parameter, which takes an array of validator objects.

Each object must have a validate parameter which specifies what kind of validation it is. Every validator takes an optional errorMessage which you can use to provide a customized error message to the user when the validation fails. The error message is shown to the user as a tooltip on invalid cells.

A validator error message shown to the user

Dromo provides the following validators.

Required

  • validate"required"Required

Specifies that the field cannot be empty.

Unique

  • validate"unique" | "unique_case_insensitive"Required

Specifies that all non-empty values in the column must be distinct (non-equal).

You can also validate uniqueness case-insensitively with { validate: "unique_case_insensitive" }.

Unique across multiple fields

  • validate"unique_with"Required
  • uniqueKeystringRequired

The unique_with validator can be used to validate uniqueness across multiple fields.

To use it, place a unique_with validator on each field that you want to be part of the uniqueness validation, all sharing the same uniqueKey.

Here is an example set of fields using unique_with validators used to validate that the combination of the first name and last name fields are unique.

[
{
label: "First Name",
key: "firstName",
validators: [
{
validate: "unique_with",
uniqueKey: "full name",
},
],
},
{
label: "Last Name",
key: "lastName",
validators: [
{
validate: "unique_with",
uniqueKey: "full name",
},
],
},
]

And here is an example of the validators in action:

Matches a regular expression

  • validate"regex_match" | "regex_exclude"Required
  • regexstringRequired
  • regexOptionsRegexOptions

You can validate that a field matches the given regular expression with the regex_match validator.

Conversely, you can validate that a field does not match a regular expression with the regex_exclude validator.

The Dromo uploader uses standard JavaScript regular expressions. However, they must be supplied as strings and not RegExp objects or literals.

Be careful to properly escape special characters in your regex. For example, the regex /^"\d+"$/ should be passed in as "^\"\\d+\"$".

Note also that you cannot pass in regex flags directly in your regex. Instead, you may optionally provide a regexOptions parameter with the validator which takes an object with the following keys:

  • ignoreCase: boolean - Case insensitive flag (regex flag i)
  • dotAll: boolean - Matches all including any line breaks (regex flag s)
  • multiline: boolean - Multiline flag (regex flag m)
  • unicode: boolean - Unicode flag (regex flag u)

Require with other fields

  • validate"require_with" | "require_without" | "require_with_all" | "require_without_all"Required
  • fieldsstring[]Required

You can use these validators to require that a field be non-empty only if other fields are present or empty. There are four variations:

{ validate: "require_with", fields: [<fieldKey>, ...] }

This will require that the field has a value if any of the fields listed in the fields array are non-empty.

{ validate: "require_without", fields: [<fieldKey>, ...] }

This will require that the field has a value if any of the fields listed in the fields array are empty.

{ validate: "require_with_all", fields: [<fieldKey>, ...] }

This will require that the field has a value if all of the fields listed in the fields array are non-empty.

{ validate: "require_without_all", fields: [<fieldKey>, ...] }

This will require that the field has a value if all of the fields listed in the fields array are empty.

Require with other field values

  • validate"require_with_values" | "require_without_values" | "require_with_all_values" | "require_without_all_values"Required
  • fieldValues{ [fieldKey: string]: string }Required

You can use these validators to require that a field be non-empty only if other fields have specific values. There are four variations:

{ validate: "require_with_values", fieldValues: { <fieldKey>: <fieldValue>, ... } }

This will require that the field has a value if any of the fields contain the corresponding value specified under fieldValues.

{ validate: "require_without_values", fieldValues: { <fieldKey>: <fieldValue>, ... } }

This will require that the field has a value if any of the fields do not contain the corresponding value specified under fieldValues.

{ validate: "require_with_all_values", fieldValues: { <fieldKey>: <fieldValue>, ... } }

This will require that the field has a value if all of the fields contain the corresponding value specified under fieldValues.

{ validate: "require_without_all_values", fieldValues: { <fieldKey>: <fieldValue>, ... } }

This will require that the field has a value if all of the fields do not contain the corresponding value specified under fieldValues.

Column matching

During the column matching step, Dromo will try to match columns headers in the user data to a corresponding label or key within your fields.

If you want to provide additional aliases that should automatically match to a given field, you can do so by setting alternateMatches for that field.

Column matching is case-sensitive.

Example:

{
label: "City",
key: "city",
alternateMatches: ["municipality", "town", "locality"]
}