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 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.
Next, is three Image Location text fields for the Available, Unavailable and Reserved image location URLs. Any 300 x 300 pixel PNG image may be uploaded to the WIX Media Manager and its URL inserted in the corresponding text field to have that image used by the Calendar widget when displaying Available, Unavailable and Reserved dates. For instructions on how to obtain the URL for uploaded images, please see the following video tutorial:
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.
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 Change Preset button to view the Design Presets. 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 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, then expand the first Container and the Title field will be found near the top 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 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 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 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 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. Whenever this selection is changed, reload the page for the display to update.
The Store switch should only be enabled if the Booking Calendar has been integrated with WIX Stores. This integration requires custom Velo code, which has been added in the Off-Grid Rentals template. This template adds bookings to the shopping cart for collecting payments with WIX Stores.
When the Store switch is enabled an Update Links button appears. Clicking this button creates links from each booking in the dashboard to the corresponding Order in WIX Stores. After the update completes, which can take more than a minute, reload the page to have the links read in. Note that the links also expire after some time, so whenever that happens just Update Links again.
The View Bookings 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 with the Manage Bookings dashboard page by first searching for a booking and then adding the title and saving it.
The Booking Calendar Dashboard page is accessed from the WIX Dashboard. From the left menu, select Apps, then Booking Calendar.
Dashboard Page
View Bookings
It is highly recommended to watch the following video tutorial that covers all of the features available.
Manage Bookings
The Manage Bookings dashboard page is accessed by clicking the Manage Bookings button in the top right. This page allows site owners to add, delete and update bookings. The instructions for doing this are given on the right side of the 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.
The recommended use for most cases is to purchase and customize the Off-Grid Rentals template. It integrates the Booking Calendar with WIX Stores, and provides example rentals for property and equipment. It comes with a 30 day free trial, then US$19 to purchase. The following video provides full details of the template.
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.
Important Note Before Upgrading to V3. If custom images are being used for the available, unavailable or reserved images, then the WIX Media Manager URL for those images will need to be entered in the Settings panel. Instructions are provided in this tutorial video: