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.

https://elements.cronofy.com/js/CronofyElements.v1.61.1.js

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";

Using UI Elements #

With the exception of the Calendar Sync element which is used to enroll users, each UI Element uses an authentication token called an Element Token. Element tokens are short-lived tokens with specific scopes, which are used to avoid exposing the much more powerful API access tokens in public.

Once you have connected a user, you can create an Element token for them and pass it to your front-end code to initialize a UI Element.

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 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:
YourElement.update(newOptions);

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:
YourElement.refresh();

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 #

• ar Arabic
• cs Czech
• cy Welsh
• de German
• en US English (default)
• es Spanish
• fr French
• fr-CA Canadian French
• he Hebrew
• it Italian
• ja Japanese
• nl Dutch
• pl Polish
• pt-BR Brazilian Portuguese
• ru Russian
• sv Swedish
• tr Turkish
• zh-CN Simplified Chinese

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

Locale modifiers #

Some locales have multiple valid options for localization. Locale modifiers allow you to opt into using these variations rather than the defaults. The modifiers block can be passed to all instances of an element, and will be applied when a user in the root locale views the element.

For example, to have Japanese (ja) users see dates in the ‘western’ format:

    locale_modifiers: {
      "ja": { "dates": "western" }
    }

Current values are: #

2021年 8月 23日 (月)

Universal options #

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

data_center optional  #

Default value is us.

config.logs optional  #

• 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  #

element_token required  #

styles optional  #

styles.prefix optional  #

target_id required  #

locale_modifiers optional  #

translations optional  #

callback optional  #

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

For example, here is the notification showing the API error when we have made an Availability Query which includes a sub we don’t have access to:

{
  "notification": {
    "type": "error",
    "element": "Availability Viewer",
    "message": "There was a problem with your availability query.",
    "url": "https://docs.cronofy.com/developers/ui-elements/availability-viewer/#availability_query",
    "errors": {
      "participant[sub=acc_600eb48068ed0f33f6d4abad]": [
        {
          "key": "errors.not_recognized",
          "description": "not recognized"
        }
      ]
    }
  }
}