This article was sponsored by Acuity Scheduling. Thank you for supporting the sponsors who make SitePoint possible.
Cards on the table: it has been quite a while since I learned to drive. I can’t quite remember how I found my instructor, but I’m pretty sure it wasn’t through a website. What I do know is that booking a lesson involved a phone call. With my instructor on the road all day, that call usually had to be out-of-hours. The appointments themselves were scheduled by hand in a good old-fashioned diary.
[author_more]
I’m not sure that sort of approach would cut it now. I know that if I were looking, it would be through the web, and like most people I’ve started to take it for granted that I can book things online.
What about the other side of the coin? Managing lessons that way is an inefficient approach. I can only guess how many times my instructor turned up for a lesson to find that the student had left a cancellation message on their answering machine at home.
What we’re going to do in this tutorial, then, is drag our driving instructor into the 21st century by providing a web-based widget for viewing availability and scheduling lessons. Furthermore, we’ll take advantage of Acuity Scheduling to help them manage their diary without resorting to pen and paper.
Before you continue, you might like to see what it is we’re going to build with the online demo or the screenshot below.
The code for this tutorial is available on GitHub.
Looking at the Business
Before we delve into the implementation, let’s look a little closer at the business of operating as a driving instructor.
A driving instructor, of course, has a number of “slots” available in a given day. Driving lessons are, by their very nature, one-to-one, which simplifies things for us a little.
In order to keep things relatively simple, we’ll gloss over certain practicalities. For example, in the real world it would be impossible to begin a lesson at one side of a given city at 3pm, when another finished moments earlier on the other side of the city.
Our availability widget will display a calendar for a given month — defaulting to the current one — which shows, at a glance, which days have some availability. If a user clicks on a specific day, it’ll drill down and display the time slots which are available for that day.
We’ll do this using some of the latest front-end technologies, making our widget highly responsive.
Why Build a Custom Widget?
There are a number of possible reasons why you might decide to build a custom widget, for example:
- You can style it so that it matches the design of your site seamlessly
- You can use whatever front and back-end technologies you already have in place
- A custom widget might be the most appropriate solution if you’d prefer to take payments yourself
- You can keep people on your site as they complete the scheduling process
The Example Code
The code which accompanies this tutorial is available on GitHub. For brevity, we won’t cover all of the code here, so you’ll need to grab a copy regardless of whether you code along, or simply read through as you go.
The example includes a PHP back-end along with the booking widget; we’ll see in a moment why we need a server-side component.
The simplest way to run the example is to use PHP’s built-in web server.
Simply cd into the public directory and enter the following command, substituting the port number if required:
php -S localhost:8000
Introducing Acuity Scheduling
Acuity Scheduling is an online service for managing and scheduling appointments. In the context of our driving instructor, an appointment is a driving lesson, but its applications are far broader.
One of Acuity’s key features is the ability to provide real-time availability information. We can grab that information using the API, to embed into our driving instructor’s website, and then use that as the basis of our scheduling widget.
Acuity offers a whole host of other features, including the ability to take online payments, to manage clients, send e-mail and text message reminders, and much more.
The Acuity Scheduling API
We’re going to integrate with Acuity using their API. In particular, we’ll use three endpoints:
GET /availability/dates gives us a list of dates belonging to a specified month which have one or more available time slots.
GET /availability/times provides a list of available times for a specified day.
POST /appointments is used to actually create (in other words, book) an appointment.
Together, the first two endpoints provide enough information for the end-user to see at a glance what’s available, so that they can choose a suitable slot. Once we have an available date and time, we can collect some information from the learner and make an appointment for them.
Authentication
The Acuity API provides two methods of authentication: OAuth2 and basic HTTP authentication. The former is only really applicable when you’re dealing with multiple Acuity users. For our purposes it’s probably overkill.
To use basic HTTP authentication, however, we’re going to need to proxy the API calls through our back-end.
The reason for this is simple. Basic HTTP authentication requires a username and password that, were we to call the API directly from our JavaScript code, would be exposed. When using the Acuity API the username and password are your user ID and API key respectively, but the principle is exactly the same. This poses an obvious security risk.
The key part of the server-side code for determining availability, which you’ll find in the repository which accompanies this article, is the following:
$app->get( 'api/availability/{period}', function( Request $request, $period ) use ( $app ) {
// Build the URL, incorporating the `appointmentTypeID`.
$query = $request->query->all( ) + [ 'appointmentTypeID' => $app[ 'appointmentTypeID' ] ];
$url = sprintf( '/availability/%s?%s', $period, http_build_query( $query ) );
// Make the request...
$response = $app[ 'client' ]->request( $url );
// If there's an error, write it to the log
if ( $response[ 'status_code' ] !== 200 ) {
$app[ 'logger' ]->error( $response[ 'message' ] );
}
// ... and simply return it
return json_encode( $response );
} )
->assert( 'period', 'dates|times');
The code uses the official PHP SDK. Check the repository to see how the client is constructed, or check out the SDK documentation and the developer documentation.
Although this code is simplified somewhat, for the purposes of this demonstration it should do the trick. All it’s doing, effectively, is “proxying” calls to either /availability/dates or /availability/times — complete with query parameters — to the Acuity Scheduling API, and returning the results in JSON format. It’s also merging in the appointment type ID, which basically tells Acuity what it is we’re trying to find availability for.
This way, we can keep our API Key — which acts as a password — safely on the server, without exposing it in our client-side code.
If you don’t want to use PHP, you don’t have to. There’s an official SDK for Node.js, or if you’re using something else then it ought to be straightforward to call the API from your programming language of choice. Refer to the documentation for more information.
Without further ado, let’s get started.
Getting Set Up
In order to work through this tutorial, you’ll need an account with Acuity Scheduling. Head over to the website to sign up, which only takes a couple of minutes.
The 14-day free trial will work just fine for the purposes of this tutorial, so it needn’t cost you a penny.
Once you have an account, you’ll need to set up a new appointment type. For the purposes of this tutorial that’s pretty straightforward — we’ve only got one type of appointment, and that’s a driving lesson.
While logged into Acuity, go to Business Settings > Appointment Types and click New Type of Service, then fill out the required information. It’s probably simplest to keep the duration at one hour, which is probably what you’d expect for a driving lesson.
There’s additional help if you need it.
If you click on your new appointment type and take a look at the URL, you’ll see that it includes a unique ID. Make a note of this because you’ll need to add it to the configuration file in a moment.
Your next step should be to set your availability. This is essentially where you define your working hours, whether a regular Monday to Friday 9–6, or something a little more irregular. You can do this by selecting Availability under Business Settings.
For the purposes of the example widget we’re building, it’s probably easiest if you set your hours as 9–6, leaving a break for lunch.
The screenshot below shows an example of the working hours set to 9–6pm, with an hour for lunch at 12.
Acuity will ensure that appointments fit within the working hours, so if you specify those as 9am–6pm, the last available slot for a one-hour lesson will be at 5pm. For a day that has all slots available, our widget will look like the screenshot below.
The next step is to find out your API credentials. Go to Business Settings → Integrations, scroll to the bottom of the page and click ”View your API credentials”.
Now that you have the three pieces of required information — your user ID, API key and a new Appointment Type ID — it’s time to get that into a configuration file.
In the repository you’ll find a file named config/__COPY_ME__.json. Take a copy of it, naming it config/dev.json.
The dev part indicates that we’re working in a development environment. In production you’d probably call it production.json or similar.
Fill out this new configuration file, replacing the appropriate entries:
{
"debug": true,
"userId": "YOUR-USER-ID",
"apiKey": "YOUR-API-KEY",
"appointmentTypeID": "APPOINTMENT-TYPE-ID"
}
With this configured, our simple back-end will be able to communicate with the Acuity API to find availability and to schedule appointments.
Note that the PHP code which accompanies this article includes very simple logging; if it gets an error response from the Acuity API then it will log the corresponding message in logs/error.log.
Starting with the Implementation
We’re going to use Vue.js to build the widget itself. In many ways, it’s like a stripped-down version of Angular, specifically for building reactive components. If you’d rather use something else, like Angular for example, then the general principles shouldn’t be all that different.
We’ll also be using Moment.js to make working with dates and times much simpler, Vue Resource for communicating with our back-end and Vue Form for simple form validation.
Install the dependencies:
bower install vue moment vue-resource vue-form --save
You can use npm if you prefer. Just alter the paths accordingly.
Now let’s build the basic page structure. The example uses Twig, and the HTML can be found in views/index.twig.html.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Book a Driving Lesson</title>
<link rel="stylesheet" href="http://ift.tt/1jAc5cP">
<link rel="stylesheet" href="/assets/styles.css">
</head>
<body>
<script src="/bower_components/moment/moment.js"></script>
<script src="/bower_components/vue/dist/vue.js"></script>
<script src="bower_components/vue-resource/dist/vue-resource.js"></script>
<script src="/bower_components/vue-form/vue-form.js"></script>
<script src="/assets/scripts.js"></script>
</body>
</html>
The file public/assets/scripts.js will hold our widget definition, so let’s create the basic structure of that along with a couple of filters, which we’ll use to format dates and times.
Vue.http.options.root = '/api';
Vue.filter('time', function ( hour ) {
if ( hour < 10 ) {
return '0' + hour + ':00';
}
return hour + ':00';
});
Vue.filter('formatDateTime', function( day, format ) {
if ( ! day ) {
return '';
}
return day.format( format )
});
var widget = new Vue({
el : '#availability-widget',
data : {
// . . .
},
ready : function() {
// . . .
},
methods : {
// . . .
}
});
We’ll fill in the following three parts of the widget as we go:
- The data property is used to initialize our data. Specifying the properties here ensures that Vue.js performs the getter/setter process during initialization.
- The
ready() method will perform some initialisation.
methods is a hash of, as you might expect, methods; we’ll define a number of these to take the user from selecting a date to completing their booking.- You can grab a copy of the stylesheet from the repository, or build your own to match your website’s look and feel.
One Step at a Time
Our widget will comprise three “stages”:
- The user selects a date with some availability on a mini-calendar.
- Having selected a date, they select a “slot” from those that are available.
- Once a date and time have been selected, we’ll show that back to the user for confirmation and take some basic information. Once they’ve provided that information, we can call the API to actually schedule the lesson.
Let’s start by building the HTML for the three steps:
<div id="availability-widget">
<ol class="steps">
<li class="col-md-4 active">
<header>Select a Day</header>
</li>
<li class="col-md-4" v-bind:class="{ 'active' : day }">
<header>Choose a Time</header>
</li>
<li class="col-md-4" v-bind:class="{ 'active' : time }">
<header>Confirm Booking</header>
</li>
</ol>
</div>
Notice we’ve wrapped the steps in a <div> with an ID of availability-widget. This matches the el property in our widget code, which means that Vue will bind itself to it in order to implement our widget.
We’ll add the markup for each steps shortly, but for now note that we’re using a class of active to indicate progress; using v-bind we can “activate” the second step when the user has selected a day, and the third step when they’ve selected a time.
Initializing the Data
We’re going to maintain three separate data properties to help keep track of the process of “drilling down” to a specific date and time:
You might wonder why we’re maintaining three separate date properties, given that a Moment instance can encapsulate all three parts. We’re doing this so that we can keep track of what the user has specifically selected.
Let’s initialize our data:
data : {
today : moment(),
weekdays : moment.weekdaysShort(),
calendar : [],
month : moment(),
day : null,
time : null,
hours : [],
bookingForm : {},
learner : {
firstName : null,
lastName : null,
email : null
},
bookingStatus : 'pending'
}
By getting the names of the days of the week from Moment, we’re making it potentially even simpler to internationalize our widget.
Here we’re also initializing properties to hold the calendar definition, the working set of hours, the learner data, the booking form and the status of the booking part of the process.
Finding an Available Day
The first part, then, is to call the Acuity API to find availability for a particular month and render a mini-calendar. When the component is initialised we’ll call it for the current month, but we’ll also need to allow users to navigate between months using the arrow in the calendar header. This is illustrated in the screenshot below.
Let’s start with the HTML:
<li class="col-md-4 active">
<header>Select a Day</header>
<div class="cal">
<div class="header">
<span class="left button" id="prev" v-on:click="previousMonth" v-if="!month.isSame(today, 'month')"> 〈 </span>
<span class="month-year" id="label"> </span>
<span class="right button" id="next" v-on:click="nextMonth"> 〉 </span>
</div>
<table id="days">
<tr>
<td v-for="weekday in weekdays"></td>
</tr>
</table>
<div class="cal-frame" v-if="calendar.length">
<table class="curr">
<tr v-for="row in calendar">
<td v-for="day in row" v-bind:class="{ 'nil' : !day.d, 'today' : day.today, 'past' : day.past, 'available' : day.available }" v-on:click="selectDay(day.d)"></td>
</tr>
</table>
</div>
<div class="loading" v-if="!calendar.length">
<p><img src="/assets/ajax-loader.gif"></p>
<p>Loading dates...</p>
</div>
</div>
</li>
There are a couple of things worth noting here.
The calendar header contains buttons for navigating between months. The back button’s visibility is dependent on whether or not the calendar is displaying the current month.
Each cell (for example, day) on the calendar has one or more CSS classes assigned. The cells that make up the calendar can have one or more of the following “states”:
- An empty cell, used to pad it out into a tabular structure.
- A day in the past.
- The current day.
- A day with availability.
- A day with no availability.
Finally, note that we’re assigning a click handler to the day which will call the method selectDay(). We’ll implement that in the next section; but first, we need to populate and build the calendar.
So, we’ll need to get the availability for a given month. Here’s what the output from /availability/dates will look like:
[
{
"date": "2016-06-02"
},
{
"date": "2016-06-06"
},
...
}
With this in mind let’s create our first widget method, which is responsible for getting the availability for a given month. Remember that this goes in the methods part of the widget:
methods : {
/**
* Fetch the availability data for a given month
*/
getAvailabilityForMonth : function( ) {
this.calendar = [];
this.$http.get( 'availability/dates', { month : this.month.format( 'YYYY-MM' ) } ).then( function( response ) {
this.days = [];
var available = response.data.map( function( item ) {
return moment( item.date ).date( );
});
var temp = moment( this.month ).date( 1 );
var m = temp.month();
var now = moment();
do {
this.days.push({
d : temp.date(),
past : temp.isBefore( now, 'day' ),
today : temp.isSame( now, 'day' ),
available : ( available.indexOf( temp.date() ) > -1 ),
});
temp.add( 1, 'day' );
} while ( temp.month() == m );
this.buildCalendar();
});
},
// . . .
}
An array of days of the month isn’t quite enough to build a calendar. We need some optional padding at the beginning, depending on the day of the week that the first of the month falls on. Then we need to split it into rows, adding additional cells at the end to ensure each row has exactly seven cells.
The code for building the calendar table is a little long-winded to go into here in detail, but essentially what it does is split the days in a month into rows, then adds “padding” either side so that the first of the month is set to the appropriate day, and each row contains seven cells. The method in question is buildCalendar().
Remember that we want to load the current month’s availability when the component is initialized. We can do this in the ready section:
var widget = new Vue({
// . . .
ready: function() {
this.getAvailabilityForMonth();
},
// . . .
});
Also in the methods section, we’ll need the following to implement the forward and back arrows on the mini-calendar:
previousMonth : function() {
var current = this.month;
this.$set( 'month', null )
this.$set( 'month', current.subtract( 1, 'months' ) );
this.getAvailabilityForMonth();
},
nextMonth : function() {
var current = this.month;
this.$set( 'month', null )
this.$set( 'month', current.add( 1, 'months' ) );
this.getAvailabilityForMonth();
},
We’ve now got a mini-calendar that highlights days which have some availability, enabling users to drill down further, choosing a time for their lesson.
Continue reading %How to Modernize a Booking System with Acuity Scheduling%
by Lukas White via SitePoint
