Using the Scheduling Component

With the Scheduling Component, you can create a unique Scheduling Page to book different types of events for different purposes. In this tutorial, you'll learn how to do the following tasks:

Create one-time invitations.
Skip the booking form.
Arrange components in composable mode.
Customize event handlers.

App versus Composable mode

The Scheduler UI Components support two configuration modes: app and composable.

The default mode is app. It allows the Scheduling Component to render all sub-components by default. You can embed the pre-built components in your application with the minimum configuration.

The composable mode enables you to customize how each sub-component is arranged and rendered in the UI. You can use sub-components as standalone components.

For more information on each component, see the Scheduling Component reference documentation.

Custom event handlers

Event handlers in Scheduler respond to user actions and dictate the operation that follows. Each event handler is associated with a specific type of event, such as timeslotSelected, timeslotConfirmed, dateSelected, and monthChanged.

The eventOverrides property allows you to customize the default event handlers so that you can implement specific logic or behavior for end user actions in Scheduler. For example, you can add or remove steps in your booking flow, track user interactions for analytics, update available time slots when the user selects a different date, and more.

For a use case example, see Customize event handlers.

Before you begin

Before you begin, do the following:

Create one-time invitations

You can use the date and time properties to create and display one-time invitations. These invitations have no date or time selected, and guests can book the event by entering their contact information.

The following example configures the default Scheduling Page state (defaultSchedulerState) to show the booking form with a pre-selected time. It also disables the Back button, so the end user can’t go back to the time slot selection page.

HTML/Vanilla JS
React

<html>
  <head>
    <script type="module" src="https://unpkg.com/@nylas/web-elements@latest"></script>
  </head>

  <body>
    <nylas-scheduling />
    <script type="module">
      const nylasScheduling = document.querySelector('nylas-scheduling');

      // Create one-time invitation
      nylasScheduling.showBookingForm = true
      nylasScheduling.selectedTimeslot = {
        start_time: new Date('2024-02-22T22:12:53+0000'),
        end_time: new Date('2024-02-23T22:14:53+0000')
      }
    </script>
  </body>
</html>

<NylasScheduling
  mode="app"
  // Set the scheduler configuration ID if using public configuration (`requires_session_auth=false`)
  configurationId={"<SCHEDULER_CONFIG_ID>"}
  // OR set the scheduler session ID if using private configuration (`requires_session_auth=true`)
  // sessionId={"<SCHEDULER_SESSION_ID>"} 
  defaultSchedulerState={{
      showBookingForm: true,
      selectedTimeslot: {
        start_time: new Date('2024-02-22T22:12:53+0000'),
        end_time: new Date('2024-02-23T22:14:53+0000')
      }
  }}
/>

Skip the booking form

You can set the eventOverrides property to override the timeslotConfirmed event's default behavior, which proceeds to the booking form page.

The following example skips the booking form page and confirms the booking after the time confirmation step. After the booking is confirmed, the Scheduling Page displays a "thank you" message.

HTML/Vanilla JS
React

<html>
  <head>
    <script type="module" src="https://unpkg.com/@nylas/web-elements@latest"></script>
  </head>

  <body>
    <nylas-scheduling />
    <script type="module">
      const nylasScheduling = document.querySelector('nylas-scheduling');

      // Create event overrides
      nylasScheduling.eventOverrides={{
        timeslotConfirmed: (event, connector) => {
        event.preventDefault()
        connector.scheduler.bookTimeslot({
          primaryParticipant: {
            name:"John Smith",
            email:"john.smith@example.com"
          }
        })
      }}}
    </script>
  </body>
</html>

<NylasScheduling 
  configurationId="<SCHEDULER_CONFIG_ID>"
  // OR set the scheduler session ID if using private configuration (`requires_session_auth=true`)
  // sessionId="<SCHEDULER_SESSION_ID> 
  mode="app"
  eventOverrides={{
    timeslotConfirmed: (event, connector) => {
      event.preventDefault()
      connector.scheduler.bookTimeslot({
        primaryParticipant: {
          name:"John Smith",
          email:"john.smith@example.com"
        }
      })
    }
  }}
/>

Arrange components in `composable` mode

You can use the composable mode to customize how each sub-component is arranged and rendered in the UI.

The following example creates a date selection page with two panels on either side of the component. The panel to the left contains the date picker and locale switch sub-components, and the panel to the right displays the time slot picker.

HTML/Vanilla JS
React

<nylas-scheduling mode="composable">
  <div class="select-date-page">
    <div class="left-panel">
      <nylas-date-picker></nylas-date-picker>
      <nylas-locale-switch></nylas-locale-switch>
    </div>
    <div class="right-panel">
        <nylas-timeslot-picker></nylas-timeslot-picker>
    </div>
  </div>
</nylas-scheduling>

<NylasScheduling mode="composable">
  <div class="select-date-page">
    <div class="left-panel">
      <nylas-date-picker></nylas-date-picker>
      <nylas-locale-switch></nylas-locale-switch>
    </div>
    <div class="right-panel">
        <nylas-timeslot-picker></nylas-timeslot-picker>
    </div>
  </div>
</NylasScheduling>

Customize event handlers

You can use the eventOverrides property to customize the default event handlers:

The Partial object allows you to override one, some, or all of the event handlers.
Custom event handlers return a Promise for asynchronous operations. This is useful when you want to fetch data, update UI components, or perform any tasks that require the outcome of other operations.
The NylasSchedulerConnectorInterface object allows custom event handlers to interact with the Nylas Scheduler API for more complex operations. The NylasSchedulerConnector exposes the following API interactions:
- bookTimeslot
- getAvailability
- cancelBooking
- rescheduleBooking

The following code overrides the default timeslotConfirmed handler.

HTML/Vanilla JS
React

<nylas-scheduling id="scheduler" eventOverrides='{"timeslotConfirmed": timeslotConfirmedHandler}'>
</nylas-scheduling>

<script>
document.addEventListener('DOMContentLoaded', function() {
  const schedulerElement = document.getElementById('scheduler');

  // Define the handler for timeslotConfirmed
  function timeslotConfirmedHandler(event, nylasConnector) {
    console.log("Timeslot confirmed event fired!");

    // Custom logic for booking the timeslot using the connector
    // Assuming 'bookTimeslot' is a method available in the connector
    nylasConnector.bookTimeslot(event.detail).then(bookingResponse => {
      console.log("Booking completed:", bookingResponse);
    }).catch(error => {
      console.error("Booking failed:", error);
    });

    // Sending data to analytics service
    sendToAnalyticsService(event.detail);
  }

  // Function to send data to analytics service
  function sendToAnalyticsService(data) {
    // Implement your analytics logic here. For example:
    console.log("Sending data to analytics service:", data);
    // Here you would typically make an API call or use a client-side analytics library
  }

  // Assign the handler to the scheduler's eventOverrides property
  schedulerElement.eventOverrides = { timeslotConfirmed: timeslotConfirmedHandler };
});
<script/>

<NylasScheduling 
  sessionId="<SESSION_ID>" 
  mode="app"
  eventOverrides={
    timeslotConfirmed: (event, connector) => {
      event.preventDefault()
      connector.scheduler.bookTimeslot({
        primaryParticipant: {
          name:"John Smith",
          email:"john.smith@example.com"
        }
      })
    }
  }
/>