BOOKING CALENDAR

The booking calendar solves common problems associated with creating bookings, or handling selections between two date-times in web applications. The package consists of a Javascript component built with React, that renders different types of calendar components according to the intervals and Events specified.

Quick Start

Setup as dependency

Install as a dependency to use it in your project:

$ npm install booking-calendar

or with yarn

$ yarn add booking-calendar

Then import the component and its style into your component:

import BookingCalendar from 'booking-calendar';

Usage Example

The calendar allows the user to select a start and end time. When the start time is selected, onSelectStart is called. When the end time is selected, onSelectEnd is called.

import React, {useState} from 'react';
import BookingCalendar from 'booking-calendar';

export default function App() {
    const today = new Date()
    const nextWeek =  new Date(today.getFullYear(), today.getMonth(), today.getDate()+7);
    const [startDate, setStartDate] = useState(today);
    const [endDate, setEndDate] = useState(nextWeek);

    return (
        <BookingCalendar 
            defaultAvailable={true}
            onSelectStart={setStartDate}
            onSelectEnd={setEndDate}
            bookingPickerType={'dateRangePicker'}
        />
    );

}

Types of pickers

Date Range Picker

Select dates (without times). An example selection could be:

Start Time: 2021-11-21 End Time: 2021-11-27

We could also select one date as the start and end time (i.e. A one-day booking )

import React from 'react';
import BookingCalendar from 'booking-calendar';

export default function App() {
    const today = new Date()
    const nextWeek =  new Date(today.getFullYear(), today.getMonth(), today.getDate()+7);
    const [startDate, setStartDate] = useState(today);
    const [endDate, setEndDate] = useState(nextWeek);

    return (
        <BookingCalendar 
            defaultAvailable={true}
            onSelectStart={setStartDate}
            onSelectEnd={setEndDate}
            bookingPickerType={'dateRangePicker'}
        />
    );

}

Time Range Picker

Select the start and end times within the same day but with different hours. An example selection could be:

Start Time : 2021-11-21 08:00:00 GMT End Time : 2021-11-21 12:00:00 GMT

import React from 'react';
import BookingCalendar from 'booking-calendar';
export default function App() {
    const now = new Date()
    const plus_1_hour =  new Date()
    plus_1_hour.setHours(plus_one_hour.getHours() + 1);
    const [startTime, setStartTime] = useState(now);
    const [endTime setEndTime] = useState(plus_1_hour);
    return (
        <BookingCalendar 
            defaultAvailable={true}
            onSelectStart={setStartTime}
            onSelectStart={setEndTime}
            bookingPickerType={'timeRangePicker'}
        />
    );
}

Time Interval Picker

This picker is for items that are only available at specified intervals. For example, an item that can only be booked for hour-long appointment times.

So in that case, two (of many) appointment times available might look like:

Start Time : 2021-11-21 08:00:00 GMT End Time : 2021-11-21 09:00:00 GMT

Start Time : 2021-11-21 09:00:00 GMT End Time : 2021-11-21 10:00:00 GMT

You can only select one interval within the day. The intervals will be created each hour by default but you can specify a different interval through the Booking Configuration

import React, {useState} from 'react';
import BookingCalendar from 'booking-calendar';

export default function App() {
    const next_available _start = new Date()
    next_available _start.setHours(next_available _start.getHours() + Math.round(next_available_start.getMinutes()/60));
    next_available _start.setMinutes(0, 0, 0); 
    
    const next_available _end = new Date(next_available_start.valueOf())
    next_available _end.setHours(next_available_end.getHours() + 1)
    
    const [startTime, setStartTime] = useState(next_available_start);
    const [endTime setEndTime] = useState(next_available_end);

    return (
        <BookingCalendar 
            defaultAvailable={true}
            onSelectStart={setStartTime}
            onSelectEnd={setEndTime}
            bookingPickerType={'timeIntervalPicker'}
        />
        
}

Events Picker

The Events Picker is useful for bookable events (see: Events). For example, let's say you have an all-day workshop from 8 am to 4 pm.

Start Time : 2021-11-21 08:00:00 GMT End Time : 2021-11-21 16:00:00 GMT

In the calendar view, the day will be disabled if there are no events available on that day.

import React from 'react';
import BookingCalendar from 'booking-calendar';
export default function App() {
    const bookableEvents = [
        {
            start:new Date(2021,11,5,10,0,0),
            end:new Date(2021,11,5,16,0,0),
            timezone: 'UTC'
        }
    ]
    const [startTime, setStartTime] = useState(BookableEvents[0].start);
    const [endTime setEndTime] = useState(BookableEvents[0].end);
    return (
        <BookingCalendar 
            defaultAvailable={true}
            onSelectStart={setStartTime}
            onSelectEnd={setEndTime}
            bookingPickerType={'bookableEvents'}
            bookableEvents={bookableEvents}
        />
    );
}

Default Available

The availability of the calendar defines how the selection of date-times works by default. If the calendar is available by default, all of the date-times will be enabled to be selected unless they overlap a blocking period (see: Events Precedence). If the calendar is unavailable by default, all of the date-times will be disabled except for those within an open period (see: Events) that do not overlap a blocking period (see: Events Precedence)

The availability is indicated through parameter defaultAvailable and it can true or false

import React from 'react';
import BookingCalendar from 'booking-calendar';
export default function App() {
    const openPeriods = [
        {
            start:new Date(2021,11,22,12,0,0),
            end:new Date(2021,11,22,23,0,0),
            timezone: 'America/Bogota',
            eventType:'open_period'
        }
    ]
    return (
        <BookingCalendar 
            defaultAvailable={false}
            startDateCallback={function(){}}
            endDateCallback={function(){}}
            bookingPickerType={'timeIntervalPicker'}
            openPeriods={openPeriods}
        />
    );
}

Displaying events

Events

An event is an object with the following properties:

• start: The date-time when the event starts
• end: The date-time when the event ends
• timezone: The calendar will take this argument to display the dates and times according to the desired location
• eventType: An optional parameter to indicate one of the four types events defined (see: Event Types)

Event Types

The booking calendar handles four types of events:

• Open periods: Think of these like the 'open hours' of a business. If your studio is open from 9-5, set your open period to 9-5. The open periods will display as available, except for any closed periods (such as bookings) that overlap with the open period. (see: Precedence)

• Closed periods: Think of these as periods when your business is closed completely. For example, if you close during New Year's, you might create a closed period from 12/28 - 11/2. They define periods where the date-times are disabled unless they are preceded by other events (see: Precedence)

• Bookable Events: Think of these as specific events that can be booked like a conference or a concert. They define periods where the date-times should be enabled, if the bookingEventType parameter is set to bookableEvents otherwise the date-times should be disabled. This could change if the bookable event is preceded by other events (see: Precedence)

• Bookings: Think of these as bookings from your customers. They define periods where the date-times should be disabled unless you have configured the capacity to be more than 1, in which case the date-times will be enabled until capacity is reached (see: Booking Configuration)

Events Precedence

When two or more events overlap, we have to decide which event or events should be considered first to mark a date-time as enabled or disabled. The events are organized in order of importance as follows:

1. The booking is the most important of all events. If the number of bookings that overlap a date-time is greater than or equal to the capacity defined (see: Booking Configuration), the date-time should be disabled no matter what, even if another event (like an 'open period') occurs at the same time.

2. If a bookable event enables a date-time (this happens when the bookingEventType parameter is set to bookableEvents), it should remain enabled unless a booking blocks it. If a bookable event disables a date-time, it should remain disabled no matter what.

The open and closed period events could change the precedence according to the defaultAvailable parameter (see: Availability)

• If default available == true: The open periods take precedence over the closed periods, which means that a closed period disables a date-time if there is no open period overlapping them, in that case, the date-time should remain enabled unless other events overlap that date-time (bookable events or bookings)

  Bookings > Bookable Events > Open Periods > Closed Periods

• If default available == false: The closed periods take precedence over the open periods, which means that an open period enables a date-time only if there is no closed period overlapping them, in that case, the date-time should remain disabled unless other events overlap that date-time (bookable events or bookings)

  Bookings > Bookable Events > Closed Periods > Open Periods

Parameters for Events:

The events are passed to the booking calendar through one of five optional parameters:

• events: This is an array of every type of event, however, every event needs to specify the eventType prop
• bookableEvents: This is an array with bookable events (no need to specify the type)
• bookings: This is an array with bookings (no need to specify the type)
• closedPeriods: This is an array of closed periods (no need to specify the type)
• openPeriods: This is an array with open periods (no need to specify the type)

Examples:

import React from 'react';
import BookingCalendar from 'booking-calendar';
export default function App() {
    const bookableEvents = [
        {
            start:new Date(2022,1,5,10,0,0),
            end:new Date(2022,1,5,16,0,0),
            timezone: 'UTC'
        }
    ]
    const openPeriods = [
        {
            start:new Date(2022,1,6,8,0,0),
            end:new Date(2022,1,,6,17,0),
            timezone: 'UTC'
        }
    ]
    const closedPeriods = [
        {
            start:new Date(2022,1,6,10,0,0),
            end:new Date(2022,1,6,12,0,0),
            timezone: 'UTC'
        }
    ]
    return (
        <BookingCalendar 
            defaultAvailable={false}
            startDateCallback={function(){}}
            endDateCallback={function(){}}
            bookingPickerType={'timeRangePicker'}
            bookableEvents={bookableEvents}
            openPeriods={openPeriods}
            closedPeriods={closedPeriods}
        />
    );
}

Timezone

The timezone is one of the most important parameters for the calendar. This indicates how the events will be displayed in the calendar, taking into account the location of the product that is implementing the calendar.

The default value for this parameter is UTC

import React from 'react';
import BookingCalendar from 'booking-calendar';
export default function App() {
    return (
        <BookingCalendar 
            defaultAvailable={true}
            startDateCallback={function(){}}
            endDateCallback={function(){}}
            bookingPickerType={'timeRangePicker'}
            timezone={'Europe/Berlin'}
        />
    );
}

Here is a list of the timezones according to the format used in the calendar, indicated in the column TZ database name

Styling

The booking calendar can be customized to match the website it's displayed on, so it does not disrupt the aesthetics. Currently, we support the customization of the following styles:

• primaryColor: The background color for the HTML elements that are currently selected (e.g. The start and end date times)

• secondaryColor: The background color for the HTML elements that are between two selected elements (e.g. The date-times between the start and date-times in the Date Range Calendar)

• textAccentColor: The color of the text when it is within a selected element

• backgroundColor: The background color used by default for the calendar, it will be used when there is no other background color specified

• panelBackgroundColor: The background color used for the element that contains the events in the Events Calendar

• font: The font family that will be used for the whole calendar. Remember that the font should be added to the website through CDN or imported in a CSS file that will be applied to the calendar

• textColor: The color of the text when it is not within a selected element

import React from 'react';
import BookingCalendar from 'booking-calendar';
export default function App() {
    const styles = {
        primaryColor: 'white',
        secondaryColor: 'gray',
        textAccentColor: 'black',
        backgroundColor: 'black',
        panelBackgroundColor: '#939699',
        font:'Poppins',
        textColor: 'white'
    }
    return (
        <BookingCalendar 
            defaultAvailable={true}
            startDateCallback={function(){}}
            endDateCallback={function(){}}
            bookingPickerType={'timeRangePicker'}
            styles={styles}
        />
    );
}

Booking Configuration

A booking configuration is an object that contains other parameters to customize the calendar even more:

• Default Capacity: This is the number of bookings that can overlap each other at the same date-time (e.g. If the calendar is used to create reservations for a lecture, the defaultCapacity would indicate how many places can be reserved)

• Booking Interval: If we want to customize the Booking Calendar with smaller or bigger intervals (quarterHour, halfHour, day, night, a specific amount of minutes), It would be indicated in this parameter as a string or as a number(in minutes)

import React from 'react';
import BookingCalendar from 'booking-calendar';
export default function App() {
    const bookingConfig = {
        defaultCapacity:3
        bookingInterval:'quarterHour'
    }
    return (
        <BookingCalendar 
            defaultAvailable={false}
            startDateCallback={function(){}}
            endDateCallback={function(){}}
            bookingPickerType={'timeIntervalPicker'}
            bookingConfig={bookingConfig}
        />
    );
}

API

Main parameters of the Booking Calendar

bookableEvents Array - optional

An array of events

bookings Array - optional

An array of events

openPeriods Array - optional

An array of events

closedPeriods Array - optional

An array of events

events Array - optional

An array of events, for these events, the property eventType is mandatory

bookingPickerType * 'dateRangePicker' | 'timeRangePicker' | 'bookableEvents' | 'timeIntervalPicker' - string*

Indicates the type of calendar to be displayed

Mandatory parameter

defaultAvailable boolean,

Indicates the availability for the calendar by default.

Mandatory parameter.

styles Object - optional

An object with the styles to customize the calendar with the following props

• primaryColor - string - optional CSS property for backgroundColor
• secondaryColor - string - optional CSS property for backgroundColor
• textAccentColor - string - optional CSS property for color
• backgroundColor - string - optional CSS property for backgroundColor
• panelBackgroundColor - string - optional CSS property for backgroundColor
• font - string - optional CSS property for font-family
• textColor - string - optional CSS property for color

startDateCallback function | (startDate?:Date) => void

This function receives a Date as a parameter or undefined, to define the start date-time outside the calendar

Mandatory parameter.

endDateCallback function | (endDate?:Date) => void

This function receives a Date as a parameter or undefined, to define an end date-time outside the calendar

Mandatory parameter.

timezone string - optional

The timezone for the calendar (see: Timezones)

bookingConfig object - optional

An object with more specific parameters to customize the calendar with the following props

• defaultCapacity number - optional

  The number of bookings that can be overlapped in the same date-time

• bookingInterval number | 'quarterHour' | 'halfHour' | 'hour' | 'day' | 'night' - optional

  The time intervals that are available to be selected in the calendar

Event object

start Date | string

A Date or a string with a date in UTC, that indicates the start date-time for the event

Mandatory parameter.

end Date | string

A Date or a string with a date in UTC, that indicates the start date-time for the event

Mandatory parameter.

timezone string

The timezone for the event (see: Timezones)

Mandatory parameter.

eventType 'bookable_event' | 'open_period' | 'closed_period' | 'booking' - optional

A string that indicates the type of event