UI Elements

UI Elements are JavaScript components that provide user interface overlays to various Cronofy API endpoints.

Installation #

All the UI Elements accept some global options, and each have additional Element-specific options. For all Elements, load them into your app by including the source .js file into your page.


Using npm #

If you prefer, you can install the UI Elements with npm.

npm install --save cronofy-elements

After installing, you will need to import the Elements into your JavaScript:

import * as CronofyElements from "cronofy-elements";

Initialize the Element #

Once you have included the UI Element in your project (either by importing from npm or including the source file), you can initialize the desired Element using the corresponding method and passing in an options as an object. For example, to load the “Agenda” Element, your script would look like this:

CronofyElements.Agenda({ token: "YOUR_TOKEN", target: "cronofy-agenda" });

Updating options #

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 Element:
const YourElement = CronofyElements.AvailabilityViewer(optionsObject);

// Update the Element with new options:

When updating, you do not need to redeclare all the options; you just need to add the ones you want to update. For instance, the AvailabilityViewer Element accepts several options, but when you’re updating the options, you only need to include the options that are changing.

Refreshing a UI Element #

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

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

// Refresh the Element:

Context #

The context is an object representing useful context about the users browser.

Currently the only key available is the tzid, the timezone ID being used by the element. If no tzid is set within the options object for a UI Element, this will return the browser’s timezone.

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

// Grab the tzid:
const tzid = YourElement.context.tzid;

Browser support #

UI Elements are officially supported on the last two versions of Chrome, Firefox, Safari, and Edge.

Translations and localization #

Each of the elements support localization (e.g. locale: "fr" to load in French) via the locale initialization parameter.

Supported locales #

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

Locales can be customized or added to by following the instructions for customizing translation strings

Universal options #

These options can be applied to any of the UI Elements. See the individual element pages for element-specific options.

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.

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

element_token required  #
The Element Token used by the element to communicate with Cronofy.

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

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

translations optional  #
To override either a locale or a particular string, pass in a translations object here. See the individual element pages for the element-specific context, and you can find instructions for customizing translation strings on the UI Element Customizations page.

callback optional  #
A function to be called when an action has occurred within a UI Element. Receives an object in the format:

    "notification": {
        "type": "notification_type"
Log notifications

All log events (info, warn, and error) fire a corresponding notification. The notification.type will match the log-level. Each of these notifications will include element, message, and url values. notification.element will be the name of the UI Element that fired the notification. notification.message will match the message passed to the logging function. notification.url will be a link to a relevant section of the UI Elements’ documentation.

For example, when running the Slot Picker with the demo option set to true, the following notification will be fired:

    "notification": {
        "type": "error",
        "element": "Slot Picker",
        "message": "You are running in demo mode. No API requests will be made",
        "url": "https://docs.cronofy.com/developers/ui-elements/",
        "errors": {}

The error notification type contains an errors property. If the error has a response body (for example, in the case of 422 errors from the API) then that object will be included here. If there is no body to show, this field will be an empty object.

In This Section