Form Field Component

Purpose

Form Field is a component that wraps a form field and provides a label, description, and error message.

Field Component

Field Component is using Formik for form management. It is a wrapper for Formik's field component. More information about Formik's field component can be found here.

Field Definition

Field definition is used to define the field component. It is used to define the field component in the form.

component: field
name: firstName # component / field name is required
props:
  label: First Name # label of the field
  type: text # type of the field

Props

• label (string): The label of the field. (localized)
• description (string): The description of the field. (localized)
• error (string): The error message of the field. (localized)
• type (string): The type of the field. It accepts text, number, password, email, checkbox, radio, select, select-async, textarea, date, time, datetime, rangedatetime, url, tel, file, hidden, image, range.
• placeholder (string): The placeholder of the field.
• defaultValue (string): The default value of the field.
• items (array): The items of the field. It is used for radio and select types.
• options (object): The options of the field. Options for Formik field component.

Yaml Example

component: field
name: firstName
props:
  label: First Name
  type: text
  placeholder: Enter your first name
  defaultValue: John

Field Types

The following types are supported:

• text
• number
• password
• email
• checkbox
• radio
• select
• select-async
• textarea
• date
• time
• datetime
• rangedatetime
• url
• tel
• hidden
• file
• image
• range

Text

The text type is used for single-line text input.

component: field
name: firstName
props:
  label: First Name
  type: text
  placeholder: Enter your first name

Number

The number type is used for input fields that should contain a numeric value.

Options: https://s-yadav.github.io/react-number-format/docs/numeric_format for more details.

component: field
name: age
props:
  label: Age
  type: number
  placeholder: Enter your age
  options:
    decimalScale: 3

Password

The password type is used for password input fields.

component: field
name: password
props:
  label: Password
  type: password
  placeholder: Enter your password

Email

The email type is used for email input fields.

component: field
name: email
props:
  label: Email
  type: email
  placeholder: Enter your email

Checkbox

The checkbox type is used for checkboxes.

component: field
name: terms
props:
  label: Terms
  type: checkbox
  onChange:
    - if: "{{ value }}"
      then: # if checked
        - setStore:
            terms: "T"
      else: # if unchecked
        - setStore:
            terms: "N"
  onKeyPress: # on key press event for the field
    - if: "{{ eval keyCode === 13 }}"
      then: # if enter key is pressed
        - consoleLog: "Enter key pressed"

Radio

The radio type is used for radio buttons.

component: field
name: PaymentMethod
props:
  label: Payment Method
  type: radio
  items:
    - label: Credit Card
      value: creditCard
    - label: PayPal
      value: payPal

Select

The select type is used for select dropdowns.

component: field
name: country
props:
  label: Country
  type: select
  options:
    allowSearch: true
    allowClear: true
    allowMultiple: true
    allowCreate: true
  items:
    - label: United States
      value: us
    - label: Canada
      value: ca

Select Async

Select with query is used to load options from a GraphQL query.

component: field
name: country
props:
  label: Country
  type: select-async
  options:
    valueFieldName: "countryCode" # if name is different than value field
    itemLabelTemplate: "{{value}}"
    itemValueTemplate: "{{id}}"
    searchQuery:
      name: getCountries
      path: countries
      totalCountPath: totalCount
    valueQuery:
      name: getCountry
      path: country
    allowSearch: true
    allowClear: true
    allowMultiple: false
    allowCreate: true
    queries:
      - name: getCountries
        query:
          command: "query { countries { id name } }"
          variables: { search: "{{search}}" }
      - name: getCountry
        query:
          command: "query { country(id: {{id}}) { id name } }"
        variables: { id: "{{id}}" }
    dropDownToolbar:
      - component: button
        name: createCountryBtn
        props:
          label:
            en-US: Create Country
          icon: plus
          options:
            variant: primary
          onClick:
            - dialog:
                component: Countries/CreateCountry
                onClose:
                  - selectValue: "{{ result.countryCode }}"
    onSelectValue:
      - setStore:
          selectedCountry: "{{ selectedItem }}"
    onCreateValue:
      - mutation:
          command: "mutation { createCountry(input: { countryCode: '{{ value }}' }) { countryCode } }"
          variables: { value: "{{ value }}" }

Select Async Options

• itemLabelTemplate (string): The template for the label of the item.
• itemValueTemplate (string): The template for the value of the item.
• searchQuery (object): The search query for the select dropdown.
• valueQuery (object): The value query for the select dropdown.
• allowSearch (boolean): Allow search in the select dropdown.
• allowClear (boolean): Allow clear in the select dropdown.
• allowMultiple (boolean): Allow multiple selection in the select dropdown.
• allowCreate (boolean): Allow create in the select dropdown.
• queries (array): The queries for the select dropdown.
• dropDownToolbar (components): The toolbar component to be displayed in the dropdown.
• onSelectValue (array): The actions to be executed when a value is selected.
• onCreateValue (array): The actions to be executed when a value is created.

Select Async Additional Actions

• 'refreshSelect': Reload the selected value from the server.

Textarea

The textarea type is used for multi-line text input.

component: field
name: description
props:
  label: Description
  type: textarea
  placeholder: Enter your description
  options:
    rows: 3

Date

The date type is used for date input fields.

component: field
name: date
props:
  label: Date
  type: date
  options:
    format: "MM/dd/yyyy"

Time

The time type is used for time input fields.

component: field
name: time
props:
  label: Time
  type: time
  options:
    format: "hh:mm a"

Datetime

DateTime and DateTimeRange Options Reference

Overview

This document describes all available options for datetime and rangedatetime field types in the TMS Frontend Web application.

DateTime Options

The datetime field type supports the following options:

Core Options

Option	Type	Default	Description
dateFormat	string	"MM/dd/yyyy"	Display format for the date picker. Uses moment.js format tokens.
showTimeSelect	boolean	false	Whether to show time selection in addition to date.
showTimeSelectOnly	boolean	false	Show only time picker without date selection.
timeIntervals	number	15	Time selection intervals in minutes (e.g., 15, 30, 60).
timeCaption	string	"Time"	Label displayed for the time selection section.

Timezone Options

Option	Type	Default	Description
useTimezone	boolean	false	Enable timezone-aware date handling. When false, dates are stored as simple strings.
storeAsUTC	boolean	false	When used with useTimezone: true, converts and stores dates in UTC format.
timezone	string	undefined	Fixed timezone for display (requires moment-timezone library).

Storage Format

Option	Type	Default	Description
format	string	undefined	Custom storage format. If not specified, format is determined by other options.

DateTime Range Options

The rangedatetime field type supports all datetime options plus:

Option	Type	Default	Description
isClearable	boolean	true	Whether to show a clear button to reset the date range.

Storage Formats by Configuration

Default (Simple Date)

type: datetime
# Stores as: "2024-03-15"

Date with Time

type: datetime
options:
  showTimeSelect: true
# Stores as: "2024-03-15 14:30:00"

Timezone-Aware with UTC Storage

type: datetime
options:
  showTimeSelect: true
  useTimezone: true
  storeAsUTC: true
# Stores as: "2024-03-15T19:30:00.000Z"

Timezone-Aware with Local Offset

type: datetime
options:
  showTimeSelect: true
  useTimezone: true
# Stores as: "2024-03-15T14:30:00-05:00"

Common Use Cases

1. Birth Date (Date Only)

- name: birthDate
  component: field
  componentProps:
    props:
      type: datetime
      label: Birth Date
      options:
        dateFormat: "MM/dd/yyyy"

2. Appointment Time (Local Time)

- name: appointmentTime
  component: field
  componentProps:
    props:
      type: datetime
      label: Appointment Time
      options:
        showTimeSelect: true
        timeIntervals: 30
        dateFormat: "MM/dd/yyyy h:mm aa"

3. International Meeting (UTC Storage)

- name: meetingTime
  component: field
  componentProps:
    props:
      type: datetime
      label: Meeting Time (UTC)
      options:
        showTimeSelect: true
        useTimezone: true
        storeAsUTC: true
        dateFormat: "MM/dd/yyyy HH:mm"
        timeCaption: "Time (UTC)"

4. Date Range Filter

- name: dateRange
  component: field
  componentProps:
    props:
      type: rangedatetime
      label: Date Range
      placeholder: "Select date range"
      options:
        dateFormat: "MM/dd/yyyy"
        isClearable: true

5. Delivery Window (Date Range with Time)

- name: deliveryWindow
  component: field
  componentProps:
    props:
      type: rangedatetime
      label: Delivery Window
      options:
        showTimeSelect: true
        timeIntervals: 60
        dateFormat: "MM/dd/yyyy h:mm aa"

6. Time-Only Selection

- name: dailyReminder
  component: field
  componentProps:
    props:
      type: datetime
      label: Daily Reminder Time
      options:
        showTimeSelectOnly: true
        timeIntervals: 15
        dateFormat: "h:mm aa"
        timeCaption: "Reminder Time"

Display Format Tokens

Common moment.js format tokens used in dateFormat:

Token	Output	Description
MM	01-12	Month (2 digits)
M	1-12	Month (1-2 digits)
DD	01-31	Day of month (2 digits)
D	1-31	Day of month (1-2 digits)
YYYY	2024	4-digit year
YY	24	2-digit year
HH	00-23	Hours (24-hour, 2 digits)
H	0-23	Hours (24-hour, 1-2 digits)
hh	01-12	Hours (12-hour, 2 digits)
h	1-12	Hours (12-hour, 1-2 digits)
mm	00-59	Minutes (2 digits)
m	0-59	Minutes (1-2 digits)
ss	00-59	Seconds (2 digits)
s	0-59	Seconds (1-2 digits)
a	am/pm	Lowercase meridiem
A	AM/PM	Uppercase meridiem

Migration Guide

From Individual Props to Options Object

Before (Deprecated):

<ReactDatepickerComponent
  id="eventDate"
  showTimeSelect={true}
  timeIntervals={30}
  dateFormat="MM/dd/yyyy h:mm aa"
/>

After (Recommended):

<ReactDatepickerComponent
  id="eventDate"
  options={{
    showTimeSelect: true,
    timeIntervals: 30,
    dateFormat: "MM/dd/yyyy h:mm aa",
  }}
/>

From Timezone-by-Default to Simple Dates

Before: Dates were often stored with timezone information by default.

After: Dates are stored as simple strings by default. To enable timezone handling:

options:
  useTimezone: true # Must be explicitly enabled

Best Practices

1. Use Simple Dates by Default: Unless you specifically need timezone handling, use the default simple date format.
2. Be Explicit About Time: If you need time selection, always set showTimeSelect: true.
3. Consider User Experience:
   • Use appropriate time intervals (15 min for appointments, 60 min for deliveries)
   • Provide clear labels with timeCaption
   • Use familiar date formats for your locale
4. DataGrid Filters: For date range filters in grids, use rangedatetime with clear labels.
5. International Applications: Only use useTimezone: true with storeAsUTC: true for truly international applications where timezone accuracy is critical.

Troubleshooting

Dates showing unexpected timezone

• Check if useTimezone is set to true unintentionally
• Verify the stored format matches your expectations

Time not appearing in picker

• Ensure showTimeSelect is set to true
• Check that dateFormat includes time tokens

Range picker not clearing

• Verify isClearable is not set to false
• Check for any custom validation preventing null values

Format not applying

• Ensure format tokens are valid moment.js tokens
• Check for typos in the dateFormat string

URL

The url type is used for URL input fields.

component: field
name: url
props:
  label: URL
  type: url
  placeholder: Enter your URL

Tel

The tel type is used for telephone input fields.

component: field
name: phone
props:
  label: Phone
  type: tel
  placeholder: Enter your phone number

Attachment

Attachment type is used for attachment input fields. It will create a new attachment record in the database and return the attachment id.

component: field
name: attachment
props:
  label: Attachment
  type: attachment
  options:
    allowMultiple: false
    allowClear: true
    displayAs: "image" # image, file
    previewWidth: 100 # optional
    previewHeight: 100 # optional
    maxSize: 10485760 # 10MB
    allowedExtensions:
      - "image/*"
      - "application/pdf"
    onUploaded:
      - consoleLog: "{{ result.attachmentId }}"

File

The file type is used for file input fields. File type will upload the file to the temp storage and return the file ur

component: field
name: file
props:
  label: File
  type: file

Hidden

The hidden type is used for hidden input fields.

component: field
name: id
props:
  label: ID
  type: hidden
  defaultValue: 1

Image

The image type is used for image input fields.

component: field
name: image
props:
  label: Image
  type: image

Range

The range type is used for range input fields.

component: field
name: range
props:
  label: Range
  type: range
  options:
    min: 0
    max: 100
    step: 1

Field Actions

The following actions are supported:

• setValue - Set value for a field. Available for form fields only.

Autocomplete

The autocomplete type is used for autocomplete input fields.

component: field
name: country
props:
  label: Country
  type: autocomplete
  options:
    allowSearch: true
    allowClear: true
    allowMultiple: true
    allowCreate: true
  items:
    - label: United States
      value: us
    - label: Canada
      value: ca

Autocomplete (Draft)

Autocomplete with query is used to load options from a GraphQL query.

component: field
name: country
props:
  label: Country
  type: autocomplete
  options:
    searchQuery:
      name: getCountries
      path: countries
    queries:
      - name: getCountries
        query:
          command: "query { countries { id name } }"
          variables: { search: "{{search}}" }
    onSelectValue:
      - setStore:
          selectedCountry: "{{ selectedItem }}"

Autocomplete Async With Google Places (Draft)

Autocomplete with Google Places is used to load options from Google Places API.

component: field
name: location
props:
  label: Location
  type: autocomplete
  options:
    searchQuery:
      type: googlePlaces
      options:
        apiKey: '{{ YOUR_GOOGLE_PLACES_API_KEY }}'
        locationRestriction: { country: 'us' }
        origin: { lat: 37.7749, lng: -122.4194 }
        includedPrimaryTypes: ['locality', 'administrative_area_level_1', 'country']
        language: "en-US",
        region: "us",
        fields: ['address_components', 'geometry', 'icon', 'name', 'place_id', 'types']
    onSelectValue:
      - setStore:
          selectedLocation: '{{ selectedItem }}'