Version:
Only show these results:

Using the Scheduling Component

With the Scheduling Component, you can create a unique Scheduling Page to book different types of events for different purposes. This page explains how to do the following tasks:

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.

You can use composable mode 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:

  1. Sign up for a Nylas account.
  2. Sign in to the v3 Dashboard and create a Nylas application.
  3. Generate an API key for your application and save it.
  4. Create a grant and save the grant ID.
  5. Install the Scheduler UI Components and set up Scheduler.

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>
  <body>
    <nylas-scheduling />
    <script type="module">
      
      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduling/nylas-scheduling.es.js";

      defineCustomElement();

      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>
  <body>
    <nylas-scheduling />
    <script type="module">
      
      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduling/nylas-scheduling.es.js";

      defineCustomElement();
      
      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"
        }
      })
    }
  }}
/>

Pre-fill the booking form

You can set the bookingInfo property to pre-fill the booking form. For example, you can pre-fill the guest's name and email to make the booking process faster and more convenient.

<html>
  <body>
    <nylas-scheduling/>
    <script type="module">

      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduling/nylas-scheduling.es.js";
      
      defineCustomElement();  
      
      const nylasScheduling = document.querySelector('nylas-scheduling');

      // Set the bookingInfo prop
      nylasScheduling.bookingInfo = {
        primaryParticipant: {
          name: 'John Doe',
          email: 'johndoe@example.com',
        },
        guests: [{
          name: 'Jane Smith',
          email: 'janesmith@example.com'
        }],
        additionalFields: {
          additional_email: {
            value: 'xyz@example.com',
            type: 'email',
          },
          phone_number: {
            value: '1234567890',
            type: 'phone_number'
          }
        },
      };
    </script>
  </body>
</html>   
const bookingInfoData = {
  primaryParticipant: {
    name: 'John Doe',
    email: 'johndoe@example.com',
  },
  guests: [{
    name: 'Jane Smith',
    email: 'janesmith@example.com'
  }],
  additionalFields: {
    additional_email: {
      value: 'xyz@example.com',
      type: 'email',
    },
    phone_number: {
      value: '1234567890',
      type: 'phone_number'
    }
  ,
};

<NylasScheduling
  bookingInfo={bookingInfoData}
/>

For hosted Scheduling Pages, you can pass query parameters in the URL to pre-fill the booking form.

Disable the feedback option

By default, Scheduling Pages include a feedback option that allows users to provide feedback or report errors to Nylas. If you want to hide the feedback button in the UI, set enableUserFeedback to false for the Scheduling Component.

<html>
  <body>
    <nylas-scheduling enable-user-feedback="false"/>
      
    <script type="module">
      // ...Scheduling Page configuration
    </script>
  </body>
</html>   
 <NylasScheduling enableUserFeedback={false}
  ...
/>

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.

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

<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
    const timeslot = event.detail;
    const bookingData = {
       primaryParticipant: {name: "John Smith", email: "john.smith@example.com"}
       timezone: "America/New_York", // optional
       guests: [{name: "Jane Doe", email: "jane.doe@example.com"}], // optional
       additionalFields: {"key": {value: "", type: ""}, // optional
       timeslot
    };
    nylasConnector.scheduler.bookTimeslot(bookingData).then(bookingResponse => {
      console.log("Booking completed:", bookingResponse);
    }).catch(error => {
      console.error("Booking failed:", error);
    });
    // Sending data to analytics service
    sendToAnalyticsService(event.detail);
  }
});
<script/>   
<NylasScheduling
 eventOverrides={
   timeslotConfirmed: async (event, connector) => {
     const timeslot = event.detail;
     const bookingData = {
       primaryParticipant: {name: "John Smith", email: "john.smith@example.com"}
       timezone: "America/New_York", // optional
       guests: [{name: "Jane Doe", email: "jane.doe@example.com"}], // optional
       additionalFields: {"key": {value: "", type: ""}, // optional
       timeslot
     };
     connector.scheduler.bookTimeslot(bookingData).then(bookingResponse => {
       console.log("Booking completed:", bookingResponse);
     }).catch(error => {
       console.error("Booking failed:", error);
     });
   }
 }
 ... // Include additional props as needed
/>