Calendar Sync

The Calendar Sync element is an interactive display of your profile synchronization status.

If you have not yet connected any profiles, it will show you authorization links for supported providers (Google, iCloud, Office 365, Outlook, and Exchange). If you have already connected one or more profiles, it will show you a list of those profiles along with the synchronization status for each profile (“active”, “pending” or “disconnected”). If the status is “disconnected” (meaning that a relink is required) then the element will also display a relink button. You can also add new accounts and disconnect existing ones within the element’s UI.

Demo #

Example initialization #

<div id="cronofy-calendar-sync"></div>
<script src="https://elements.cronofy.com/js/CronofyElements.v1.7.9.js"></script>
<script>
    CronofyElements.CalendarSync({
        target_id: "cronofy-calendar-sync",
        authorization: {
            redirect_uri: "https://example.org/oauth/redirect",
            client_id: "XXX",
            scope: "read_only"
        },
        styles: {
            prefix: "CalendarSync"
        }
    });
</script>

Element permissions #

account_management is required when generating the Element Token.

Adding profiles #

The Calendar Sync element includes the ability to add new calendar accounts. Users start the authorization flow by clicking one of the authorization links (exposed by clicking the “Add calendar account” button). When the process is complete, the user is returned to the redirect_uri with a code included as a URL parameter. This code should then be used to request an access token.

CalendarSync options #

element_token optional  #
The Element Token the Calendar Sync Element will use to communicate with Cronofy.

Not required if the Element is activated in demo mode, or the user is connecting for the first time.

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

authorization required  #
An object containing the params needed to create an authorization link (used when connecting new profiles). redirect_uri, client_id, and scope are required, but every param you add here will be added to the query string of the generated authorization URL. Full details can be found in the Authorization section.

authorization.redirect_uri required  #
The HTTP or HTTPS URI you wish the user’s authorization request decision to be redirected to. Full details can be found here: redirect_uri.

authorization.client_id required  #
The client_id issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client.

authorization.scope required  #
The scope of the privileges you want the eventual access_token to grant. Full details can be found here: redirect_uri.

authorization_url optional  #
It is possible to explicitly declare your own authorization url, and bypass the built-in authorization link. The user-selected provider will be appended to the authorization_url as a query string (for example, when clicking the link to add a Google provider, the following will be appended to the url: ?provider_name=google).

Declaring an authorization_url removes the need for the authorization options outlined above, although any authorization options you do declare will be appended as query parameters to the authorization_url.

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

Default value is us.

locale optional  #
The Calendar Sync element 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

single_profile optional  #
Limits the number of profiles that can be added using the Element to 1. Will still display all linked profiles (no matter how many there are) and will allow those profiles to be edited/removed, but will prevent any more from being added. Defaults to false.

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

{
    "notification": {
        "type": "notification_type"
    },
    "userinfo": {
        "sub": "acc_5700a00eb0ccd07000000000",
        "email": "janed@company.com",
        "name": "Jane Doe",
        "zoneinfo": "Europe/London",
        "cronofy.type": "account",
        "cronofy.data": {
            "authorization": {
                "scope": "read_write"
            },
            "profiles": [
                {
                    "provider_name": "google",
                    "profile_id": "pro_n23kjnwrw2",
                    "profile_name": "example@cronofy.com",
                    "profile_connected": true,
                    "profile_initial_sync_required": true,
                    "profile_calendars": [
                        {
                            "calendar_id": "cal_n23kjnwrw2_jsdfjksn234",
                            "calendar_name": "Home",
                            "calendar_readonly": false,
                            "calendar_deleted": false,
                            "calendar_primary": true,
                            "permission_level": "sandbox"
                        },
                        {
                            "calendar_id": "cal_n23kjnwrw2_n1k323nkj23",
                            "calendar_name": "Work",
                            "calendar_readonly": true,
                            "calendar_deleted": true,
                            "calendar_primary": false,
                            "permission_level": "sandbox"
                        }
                    ]
                }
            ]
        }
    }
}

The object will always include a notification object and a current userinfo object. The notification object will always have 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.

profile_revoked

Alongside the type of profile_revoked will be the details of the profile from before its revocation:

{
    "notification": {
        "type": "profile_revoked",
        "profile": {
            "provider_name": "apple",
            "profile_id": "pro_fe145c37de",
            "profile_name": "example@cronofy.com",
            "profile_connected": true,
            "profile_initial_sync_required": false,
            "profile_calendars": [
                {
                  "calendar_id": "cal_fe145c37de_3nkj23wejk1",
                  "calendar_name": "Bank Holidays",
                  "calendar_readonly": true,
                  "calendar_deleted": false,
                  "calendar_primary": false,
                  "permission_level": "sandbox"
                }
            ]
        }
    },
    "userinfo": {
        ...
    }
}

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

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 - horizontal rules and link borders. Defaults to "#D8D8D8"
  • primary - button background color. Defaults to "#15B3D6"

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

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

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

  • {PREFIX}__title
  • {PREFIX}__profiles
  • {PREFIX}__profile
  • {PREFIX}__profile-name
  • {PREFIX}__providers
  • {PREFIX}__provider-icon
  • {PREFIX}__provider-auth
  • {PREFIX}__provider-auth-text
  • {PREFIX}__provider-icon--google
  • {PREFIX}__provider-icon--apple
  • {PREFIX}__provider-icon--outlook
  • {PREFIX}__provider-icon--office365
  • {PREFIX}__provider-status
  • {PREFIX}__status--active
  • {PREFIX}__status--inactive
  • {PREFIX}__status-label
  • {PREFIX}__status-icon
  • {PREFIX}__status-icon--tick
  • {PREFIX}__status-icon--reload
  • {PREFIX}__status-icon--pending
  • {PREFIX}__loading-wrapper
  • {PREFIX}__footer
  • {PREFIX}__edit-toggle
  • {PREFIX}__edit-toggle-button
  • {PREFIX}__edit-toggle-icon
  • {PREFIX}__edit-toggle-text
  • {PREFIX}__add-toggle
  • {PREFIX}__add-toggle-button
  • {PREFIX}__add-toggle-icon
  • {PREFIX}__add-toggle-text
  • {PREFIX}__remove
  • {PREFIX}__remove-icon
Search