Upgrade Guide - v0 to v1 BETA

The release of UI Elements v1.0.0 marks an important transition from prototype to full-fledged product, and we’d like to thank all of you who have adopted the Elements in their alpha phase. Thanks to the efforts of those early adopters we have been able to shape the Elements into a robust suite suitable for use in any application environment. The feedback from users has been overwhelmingly positive, and has opened our eyes to use cases far beyond our initial plans.

The changes from v0 to v1 are designed to enable a more flexible and customizable set of Elements, as well as providing a solid platform for future expansion. The new config option standardizes many of the more ad-hoc options from early versions, and all style-related options have been moved to the styles option. The callback format has also been amended to support multiple notification types from a single Element, paving the way for richer and deeper integrations.

For this launch of v1.0.0, deprecated option names will still function but will raise a “deprecated” warning in the console. We recommend updating to the new option names as soon as possible. There are some changes that will impact pre-v1 implementations more severely (e.g. tzid being a required field for Availability Rules Element and the changes in the callback notification formats).

Upgrading from v0 to v1 #

Agenda View #

  • token is now element_token.
  • target is now target_id.

Layout and styling options have been consolidated within the styles option:

  • colors is now styles.colors.

See the full details in the Agenda View documentation.

Slot Picker #

  • token is now element_token.
  • target is now target_id.
  • query is now availability_query.

The confirm option has been replaced by the config.mode option. confirm accepted a true/false value, but config.mode expects to receive a string corresponding to the desired mode. confirm: true should be replaced with config: { mode: "confirm" } (although this is the default behaviour and therefore optional), and confirm: false should be replaced with config: { mode: "no_confirm" }.

Layout and styling options have been consolidated within the styles option:

  • padding is now styles.padding.

The callback response now follows the standardized notification format. Prior to v1, the Slot Picker Element would return only the selected slot object.

Previous response:
{
    "start": "2024-12-06T09:00:00Z",
    "end": "2024-12-06T11:00:00Z",
    "participants": [
        { "sub": "acc_5ba21743f408617d1269ea1e" },
        { "sub": "acc_64b17d868090ea21640c914c" }
    ]
}
New response:
{
    "notification": {
        "type": "slot_selected",
        "slot": {
            "start": "2024-12-06T09:00:00Z",
            "end": "2024-12-06T11:00:00Z",
            "participants": [
                { "sub": "acc_5ba21743f408617d1269ea1e" },
                { "sub": "acc_64b17d868090ea21640c914c" }
            ]
        }
    }
}

Use the notification.type value to filter the notifications in your callback function.

See the full details in the Slot Picker documentation.

Availability Rules #

  • token is now element_token.
  • target is now target_id.
  • tzid is now a required field.

The new config option has consolidated some options that were previously top-level options:

  • start_time is now config.start_time.
  • end_time is now config.end_time.
  • duration is now config.duration. This option is now limited to values of either 15, 30, or 60.

See the full details in the Availability Rules documentation.

Availability Viewer #

  • token is now element_token.
  • target is now target_id.
  • query is now availability_query.

The new config option has replaced the extras option, and has also acquired some options that were previously top-level options:

  • start_time is now config.start_time.
  • end_time is now config.end_time.
  • interval is now config.interval.
  • duration is now config.duration This option is now limited to values of either 15, 30, or 60.
  • extras.mode is now config.mode. The default mode value has changed from “default” to “confirm”.
  • extras.max_selection_count is now config.max_selection_count.

The callback response now follows the standardized notification format. Prior to v1, the Availability Viewer Element would return only the selected slot object (when not in multi_select mode). Callback notification for multi_select mode remain unchanged, as they already adhered to the notification pattern.

Previous response:
{
    "start": "2024-12-06T09:00:00Z",
    "end": "2024-12-06T11:00:00Z",
    "participants": [
        { "sub": "acc_5ba21743f408617d1269ea1e" },
        { "sub": "acc_64b17d868090ea21640c914c" }
    ]
}
New response:
{
    "notification": {
        "type": "slot_selected",
        "slot": {
            "start": "2024-12-06T09:00:00Z",
            "end": "2024-12-06T11:00:00Z",
            "participants": [
                { "sub": "acc_5ba21743f408617d1269ea1e" },
                { "sub": "acc_64b17d868090ea21640c914c" }
            ]
        }
    }
}

See the full details in the Availability Viewer documentation.

Calendar Sync #

  • token is now element_token.
  • target is now target_id.

See the full details in the Calendar Sync documentation.