Availability Viewer

The Availability Viewer Element is an interactive week-based display of availability. It converts an availability query into a grid of days with free/busy times displayed. If the requested available periods span more than one week, the user can browse those weeks with the provided navigation buttons. Users can pre-select an available slot for any available block of time, and then confirm that slot with a button-click. 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-availability-viewer"></div>
<script src="https://elements.cronofy.com/js/CronofyElements.v1.7.15.js"></script>
<script>
    CronofyElements.AvailabilityViewer({
        element_token: "{ELEMENT_TOKEN}",
        target_id: "cronofy-availability-viewer",
        availability_query: {
            participants: [
                {
                    required: "all",
                    members: [
                        { sub: "acc_12345678" },
                        { sub: "acc_87654321" }
                    ]
                }
            ],
            required_duration: { minutes: 60 },
            available_periods: [
                { start: "2019-11-20T09:00:00Z", end: "2019-11-20T17:00:00Z" },
                { start: "2019-11-21T09:00:00Z", end: "2019-11-21T17:00:00Z" },
                { start: "2019-11-22T09:00:00Z", end: "2019-11-22T17:00:00Z" },
                { start: "2019-11-23T09:00:00Z", end: "2019-11-23T17:00:00Z" }
            ],
        },
        config: {
            start_time: "09:00",
            end_time: "15:30",
            interval: 15
        },
        styles: {
            prefix: "custom-name"
        },
        callback: notification => console.log("callback", notification),
    });
</script>

Element permissions #

availability is required when generating the Element Token.

Element options #

element_token required  #

The Element Token the Availability Viewer 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.

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. Your application should ignore notifications it does not understand as new ones may be added in future.

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": "2019-11-20T09:00:00Z",
            "end": "2019-11-20T11:00:00Z",
            "participants": [
                { "sub": "acc_12345678" },
                { "sub": "acc_87654321" }
            ]
        }
    }
}
slot_added

Sent by the Element when in the multi_select mode after the user has added a slot to their selection.

{
    "notification": {
        "type": "slot_added"
        "slot": {
            "start": "2019-11-20T09:00:00Z",
            "end": "2019-11-20T11:00:00Z",
            "participants": [
                { "sub": "acc_12345678" },
                { "sub": "acc_87654321" }
            ]
        }
    },
    "slots": [
        {
            "start": "2019-11-20T09:00:00Z",
            "end": "2019-11-20T11:00:00Z",
            "participants": [
                { "sub": "acc_12345678" },
                { "sub": "acc_87654321" }
            ]
        }
    ]
}

slots includes all selected slots, including the one that was selected to generate the notification.

slot_removed

Sent by the Element when in the multi_select mode after the user has removed a slot from their selection.

{
    "notification": {
        "type": "slot_removed"
        "slot": {
            "start": "2019-11-20T09:00:00Z",
            "end": "2019-11-20T11:00:00Z",
            "participants": [
                { "sub": "acc_12345678" },
                { "sub": "acc_87654321" }
            ]
        }
    },
    "slots": []
}

slots includes all selected slots and so will not include the one that was removed to generate the notification.

availability_query required  #
Object that matches a valid Cronofy Availability request.

config optional  #
Use this object to add further limits to the availability display:

config.start_time optional  #
Hide any available slots before this time. Defaults to “09:00”.

config.end_time optional  #
Hide any available slots after this time. Defaults to “17:30”.

config.interval optional  #
When selecting a slot, the available options are staggered by this amount. Defaults to 15.

config.mode optional  #
The Availability Viewer element has several “modes” it can operate in:

  • confirm (default)
  • no_confirm
  • multi_select

When in confirm mode, clicking a slot once marks it as selected. Clicking a selected slot confirms the selection and fires the provided callback with a single slot object.

When in no_confirm mode, the “confirmation” step is skipped. Clicking any slot will fire the callback.

When in multi_select mode, you can select as many slots as you like. Every time a slot is clicked, the callback is fired with an object in the following format:

{
  "notification": {
        "type": "slot_removed",
        "slot": {
            // The details of the clicked slot.
        }
    }
    "slots": [
        // An array of all currently selected slots.
    ]
}

In this scenario, notification.type is either slot_added or slot_removed depending on whether the most recently clicked slot has be selected or deselected.

config.max_selection_count optional  #
When config.mode is set to multi_select, it is possible to limit the amount of slots that can be selected at any one time. If config.mode is set to anything other than multi_select, this parameter will be ignored. Accepts an Integer or false. false explicitly applies no limit, and is the default value.

config.bounds_control optional  #
If config.bounds_control option is set as true, users can dynamically change the start and end times of the Availability Viewer element. This is handled by a start/end time modal activated by clicking a cog icon that appears above the times label column. The default value is false.

config.slot_selection optional  #
Controls the slot-selection behavior. Takes a string with two possible values: available or unrestricted. The default of “available” means only available slots can be selected. Setting this option to “unrestricted” will allow any slot (available and unavailable) to be selected.

In both instances, the config.mode will still be honored. So if the mode is no_confirm, the notification callback will be fired every time a slot is clicked, but if the mode is confirm (the default) then the notification will only be fired when a slot is confirmed (the second click after it has been selected).

When this parameter is set to unrestricted, a boolean “available” attribute is added to the slot objects that are returned by the notification (notification.slot.available). This reflects the availability of the slot (true for available, false for unavailable).

Note, when the Availability Viewer is loaded in “unrestriced” mode, the “hover-slot” indicator will display the full duration (e.g. 60mins, if a duration of 60 has been set) when hovering unavailable slots, and the tooltip will switch from displaying “unavailable” to showing the start/end times for the slot (matching the behaviour currently show for available slots). There will be a corresponding --unavailable modifier added to the hover-slot class.

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

Default value is us.

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

Supported locales (languages) for the UI Elements are:

  • Dutch - nl
  • English - en (default)
  • French - fr
  • German - de
  • Italian - it
  • Spanish - es

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).

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__slot. Defaults to the name of the element (e.g. "AvailabilityViewer").

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. available: "tomato")

  • hairline - gridlines. Defaults to #D8D8D8
  • primary - button background color. Defaults to #15B3D6
  • available - available slot background color. Defaults to #E2FAC8
  • availableHover - available slot when hovered. Defaults to available darkened by 10%
  • availableActive - available slot when active. Defaults to available darkened by 20%
  • unavailable - unavailable slot background color. Defaults to #FFFFFF
  • unavailableHover - unavailable slot when hovered. Defaults to unavailable darkened by 10%
  • unavailableActive - unavailable slot when active. Defaults to unavailable darkened by 20%

tzid optional  #
The time zone that the Availability Viewer will be rendered in. Must be a known time zone identifier from the IANA Time Zone Database. If tzid is declared, the time zone is displayed in the footer of the Element. By default, the Availability Viewer will render in the time zone of the user’s browser.

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

Styling #

Cronofy UI Elements come with built-in CSS that control their layout (as well as adding a generic theme with placeholder colors and spacing). You can specify any style rule you like in your own stylesheet.

To be sure to avoid specificity issues with CSS, make sure any custom selectors you add are preceded by .PREFIX. For example, if your prefix is ABC, you would target the button styles with this selector:

.ABC .ABC__button {
    /* your button styles go here */
}

Element classes #

PREFIX default is AvailabilityViewer.

  • {PREFIX}__body
  • {PREFIX}__button
  • {PREFIX}__column-body
  • {PREFIX}__column-body--empty
  • {PREFIX}__column-header
  • {PREFIX}__column-header__day
  • {PREFIX}__column-header__day
  • {PREFIX}__column-header__day
  • {PREFIX}__column-header__day
  • {PREFIX}__column-header__day
  • {PREFIX}__column-header__day
  • {PREFIX}__column-header__day
  • {PREFIX}__column-header__day
  • {PREFIX}__column-header__ordinal
  • {PREFIX}__column-message
  • {PREFIX}__day-headers
  • {PREFIX}__error
  • {PREFIX}__error-icon
  • {PREFIX}__error-text
  • {PREFIX}__example
  • {PREFIX}__footer
  • {PREFIX}__grid
  • {PREFIX}__grid-columns
  • {PREFIX}__grid-column
  • {PREFIX}__hover-positioner
  • {PREFIX}__hover-positioner--main
  • {PREFIX}__hover-positioner--tooltip
  • {PREFIX}__hover-slot
  • {PREFIX}__hover-slot--available
  • {PREFIX}__hover-slot--unavailable
  • {PREFIX}__icon
  • {PREFIX}__legend
  • {PREFIX}__legend-item
  • {PREFIX}__legend-label
  • {PREFIX}__loading
  • {PREFIX}__loading-icon
  • {PREFIX}__loading-text
  • {PREFIX}__month-label
  • {PREFIX}__month-labels
  • {PREFIX}__navigation
  • {PREFIX}__preloading
  • {PREFIX}__preloading-icon
  • {PREFIX}__preloading-text
  • {PREFIX}__selected-slot
  • {PREFIX}__selected-slot__button
  • {PREFIX}__selection-mask
  • {PREFIX}__selection-positioner
  • {PREFIX}__slot-background
  • {PREFIX}__slot-background--available
  • {PREFIX}__slot-background--unavailable
  • {PREFIX}__slot-tooltip
  • {PREFIX}__slot-tooltip-background
  • {PREFIX}__slot-tooltip-label
  • {PREFIX}__tick-mark
  • {PREFIX}__timeline
  • {PREFIX}__timeline--hour
  • {PREFIX}__timelines
  • {PREFIX}__timezone
  • {PREFIX}__time-label
  • {PREFIX}__time-labels
  • {PREFIX}__time-select__trigger
  • {PREFIX}__time-select__trigger-icon
  • {PREFIX}__time-text
  • {PREFIX}__tooltip-positioner
  • {PREFIX}__tooltip-positioner--available
  • {PREFIX}__tooltip-positioner--unavailable
  • {PREFIX}__week
Search