Configuring columns

Like columns in a spreadsheet, a Column in a template represents fields you expect your users to upload. Each Template consists of one or more Columns, which are represented by regular Javascript objects. To configure Columns in a template, pass in an array of Column objects to the columns parameter in the DolphinCSVImporter instance / component.

General column properties

All columns have 4 properties in common:

Property	Description	Type
type	The Column type.	string
key	The Column key acts as the Column identifier. When you receive the imported data, fields will be saved using the key.	string
label	The Column label visible to your users.	string
required	Determines if the Column is required. If it is, users will need to supply data for that Column, and values for that Column cannot be blank.	boolean

On top of those 3 common properties, some Columns contain a Meta object, which controls data validation & formatting within the Column.

See below for examples of how to define each Column & its associated Meta.

Types of Columns

Text

A text column represents any arbitrary text. The following Meta properties are available:

Property	Description	Type	Default
max_length (optional)	The maximum length for the text	number
min_length (optional)	The minimum length for the text	number
alphanumeric_only (optional)	Specifies whether to only alphanumeric characters are allowed	boolean	false
letter_casing (optional)	Specifies expected letter casing. The default option means the importer will not validate letter casing.	default | uppercase | lowercase | title	default
disallowed_characters (optional)	Specifies any characters you want to disallow from the text. Place all the disallowed characters inside a string, like this: #$%^&*()	string
disallow_tabs (optional)	Specify whether tab characters (\t) are disallowed.	boolean	false
disallow_linebreaks (optional)	Specify whether linebreak characters (\n) are disallowed	boolean	false

Example:

const textColumn = {
    type: "text",
    key: "name",
    label: "Name",
    required: true,
    meta: {
        max_length: 2,
        min_length: 64,
        alphanumeric_only: false,
        letter_casing: "title",
        disallowed_characters: "_#@$%^&*()",
        disallow_tabs: true,
        disallow_linebreaks: true,
    }
}

Email

An email column captures email addresses. It does not have any Meta properties.

Example:

const emailColumn = {
  type: "email",
  key: "email",
  label: "Email Address",
  required: true
}

URL

A URL column captures website URLs. It does not have any Meta properties.

Example:

const urlColumn = {
    type: "url",
    key: "website",
    label: "Website URL",
    required: false
}

International Phone Number

An international phone number column captures phone numbers in international format. It does not have any Meta properties.

Example:

const phoneColumn = {
    type: "phone",
    key: "contactNumber",
    label: "Contact Number",
    required: true
}

US Phone Number

A US phone number column captures phone numbers specific to the US format. It does not have any Meta properties.

const usPhoneColumn = {
  type: "us_phone",
  key: "usContactNumber",
  label: "US Contact Number",
  required: true
}

US Postcode

A US postcode column captures postal codes in the United States. It does not have any Meta properties.

const usPostcodeColumn = {
  type: "us_postcode",
  key: "zipcode",
  label: "ZIP Code",
  required: true
}

Picklist

A picklist column provides a dropdown selection. The following Meta property is available:

Property	Description	Type
options	An array of options for selection.	{label: string, value: string}[]

const picklistColumn = {
    type: "picklist",
    key: "department",
    label: "Department",
    required: true,
    meta: {
        options: [
            { label: "Sales", value: "sales" },
            { label: "Marketing", value: "marketing" },
            { label: "Development", value: "development" }
        ]
    }
}

Number

A number column captures numeric values. The following Meta properties are available:

Property	Description	Type	Default
min_value (optional)	The minimum value allowed.	number
max_value (optional)	The maximum value allowed.	number
disallow_decimals (optional)	Specifies whether decimal values are disallowed.	boolean	false

Example:

const numberColumn = {
    type: "number",
    key: "quantity",
    label: "Quantity",
    required: true,
    meta: {
        min_value: 1,
        max_value: 100,
        disallow_decimals: true
    }
}

Percentage

A percentage column captures percentage values. Imported percentage data is returned as floating point numbers (i.e. 10% is returned as 0.1).The following Meta properties are available:

Property	Description	Type	Default
min_value (optional)	The minimum value allowed (e.g. 0.1 to denote 10%).	number
max_value (optional)	The maximum value allowed (e.g. 0.9 to denote 90%).	number

Example:

const percentageColumn = {
    type: "percentage",
    key: "completionRate",
    label: "Completion Rate",
    required: false,
    meta: {
        min_value: 0,
        max_value: 100
    }
}

Date

A date column captures date values. Date data is returned as a string. The following Meta properties are available:

Property	Description	Type	Default
min_value (optional)	The minimum date allowed in YYYY-MM-DD format.	string
max_value (optional)	The maximum date allowed in YYYY-MM-DD format.	string

Example:

const dateColumn = {
    type: "date",
    key: "startDate",
    label: "Start Date",
    required: true,
    meta: {
        min_value: "2023-01-01",
        max_value: "2024-12-31"
    }
}

Datetime

A datetime column captures date and time values. Datetime data is returned as a UTC timestamp indicating the number of seconds since epoch. The following Meta properties are available:

Property	Description	Type	Default
min_value (optional)	The minimum datetime allowed in YYYY-MM-DD hh:mm:ss format.	string
max_value (optional)	The maximum datetime allowed in YYYY-MM-DD hh:mm:ss format.	string

Example:

const datetimeColumn = {
    type: "datetime",
    key: "eventTime",
    label: "Event Time",
    required: true,
    meta: {
        min_value: "2023-01-01T00:00:00Z",
        max_value: "2024-12-31T23:59:59Z"
    }
}