Date Field Type

Description:
The date field type is used to capture date and time information from the user. It provides an interface for selecting dates, and optionally times, in a consistent and user-friendly format. This field is essential for applications that involve scheduling, event tracking, deadlines, or any functionality requiring accurate date and time inputs.

YAML Definition 

- name: event_date
  type: date
  display_name: "Event Date"
  guidance: "Select the date and time of the event."
  required: true
  format: "DD-MM-YYYY"
  time_format: "24hr"
  display: "date_time"
  default_value: null

Attributes

  • name (string): Required.
    The unique identifier for the field.

  • type (string): Required.
    Must be set to date for date fields.

  • display_name (string): Optional.
    The label displayed to the user. If not provided, a formatted version of name is used.

  • guidance (string): Optional.
    Help text or instructions displayed to the user for this field.

  • required (boolean): Optional.
    If true, the field must be completed before submission.

  • default_value (string): Optional.
    The default date value when the form loads. Should be in ISO 8601 format (e.g., "2023-01-01T00:00:00Z").

  • format (string): Optional.
    The format used to display and parse the date. Uses Moment.js format tokens. Common formats include "DD-MM-YYYY" or "MM/DD/YYYY".
    Default: "DD-MM-YYYY"

  • input_format (string): Optional.
    The format expected when the user inputs the date manually. If not specified, format is used.

  • time_format (string): Optional.
    Specifies the time format if time selection is enabled. Options are "24hr" or "ampm" for 12-hour format with AM/PM.
    Default: "24hr"

  • display (string): Optional.
    Determines how the date and time pickers are displayed. Options are:
    • "date_time": Display both date and time pickers.
    • "date_only": Display only the date picker.
    • "time_only": Display only the time picker.
      Default: "date_time"

  • readonly (boolean): Optional.
    If true, the field is displayed but cannot be edited.

  • hidden (boolean): Optional.
    If true, the field is not displayed to the user.

Example 

- name: appointment_date
  type: date
  display_name: "Appointment Date"
  guidance: "Please select your preferred appointment date and time."
  required: true
  format: "YYYY-MM-DD"
  input_format: "MM/DD/YYYY"
  time_format: "ampm"
  display: "date_time"
  default_value: null

In this example:

  • appointment_date: Captures both the date and time for an appointment.
  • format: Displays the date in "YYYY-MM-DD" format.
  • input_format: Users input the date in "MM/DD/YYYY" format.
  • time_format: Uses 12-hour time format with AM/PM indicators.
  • display: Shows both date and time pickers.

Usage Notes

  • Date Input and Display:
    • format: Defines how the date is displayed to the user and how the input is parsed internally.
    • input_format: Useful if you want to accept a different date format from what is displayed.
    • Ensure that the date format aligns with the locale and expectations of your user base.
  • Time Selection:
    • By default, both date and time pickers are displayed ("display": "date_time").
    • Set "display": "date_only" to hide the time picker and collect only the date.
    • Use "time_only" if you need to capture time without a date.
    • time_format: Choose between "24hr" and "ampm" based on user preference.
  • Default Values:
    • default_value: Can be set to a specific date/time in ISO 8601 format.
    • If you want the current date/time as the default, handle this in your application logic.
  • Validation:
    • When required is true, ensure that the user cannot submit the form without selecting a date (and time, if applicable).
    • Implement additional validation as needed, such as ensuring the date is not in the past.
  • Guidance and Labels:
    • Provide clear display_name and guidance to assist users in making correct selections.
    • Use the guidance attribute to specify acceptable date ranges or formats.
  • Readonly and Hidden Fields:
    • Use readonly for dates that should be displayed but not edited, such as creation timestamps.
    • Use hidden to include date data in the model without displaying it to the user.
  • Internationalization:
    • Adjust date and time formats to match the locale of your users.
    • Be mindful of time zones when storing and displaying dates.
  • Time Zones:
    • Store dates in a standard time zone (e.g., UTC) and convert to the user’s local time zone for display.
    • If time zones are important, consider adding a separate field to capture or display the time zone.
  • Data Binding:
    • The date selected by the user is typically stored in ISO 8601 format.
    • Ensure that your application correctly parses and formats dates when processing form data.
  • User Experience:
    • Provide a date picker to reduce input errors and improve usability.
    • Allow manual date entry for power users or to accommodate accessibility needs.

By integrating the date field type into your schema, you enable users to input dates and times efficiently and accurately, enhancing the functionality and reliability of your application.

Copyright © 2024 Caseblocks Limited.