Date Time Picker ALPHA

Required plan: Emerging

The Date Time Picker Element is an embeddable UI for the Real Time Scheduling API. It converts an Availability query into a calendar highlighting the available days with a list of the available slots for each day. It also provides a dropdown to allow the user to select a specific timezone to view the availability in.

When a user confirms a slot, the Element passes that slot’s details into a callback function (provided when the Element is initialized).

Demo #

Example initialization #

<div id="cronofy-date-time-picker"></div>
<script src="https://elements.cronofy.com/js/CronofyElements.v1.34.0.js"></script>
<script>
    CronofyElements.DateTimePicker({
        element_token: "{ELEMENT_TOKEN}",
        target_id: "cronofy-date-time-picker",
        availability_query: {
            participants: [
                {
                    required: "all",
                    members: [
                        { sub: "acc_12345678" },
                        { sub: "acc_87654321" }
                    ]
                }
            ],
            required_duration: { minutes: 30 },
            query_periods: [
                { start: "2021-07-27T09:00:00Z", end: "2021-07-27T17:00:00Z" },
                { start: "2021-07-28T09:00:00Z", end: "2021-07-28T17:00:00Z" }
            ]
        },
        styles: {
            prefix: "custom-name"
        },
        callback: notification => console.log("callback", notification)
    });
</script>

Element permissions #

Only availability is required when generating the Element Token.

Element options #

element_token required  #

The Element Token the Date Time Picker will use to communicate with Cronofy.

Not required if the Element is activated in demo mode.

target_id required  #
The ID of the DOM node the Element will be loaded in to.

availability_query required  #
Object describing the Cronofy Availability request used to generate the offered times.

callback required  #

The function to be called when an action has occurred within the Element. Receives an object in the format:

{
    "notification": {
        "type": "notification_type"
    }
}

The object will always include a notification object with a type attribute to allow you to determine how to handle it. New notifications will be added in the future and differentiated by having new type values, so your application should ignore notification types that do not exist in the current list.

slot_selected

Sent by the Element when in the confirm mode after the user has confirmed their selection, and straight away when the slot is selected in no_confirm mode.

{
  "notification": {
      "type": "slot_selected"
      "slot": {
          "start": "2021-07-27T09:00:00Z",
          "end": "2021-07-27T11:00:00Z",
          "participants": [
            { "sub": "acc_12345678" },
            { "sub": "acc_87654321" }
          ]
      }
    }
}

data_center optional  #
Designates the Cronofy data center the Element will communicate with.

Default value is us.

config optional  #
Use this object to add further configuration to the Element:

config.mode optional  #
The Date Time Picker Element has two “modes” it can operate in:

  • confirm (default)
  • no_confirm

When in confirm mode, clicking a slot displays a confirmation view that allows a user to confirm their selection or return to the list of slots. The callback function will be called with a slot_selected notification when a user confirms their selected slot.

When in no_confirm mode, the “confirmation” step is skipped. In this mode, the callback function will be passed a slot_selected notification when a user selects a slot, without any confirmation step.

config.logs optional  #
Set the level of logging you want to appear in the console:

  • info: show verbose logging (recommended for development use only).
  • warn: (default) only log errors and warnings.
  • error: only log errors.
  • none: suppress all console output from the Element.

config.tz_list optional  #
The Date Time Picker Element includes a timezone dropdown that allows the user to view the available days and times in a timezone of their choice.

This config option allows you to set an array of timezones you want to appear in the timezone dropdown:

tz_list: [
    "America/Sao_Paulo",
    "Etc/UTC",
    "Pacific/Fakaofo",
    "Europe/London",
],

The list must be made up of known time zone identifiers from the IANA Time Zone Database. Setting this option will entirely override the default list, so ensure you include all the timezones you need.

styles optional  #
An object that controls the pre-packaged element styles.

styles.prefix optional  #
Customizable elements are given a prefixed class name using this value. For example, if the prefix was set as “Foo”, the class name on a slot element would be Foo__time-slot.

Defaults to DTP.

styles.colors optional  #
Use these options to set the colors for various parts of the Element without the need to add your own custom CSS. Each color option accepts either a valid HEX code (e.g. available: "#FF0000") or a browser-safe color name (e.g. button: "tomato")

  • black - defaults to #000000
  • white - defaults to #ffffff
  • neutralDark - defaults to #6f6f6f
  • neutral - #999999
  • neutralLight - #e4ebf2,
  • button - button background color. Defaults to #15B3D6
  • buttonConfirm - #e2fac8,
  • buttonHover - button background color when hovered.
  • buttonText - button text color. Defaults to the black variable.
  • buttonTextHover - button text color when hovered. Defaults to the black variable.
  • buttonActive - button background when selected/active.
  • buttonActiveText: button text color when a button is active/selected. Defaults to the black variable.

demo optional  #
Boolean to activate demo-mode. Defaults to false. If demo is set to true the Element will return mock data (and not make any API calls).

locale optional  #
The Date Time Picker supports localization (e.g. locale: "fr" to load in French). Defaults to browser language setting.

Supported locales (languages) for the UI Elements are:

  • de German
  • en US English (default)
  • es Spanish
  • fr French
  • fr-CA Canadian French
  • it Italian
  • ja Japanese
  • nl Dutch
  • pl Polish
  • ru Russian
  • sv Swedish

translations optional  #
To override either a locale or a particular string, pass in a translations object here. The Date Time Picker uses the date_time_picker translation “context”.

Read more about customizing translations

tzid optional  #
The time zone that the Date Time Picker will be rendered in. Must be a known time zone identifier from the IANA Time Zone Database.

If this value is not set, or is set to an invalid tzid then the Element will use the system time zone from the user’s browser and trigger a warn notification.

Be aware, using the tzid option will cause the Date Time Picker to render in a timezone that may not match the timezone of the user’s computer. Be sure to highlight this to the user.

Element classes #

PREFIX default is DTP

Available classes:

  • {PREFIX}__details
  • {PREFIX}__calendar-header
  • {PREFIX}__calendar-header-button
  • {PREFIX}__calendar-grid--week-day
  • {PREFIX}__calendar-grid--button
  • {PREFIX}__calendar-grid--available
  • {PREFIX}__calendar-grid--focused
  • {PREFIX}__slots-list
  • {PREFIX}__no-slots
  • {PREFIX}__time-slot
  • {PREFIX}__confirm-details
  • {PREFIX}__confirm-button
  • {PREFIX}__cancel-button

Element methods #

refresh()  #

From time to time you may wish to reload the DateTimePicker UI Element on the page. You can do this with the DateTimePicker.refresh() method:

// Load DateTimePicker Element:
const DateTimePicker = CronofyElements.DateTimePicker(optionsObject);

// Refresh the DateTimePicker Element:
DateTimePicker.refresh();
update()  #

Should you need to update the options for any Element, you can reload them with the .update() method (this requires you to have saved your Element instance to a variable beforehand):

// Load DateTimePicker Element:
const DateTimePicker = CronofyElements.DateTimePicker(optionsObject);

// Update the DateTimePicker Element with new options:
DateTimePicker.update(newOptions);

When updating, you do not need to redeclare all the options; you just need to add the ones you want to update.

Note: the DateTimePicker.update() method must be called with an options object, otherwise a warning-level log notification will be fired.

Accessibility #

The Date Time Picker Element has been built with accessibility in mind to help provide a better experience for all users.

Screen reader support

There are additional, visually hidden labels on certain buttons to help provide context to screen reader users.

The translation names for these are:

  • confirm_slot_title: a title for the confirmation dialog
  • nav_previous_month: a title for the “previous” calendar navigtion button
  • nav_next_month: a title for the “next” calendar navigtion button
  • select_time_slot: visually hidden pre-text on the time slot buttons
Keyboard support

Additional keyboard functionality has been built into the timezone dropdown and the calendar grid.

When the timezone option list has focus:

  • The up or down arrow keys will navigate through the list
  • The Enter key will select a timezone
  • The Esc key will close the timezone dropdown

When the calendar grid has focus:

  • The up, down, left and right arrow keys will navigate through the available days. Unavailable days will be skipped.
  • The Enter key will select a day and move the focus to the first option in the time slots list.