top of page

Calendar Widget

Calendar Settings Panel

 

Selecting the Calendar widget will bring up the widget menu. Click the Settings button to bring up the Settings panel. At the top of the panel is displayed the number of days remaining in the free trial of the Booking Calendar with a link to upgrade permanently. This is followed by three switches:

Basic - enables the Basic Calendar mode of operation and disables the Booking Calendar free trial if active.

Contact - enables the contact form to appear when the Book Now button is pressed and can be disabled if a custom contact form or alternate booking flow is desired.

Check-Out - enables the use of a check-out date which is preferred for property rentals, while the end date is preferred for item rentals. The start date and the check-in date are the same, but the label can be changed as required. For further details, please see the Date Input Settings Panel section below.

Note that multiple Calendar widgets may be added, each configured with different settings.

Date Input Settings Panel

The Start Date and End Date labels may be changed to Check-in and Check-out or Pick-up Date and Drop-off Date or anything else desired. Selecting the Start Date text input widget will bring up the widget menu. Click the Settings button to bring up the Text Input Settings panel. Update the Field title to the desired label text. Repeat for the End Date label.

Custom Images

The Available, Unavailable and Reserved images may be changed to any 300 x 300 pixel PNG image. Open the Layers panel and find the Calendar widget. From there go to the second Repeater and open the first Item. The 3 Images for Available, Unavailable and Reserved should then be visible. Select the image to change and the widget menu will appear. First click the Settings button to see which image is actually selected, then click the Change Image button and follow the prompts to apply a new image. Repeat for any other images. Note that only the first item needs to be updated as the repeater will use that image for all items.

Mobile Design Preset

The mobile design preset should be used for display on mobile devices. Switch the editor to the mobile view and select the Calendar widget. Click the Design button to view the Design Presets. The first preset is the default Desktop view with the Book Now button next to the Date fields and the second preset is for the mobile view with the Book Now button below the Date fields. Select the mobile preset and resize the Calendar widget to fit correctly in the mobile view.

Usage

Usage of the Calendar widget is fairly intuitive. Use the arrows (< >) on either side of the month to navigate forward and backward through the months. Click a date to have it entered as the Start Date, and if the date is valid (not already reserved or unavailable, etc.) then the next date clicked will be entered as the End Date. If both dates are valid, then further clicking of dates will have no effect. To change a date it needs to be made invalid. The simplest way to do this is to just delete the last digit of the year, then the next date clicked will populate that field.

 

Once both dates are valid, then the Book Now button can be clicked and the Contact form will appear if enabled. The Contact form allows the user to enter their first and last name, as well as their email address and phone number. Only the email address is required to complete the booking. If the Contact form is not enabled, then the booking will be completed with no further information collected. The booked dates will change from displaying the Available image to showing the Reserved image and will no longer be bookable. All booking and user data is stored in the CMS.

Events

The Calendar widget generates two Velo events. Velo is WIX's JavaScript based development environment.

onDatesValid()

The onDatesValid event is triggered when the Booking Calendar has determined that the entered start and end dates are valid. The purpose of this event is to allow for additional date validation rules. To facilitate this, two properties are available for use with this event:

{boolean } userValid - set to true if additional validation rules passed, otherwise set to false

{string} userError - when userValid is false, set the error message to display to the user

For a video tutorial with example code, see Adding Custom Booking Rules.

onDatesReserved()

The onDatesReserved event is triggered when the Booking Calendar has successfully reserved dates for a booking. The purpose of this event is to allow for additional actions after a booking has been made. For example, collecting payment for the booking.

For a video tutorial with example code, see Collect Payment on Booking with the Wix Pay API.

Item Id Text Field

Next to the month and year on the right is displayed the number 1. This is the Item Id that identifies the item being booked. If there are multiple calendars being used for booking multiple items, then each calendar will need to have a unique Item Id. This can be done manually, by selecting the text field and editing the Item Id or by connecting the text field to the Item Id in a CMS collection that contains all the items available for booking.

Using dynamic list and item pages connected to a CMS collection can greatly reduce the amount of work required to create and maintain a website with many items available for booking. The following four tutorial videos explain in detail how to do that.

 

Title Button and Text Field

Next to the month and year on the left is the Title button. On the live site or in preview mode, clicking this button will display the Title field that names the item being booked. To find the Title text field in the editor, open the Layers panel and find the Calendar widget. Expand it and the Title field will be found at the bottom as shown in the image below. Once selected, the Title can be manually edited, or connected to the Title in a CMS collection that contains all the items available for booking. See the Item Id section above for tutorial videos on how to do this.

Properties

The Calendar widget has nine Velo properties. Velo is WIX's JavaScript based development environment.

basic (boolean)

This property can be used to switch the Calendar widget between the Basic Calendar mode and Booking Calendar mode. This only applies if the free trial is active or the app has been upgraded. Set to true to force the Basic Calendar mode and to false to allow the Booking Calendar mode if available. This property can also be set with the Settings panel.

userValid (boolean)

This property can be used to disable the Book Now button, so the user is unable to make bookings. Set to true to disable bookings and to false to allow bookings. This property is primarily used with the onDatesValid() event.

userError (text)

This property can be used to display an error message to the user when they hover over the Book Now button. This property is primary used when userValid has been set to false to provide the reason why booking has been disabled. Therefore, this property is also primarily used with the onDatesValid() event.

contact (boolean)

This property can be used to disable the Contact form that appears after the Book Now button is clicked. Set to true to disable the Contact form and allow the booking to be made without collecting contact information through the form.  Set to false to have the Contact form appear after Book Now is clicked so that at least an email address must be entered before the booking will be made. This property can also be set with the Settings panel.

checkout (boolean)

This property can be used to switch between Start and End dates which are generally used for daily rentals and Check-in and Check-out dates which are generally used for nightly rentals. Set to true to enable Check-in and Check-out dates and to false to use Start and End dates which are generally renamed to Pick-up and Drop-off dates. This property can also be set with the Settings panel.

itemId (number)

This property can be used to set the Item Id in Velo. The Item Id can also be set directly on the Calendar widget, either manually or by connecting it to the CMS. This property was added for cases where those two options were inadequate. 

title (text)

This property can be used to set the Title in Velo. The Title can also be set directly on the Calendar widget, either manually or by connecting it to the CMS. This property was added for cases where those two options were inadequate. 

startDate (text)

This property can be used to set the Start Date in Velo. The Start Date can also be set on the Calendar widget by the user. This property was added for cases where the Start Date was entered elsewhere on the website, such as when checking availability, and now needs to be transferred to the app for booking to save the user the step of re-entering it.

endDate (text)

This property can be used to set the End Date in Velo. The End Date can also be set on the Calendar widget by the user. This property was added for cases where the End Date was entered elsewhere on the website, such as when checking availability, and now needs to be transferred to the app for booking to save the user the step of re-entering it.

 

Of these fields, the Item ID, Start and End Dates, and State are mandatory when creating an entry. If the Contact form is enabled in the Calendar widget, then the Email address is also mandatory when making a booking. User bookings have their state set to 'reserved'. The website owner can also manually add 'reserved' entries in the CMS when making bookings on behalf of a user, as well as 'unavailable' entries for dates they don't want to be available for users to book.

Select the bookings collection and view the following data fields (scroll to the right to see them all):

Title - the title (text) for the item being booked

Item ID - the ID (number) of the item being booked

Start Date - the start date (text) of the booking (day of check-in)

End Date - the end date (text) of the booking (day before check-out)

State - the state (text) of the booked days, either 'reserved' or 'unavailable'

Email - the email address (text) of the person for the booking

Phone - the phone number (text) of the person for the booking

First Name - the first name (text) of the person for the booking

Last Name - the last name (text) of the person for the booking

Order Link - the http link (text) to the WIX Store Order for the booking (future feature)

The CMS can be accessed from the WIX Dashboard or Editor. From the dashboard menu on the left, select CMS. The up/down arrows on the right allow for expanding or collapsing the display of collections. Expand the collections for @manojtheyogi/calendar. The bookings and temp collections will appear. The bookings collection contains all data for every booking made with the Booking Calendar app. The temp collection is for internal use only and shouldn't be accessed.

Working with the CMS

Bookings Collection
Data Fields

When creating an entry, click "+ Add Item" and enter the values for each field. the Item Id can be any integer number from 0 on up, digits only with no leading 0. The Start Date and End Date begin with the month using the first 3 letters with the first capitalized (i.e. Feb, Jul, Sep, etc.), next add a single space then the date as one or two digits with no leading zero (i.e. 5, 23, etc.), next add a comma and a space then the year as four digits. A full example would be: 'Feb 6, 2024'. The State must be either 'reserved' or 'unavailable' and nothing else. The remaining fields can be any text string with no strict formatting requirements.

Creating an Entry

When deleting an entry, select the checkbox on the left, next to the entry. The text "Delete 1" will appear on the right. Click it to delete the entry. 

Deleting an Entry
Dashboard Features

In the current release of the Booking Calendar, the need to work directly with the CMS has been greatly reduced with the ability to add, delete and update bookings now added to the Dashboard Page. However, there are still a few cases where working with the CMS is required. This section explains how to do that.

Add a field value to an existing booking in the database (CMS)

async function addField(start, field, type, itemId)

{string} start - start date of the booking to add the field value (CMS format)

{string} field - field value of the booking to add

{number} type - type of field of the booking to add (only 0 for title so far)

{number} itemId - item id of the item to add the field value

returns {Promise<boolean>} true if the field value was added

addField()

Add contact to an existing booking in the database (CMS)

async function addContact(start, first, last, phone, email, itemId)

{string} start - start date of the booking to add contact (CMS format)

{string} first - first name of the contact to add

{string} last - last name of the contact to add

{string} phone - phone number of the contact to add

{string} email - email address of the contact to add

{number} itemId - item id of the item to add contact

returns {Promise<boolean>} true if the contact was added

addContact()

Remove a booking from the database (CMS)

async function removeBooking(start, itemId)

{string} start - start date of the booking to remove (CMS format)

{number} itemId - item id of the item being removed

returns {Promise<boolean>} true if booking was removed

removeBooking()

Add a booking to the database (CMS)

For a video tutorial with example code, see Creating a Hotel Website with the Booking API.

async function addBooking(start, end, first, last, phone, email, itemId)

{Date} start - start date of the booking to add

{Date} end - end date of the booking to add (or check-out if enabled)

{string} first - first name of the booking requestor

{string} last - last name of the booking requestor

{string} phone - phone number of the booking requestor

{string} email - email address of the booking requestor

{number} itemId - item id of the item being booked

returns {Promise<boolean>} true if requested booking was added

addBooking()

Check if the requested booking dates are available.

For a video tutorial with example code, see Using the Check Availability API.

async function checkAvailable(start, end, itemId)

{Date} start - start date of the requested booking

{Date} end - end date of the requested booking (or check-out if enabled)

{number} itemId - item id of the item being booked

returns {Promise<boolean>} true if requested booking is available

checkAvailable()

 

Selecting the API widget will bring up the widget menu. Click the Settings button to bring up the Settings panel. The API widget is meant to be invisible on the page and only provides the ability to interface with the Booking Calendar by using Velo, WIX's JavaScript based development environment. As such, the only option is the Check-Out switch.

Check-Out - enables the use of a check-out date which is preferred for property rentals, while the end date is preferred for item rentals.

API Settings Panel

API Widget

 

Like the Booking Calendar, use the arrows (< >) on either side of the month to move forward or backward through the months. Use the mouse to scroll up and down through all available items. The red boxes represent reserved dates, dark grey boxes unavailable dates and light grey boxes available dates. Hovering the mouse over a reserved date will show the name of the person that made the booking if available in the CMS.

The Sort By menu allows for changing the order of how items are displayed. To sort by Item ID, select Item ID then reload the page for the display to update with the items now listed from lowest Item ID to highest. The other option available is Date, which sorts items by the next reserved date.

The Store switch should be left off for now, but soon it will be possible to integrate the Booking Calendar with the WIX Stores app and use WIX Store Orders for collecting payment for bookings. Enabling the Store switch will eventually allow for linking bookings to orders.

 

The Dashboard page allows site owners to view all bookings for all items available. For the best display, it is recommended that the Title field is set in the CMS for every entry. This can be done manually through the CMS UI, or in Velo by using the addField API.

The Booking Calendar Dashboard page is accessed from the WIX Dashboard. From the left menu, select Apps, then Booking Calendar.

Dashboard Page

Booking Calendar Guide

Introduction

The Booking Calendar allows for managing bookings for all types of rentals. This includes rental items like farm equipment or party supplies, as well as rental properties like hotels, apartments or vacation villas. Includes both a Basic Calendar for free and a Booking Calendar as an upgrade option. The Booking Calendar comes with a UI for users to view and select available dates for making bookings and also a form to collect contact information to store in the CMS with the booking dates.

It's also possible to create a custom UI for entering dates and contact information and then using the provided API widget to store booking dates and contact information. The API can also be used for email notifications, custom booking rules, to check availability, remove bookings and set the title field for display on the Dashboard page. Note that using the API requires knowledge of coding with Velo, WIX's JavaScript based development environment.

Installation

The Booking Calendar is available to install from the Wix App Market. Once installed, it can be accessed from the Add or Add Elements button, then App Widgets -> Booking Calendar -> Calendar widget or API widget. Just drag and drop either widget (or both) onto a website page.

Free Trial

After the first installation on a website, a 30 day free trial of the Booking Calendar is activated. To disable the free trail and revert to the Basic Calendar, the Basic option in the Settings panel can be enabled. Note that the free trial will still expire in 30 days even if not used.

The Settings panel displays the number of days remaining in the free trial and includes a link to permanently upgrade to the Booking Calendar. For further details, please see the Calendar Settings Panel section below.

bottom of page