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:
- Sign up for a Nylas account.
- Sign in to the v3 Dashboard and create a Nylas application.
- Generate an API key for your application and save it.
- Create a grant and save the grant ID.
- 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>
<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>
<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.
<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. TheNylasSchedulerConnector
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
/>