Fields

You will need to define a schema for your import, which consists of a list of fields. These fields will be matched to columns during the import process, used for validation and transformation, and will define the keys of the objects in the result data when the import is complete.

Fields are defined in Pulter as an array of objects. There are two required settings for each field: label and key. The field's label will be what users see when they are mapping the imported columns to fields. The field's key will be used to identify the field internally, and will also be the object key used in the result data.

Here is a basic example of defining some fields:

Required settings​

label​

Type: string​

The label is the human-readable name of the field that will display in the import header when the user is completing an import.

key​

Type: string​

The key is what you will refer to your field as in your application.

Optional settings​

description​

Type: string​

The description field allows you to specify additional information for your users. If you specify a value for this field, Pulter will show a ? icon in the importer that users can hover over to see this message.

example​

Type: string​

The example field allows you to specify the kind of data you want from your users. The value specified value can be downloaded as sample CSV file by your users.

alternateMatches​

Type: string[]​

The alternateMatches field allows you to provide alternate column names that you users might import. For instance, if you have a "First Name" field and you have many users importing data that has "FNAME" in the header, you can provide "FNAME" as an alternate to improve the matching process.

validators​

Type: [ ValidatorObject, ... ]​

The validations option helps you ensure you have clean data. You can specify how data should be formatted and display messages to the user to help identify what the problems are and how to fix them.

The validations option is an array of objects where each object can have a total of four keys: rule, errorMessage, regex and regexOptions

• rule: string (required): The options are:

  • rule: "required" specifies the field as a required field and will display an error message to the user if this field is empty.

  • rule: "unique" specifies that no two values in this column contain the same value.

  • rule: "regex" will require the field to match the regex validation provided in the regex key.

• errorMessage: string: This is how you display a custom error message to your users if the value fails validation. This is not required. If you don't specify an errorMessage, users will get a default message based on the type of validator. For example, validate: "required" returns an error message that simply says "Required."

• level: "info" | "warning" | "error": By default, cells that fail a validation will add an error-level message to the cell. You can override this to a lower level if you do not want a failing validation to be marked as an error.

• value: string (required if using rule with regex as the value for the rule key): This is the regular expression that you want to validate the uploaded value against. The regular expression must be a string, which will be supplied to the RegExp() constructor. Note that you may need to be careful with properly escaping special characters like backslashes in your string. You can test your regular expression and escape it using this resource.

• flags: string(optional if using rule with regex as the value for the rule key): This key allows you to provide the i, m, u and s regex flags as values instead of including them directly in your string.

fieldType​

Type: "input" or "checkbox" or "select"​

Default: "input"​

The fieldType option allows you to specify a field as a input, checkbox or select field. The checkbox field will display a checkbox to the user and can handle the following values:true / false, yes / no, y / n, enabled / disabled

The select field will render a dropdown menu with a list of selectOptions (described below)

SelectOption​

Type: [ SelectOptionsObject, ... ]​

Required: required with type: "select"​

The selectOptions field must only be used when type is set to "select". The value of this field should be an array of objects (each object is one object in the dropdown displayed to the user). You must specify a value and label field for each option.

• value (required): This is the value that will be sent in the data (similar to the key field).

• label (required): This is what the user will see in the dropdown menu.

booleanMatches

Type: { [key]: boolean }​

Optional: only used with type: "checkbox"​

With booleanMatches field you can set alternate values to be treated as booleans.

Here is a full example of defining some fields:

<Pulter
  fields =[
  {
    label: 'Name',
    key: 'name',
    alternateMatches: ['first name', 'first'],
    fieldType: {
      type: 'input',
    },
    example: 'Stephanie',
    validations: [
      {
        rule: 'required',
        errorMessage: 'Name is required',
      },
    ],
  },
  {
    label: 'Surname',
    key: 'surname',
    alternateMatches: ['second name', 'last name', 'last'],
    fieldType: {
      type: 'input',
    },
    example: 'McDonald',
    validations: [
      {
        rule: 'unique',
        errorMessage: 'Last name must be unique',
        level: 'info',
      },
    ],
    description: 'Family / Last name',
  },
  {
    label: 'Age',
    key: 'age',
    alternateMatches: ['years'],
    fieldType: {
      type: 'input',
    },
    example: '23',
    validations: [
      {
        rule: 'regex',
        value: '^\\d+$',
        errorMessage: 'Age must be a number',
        level: 'warning',
      },
    ],
  },
  {
    label: 'Team',
    key: 'team',
    alternateMatches: ['department'],
    fieldType: {
      type: 'select',
      options: [
        { label: 'Team One', value: 'one' },
        { label: 'Team Two', value: 'two' },
      ],
    },
    example: 'Team one',
    validations: [
      {
        rule: 'required',
        errorMessage: 'Team is required',
      },
    ],
  },
  {
    label: 'Is manager',
    key: 'is_manager',
    alternateMatches: ['manages'],
    fieldType: {
      type: 'checkbox',
      booleanMatches: {},
    },
    example: 'true',
  },
]
  />