HotelReservationForm.AJAX | Help Topics, Users Manual, API Reference, Troubleshooting, Customization

HotelReservationForm.AJAX Setup, Installation and Help Topics

HotelReservationForm.AJAX is full a featured AJAX solution for websites that provide online room reservations. It is skinnable, easy to customize, localizable, cross browser and ultra fast. The installation and the configuration of the script is easy, and your form can be up and running on your website within minutes.

View online demo of HotelReservationForm.AJAX or download it straight away. Buy via PayPal.

Because the component or parts of it are rendered entirely on the client, and the source is not available via the standard View Source command of the browser, it is recommended that you use IE DevToolBar or FireBug or other troubleshooting and code inspection tool (such as Opera Dragonfly or the development tools of Safari and Google Chrome) in order to inspect the HTML and the CSS classes.

Requirements

Standards-compliant (XHTML1.0/1.1, HTML5) or skinny doctype page - the control will not initialize on non-standards-compliant pages.
Web-server (Apache, IIS) with PHP support.

Supported Browsers

Installing the Default Configuration of the Component

To copy a chunk of code from the listings below and keep its indentation, double click to select it, then right click and choose "Copy" from the context menu or use Ctrl + C.

Copy the entire HotelReservationForm.AJAX folder in the root of your website. In the course of this manual you will learn how to use the rootfolder property if you keep your third party components in a separate folder.
Make sure that the page where the form will resides is in standards-compliance mode, i.e. that your doctype is XHTML1.0, XHTML1.1 or HTML5. The control won't initialize on non-standards-compliant pages and will throw a compliance exception. Optionally, a skinny doctype can be used.
In the head section of the page (between the <head>...</head> tags) on which the form will reside, add the runtime directive of HotelReservationForm.AJAX:

<?php
	$rootfolder = "";
	include "HotelReservationForm.AJAX/HotelReservationForm.AJAX/Scripts/HotelReservationForm.AJAX.php";
?>

In the <body>...</body> section of the page where the form will render, add an empty <div id="hotel-reservation-form-ajax"></div>:

<div id="hotel-reservation-form-ajax"></div>

This element will be used as a placeholder for the form.

In the <head>...</head> section of the same page, below the runtime directive, add the constructor of the control in a <script>...</script> tag:

var form = new HotelReservationFormAJAX({
	// form settings
	enabled: true,
	rootfolder: "<?= $rootfolder; ?>",
	skin: "Vista",
	rendered: function(){
		
	},

	// localization strings
	printWindowTitleText: "Print Reservation",
	closeButtonText: "Close",
	requiredFieldHint: "This is a required field",
	unsupportedBrowser: "Your browser is not supported. To make a reservation, please use one of the browsers from the list below:",

	// hotel settings
	hotelName: "Magnolia Hotel",
	hotelEmail: "info@magnolia-hotel.com",
	hotelPostmasterEmail: "postmaster@magnolia-hotel.com",
	hotelNotificationEmailSubject: "You have received a new reservation",
	hotelEmailThankyouSubject: "Thank you for booking with Magnolia Hotels",
	total: "total:",

	// print window dimensions
	printWindowWidth: 640,
	printWindowHeight: 480,

	// PayPal settings
	enablePayPal: true,
	payPalCurrency: "USD",
	paypalAddress: "payments@magnolia-hotel.com",
	paypalTitle: "Book a room at Magnolia Hotel",
	paypalReturnPage: "http://magnolia-hotel.com/thank-you/",
	paypalThankYouText: "Thank you for booking a room at Magnolia Hotel!"
});

The properties of the constructor are explained in detail later in this manual, and this default setup can be taken directly from the distribution file of HotelReservationForm.AJAX - the index.php page.

Below the constructor of the form, add the tabs settings. Here you can specify different properties regarding width, height, localization texts, etc:

HotelReservationFormAJAX.tabs = {
	width: 640,
	height: 400,
	tabContactDetails: "Contact Details",
	tabReservationDetails: "Reservation Details",
	tabMeals: "Meals",
	tabOptions: "Options",
	tabFinalize: "Finalize",
	finishedTabButtonText: "Success!"
};

After the tab settings object (HotelReservationFormAJAX.tabs), add the button settings object. Here you will be able to localize the control buttons of the form:

HotelReservationFormAJAX.buttons = {
	previous: "&laquo; previous",
	next: "next &raquo;",
	print: "print",
	finish: "finish"
};

After the button settings object (HotelReservationFormAJAX.buttons) of the form, add the room types array. In it you will be able to specify room types, prices and labels:

HotelReservationFormAJAX.typesOfRooms = {
	"room": [
	{
		"type": "single",
		"price": "50",
		"label": "single - USD50 per day"
	},{
		"type": "double",
		"price": "100",
		"label": "double - USD100 per day"
	},{
		"type": "double as single",
		"price": "80",
		"label": "double as single - USD80 per day"
	},{
		"type": "apartment",
		"price": "150",
		"label": "apartment - USD150 per day"
	},{
		"type": "studio",
		"price": "200",
		"label": "studio - USD200 per day"
	}
]};

After the room types array (HotelReservationFormAJAX.typesOfRooms), add the number of guests object that your users will select when making a reservation. The value should be a Number:

HotelReservationFormAJAX.numberOfGuests = 6;

Finally, add the initialization method below the number of guests object (HotelReservationFormAJAX.numberOfGuests):

form.pageload();

Reload the page. If the steps have been followed correctly, at this stage the form should be up and running with its default configuration and now you can start customizing it.

Initialization and Client-side Properties of HotelReservationForm.AJAX

This topic describes the setup of the public side of the component. Please, refer to the Configuring the Admin of HotelReservationForm.AJAX topic in this manual for customization how-to's of the backend of the script.

The `$rootfolder` PHP Variable

<?php
	$rootfolder = "";
	include "HotelReservationForm.AJAX/HotelReservationForm.AJAX/Scripts/HotelReservationForm.AJAX.php";
?>

By default the component should be added to the root of your public directory, however you may want to put it in another location, for example "Scripts". You can use the $rootfolder PHP variable to do this:

<?php
	$rootfolder = "Scripts/";
	include "HotelReservationForm.AJAX/HotelReservationForm.AJAX/Scripts/HotelReservationForm.AJAX.php";
?>

Make sure you do not forget the trailing slash ("/") after the directory name, otherwise the script will not initialize and will throw server and client errors.

`HotelReservationFormAJAX()`

The properties of the constructor of HotelReservationForm.AJAX should be used to customize and adapt the form for the needs of the website it is used.

enabled

Requires a Boolean (true or false) value. If set to false, the form will not initialize on the page. For example:

rootfolder: true

You can se the value to false when, for example, your hotel does not vacancies.

rootfolder

Keep it as it is, don't change anything:

rootfolder: "<?= $rootfolder; ?>",

The value of the rootfolder property will be automatically set by server with the value you have set in the $rootfolder PHP variable explained earlier in the manual.

skin

Requires a String, representing the skin that will be applied to the form and the components it consists of, for example:

skin: "Vista"

As HotelReservationForm.AJAX utilizes several other components, the skins (CSS files) for each component are stored in different locations, as follows:

HotelReservationForm.AJAX/HotelReservationForm.AJAX/Skins/[SkinName]
HotelReservationForm.AJAX/Forms.JS/Skins/[SkinName]/
HotelReservationForm.AJAX/HotelReservationForm.AJAX/DatepickerSkins/DatePicker.[SkinName].css
HotelReservationForm.AJAX/TabStrip.XML/Skins/[SkinName]
HotelReservationForm.AJAX/Window.JS/Skins/[SkinName]

For more information about each component that is used internally with HotelReservationForm.AJAX, click a links from the list above.

rendered

Here you can define a custom JavaScript function that will be executed after the component is fully rendered on the page, i.e. when the custom "hotel-reservation-form-ajax-rendered" event of the form is fired, for example:

rendered: function(){
	alert("HotelReservationForm.AJAX rendered (call from the 'rendered' property)");
}

You can also subscribe to this event by using jQuery:

$(document).ready(function(){
	$("#hotel-reservation-form-ajax").bind(form.EVENTS.rendered, function(){
		alert("HotelReservationForm.AJAX rendered (call via jQuery)");
	});
});

printWindowTitleText

Requires a String, representing the titlebar text of the Print Reservation Window that can be opened from the print button after the form has been submitted to the server:

printWindowTitleText: "Print Reservation"

More info about Print Reservation Window is available later in this manual.

closeButtonText

Requires a String, representing the tooltip (hint) of the close button in the print reservation window, for example:

closeButtonText: "Close"

requiredFieldHint

Requires a String, representing the tooltip (hint) of the required icon that appears next to an input field that is set as required:

requiredFieldHint: "Required field"

Setting a form input field to required is explained later in this manual.

unsupportedBrowser

Older browsers (such as Internet Explorer 6) are not supported, and you can display an unsupported browsers message, so your users use a newer browser in order to make a successful reservation:

unsupportedBrowser: "Your browser is not supported. To make a reservation, please use one of the browsers from the list below:"

The list with the supported browsers will render automatically.

hotelName

Requires a String, representing the name of the hotel, for example:

hotelName: "Magnolia Hotel"

Requires a String, representing the email of the hotel, for example:

hotelEmail: "info@magnolia-hotel.com"

hotelPostmasterEmail

Requires a String, representing the email or automatic postmaster email of the hotel, for example:

hotelPostmasterEmail: "postmaster@magnolia-hotel.com"

You can use the same email that you have set in the hotelEmail property.

hotelNotificationEmailSubject

Here you can set subject for the notification email that will be sent to the administrator when a new reservation arrives:

hotelNotificationEmailSubject: "You have received a new reservation"

Later in this manual you will learn how to customize the notification emails.

hotelEmailThankyouSubject

Here you can set subject for the thank you email that will be sent to the person who made the reservation:

hotelEmailThankyouSubject: "Thank you for booking with Magnolia Hotels"

Later in this manual you will learn how to customize the thankyou emails.

total

Localization string required by the realtime calculator of the form:

total: "total:"

printWindowWidth

A Number, representing the width of the print reservation window in pixels:

printWindowWidth: 640

printWindowHeight

A Number, representing the height of the print reservation window in pixels:

printWindowHeight: 480

enablePayPal

Requires a Boolean (true or false) value. If set to false, the customized PayPal link and PayPal icon will not appear in the success tab after the form has been submitted. Otherwise, users will be able to directly go to PayPal and transfer the money for their stay at your hotel:

enablePayPal: true

The PayPal functionality is disabled in the trial version of the component.

payPalCurrency

Set the default currency accepted by your hotel for PayPal payments. Please, visit this PayPal page for a complete reference for the currency codes accepted by PayPal.

payPalCurrency: "USD"

paypalAddress

The e-mail address for PayPal used by the hotel to process payments.

paypalAddress: "payments@magnolia-hotels.com"

paypalTitle

Title for the customized PayPal payment page:

paypalTitle: "Book a room at Magnolia Hotel"

paypalReturnPage

The page on your website to which users will be redirected after a successful PayPal payment.

paypalReturnPage: "http://magnolia-hotel.com/thank-you/"

paypalThankYouText

Thank you text that will appear on the personalized page on PayPal after a successful payment. The value of the property should be a plain text string.

paypalThankYouText: "Thank you for booking a room at Magnolia Hotel!"

`HotelReservationFormAJAX.tabs`

In this object you can define form dimensions and also localize the tabs.

width

Requires a Number, representing the with of the form in pixels:

width: 640

height

Requires a Number, representing the with of the form in pixels:

width: 480

tabContactDetails

Text for the Contact Details tab button

tabContactDetails: "Contact Details"

tabReservationDetails

Text for the Reservation Details tab button

tabReservationDetails: "Reservation Details"

tabMeals

Text for the Meals tab button

tabMeals: "Meals"

tabOptions

Text for the Options tab button

tabOptions: "Options"

tabFinalize

Text for the Finalize tab button

tabFinalize: "Finalize"

finishedTabButtonText

Text for the Finished tab button

finishedTabButtonText: "Success!"

The Finished tab is not rendered by default. It appears after the form has been successfully submitted.

`HotelReservationFormAJAX.buttons`

In this object you can set your own texts to the previous, next, book now and print buttons of the form:

previous: "&laquo; previous"

next: "next &raquo;"

print

print: "print"

finish

finish: "finish"

`HotelReservationFormAJAX.typesOfRooms`

Here you can define the types of rooms that will render in the form as a dropdown. To define a single room, add the following to the array (and don't forget to comma-separate each room object):

{
	"type": "double",
	"price": "100",
	"label": "double - USD100 per day"
}

"type" - the type of room is a service property. If it's value contains more than one word, it is recommended to separate words with a dash ("-") instead of space.
"price" - price for the room per day.
"label" - the label is visible to the users of the form. It may contain the type of the room and the price.

Finally, the room type array should look like this:

HotelReservationFormAJAX.typesOfRooms = {
	"room": [
	{
		"type": "single",
		"price": "50",
		"label": "single - USD50 per day"
	},{
		"type": "double",
		"price": "100",
		"label": "double - USD100 per day"
	},{
		"type": "double as single",
		"price": "80",
		"label": "double as single - USD80 per day"
	},{
		"type": "apartment",
		"price": "150",
		"label": "apartment - USD150 per day"
	},{
		"type": "studio",
		"price": "200",
		"label": "studio - USD200 per day"
	}
]};

The order of the rooms in the array is going to be the order in the dropdown.

`HotelReservationFormAJAX.numberOfGuests`

Here you can set the number of guests. This will render a dropdown and your visitors will use it to select the number of guests while making the reservation

HotelReservationFormAJAX.numberOfGuests = 4;

The value should be an integer, representing the max number of guests that can be selected.

Customizing the Form and the Tabs Content

The content of each tab is stored in a separate PHP file, in which you can add content or form fields. Tab content files are in the HotelReservationForm.AJAX/HotelReservationForm.AJAX/Tabs/ folder, and the name of each file reflects the name of the tab itself, for example - the content file for the Contact Information tab is the contact-information.php file.

You can add custom tabs to the form by editing the HotelReservationForm.AJAX/HotelReservationForm.AJAX/Tabs/HotelReservationForm.AJAX.php file. Each <tab /> tag represents a single tab, however custom tabs' properties cannot be set in the HotelReservationFormAJAX.tabs object, but directly in the .php file, for example:

<tab title="My Custom Tab" enabled="true" source="HotelReservationForm.AJAX/HotelReservationForm.AJAX/Tabs/my-custom-tab.php" />

The text for the tab button can be set in the title property, for example:

<tab title="My Custom Tab" />

Each tab requires an external tab content file (the URL of this file is set in the source) that will be loaded when the tab is clicked. External tab files are stored in the HotelReservationForm.AJAX/HotelReservationForm.AJAX/Tabs folder, so when creating a new tab, you should supply a respective PHP file for it, for example: HotelReservationForm.AJAX/HotelReservationForm.AJAX/Tabs/my-custom-tab.php. The reference to this file should be:

<tab source="HotelReservationForm.AJAX/HotelReservationForm.AJAX/Tabs/my-custom-tab.php" />

The custom tabs are fully functional, you can add form fields, set them as required, etc. You need to have a basic knowledge of HTML and use this manual as a reference (especially this topic). Make sure you always set a unique name and id attributes to a newly added custom form field, otherwise it will not be submitted, for example:

<input type="checkbox" id="meals-lunch" name="meals-lunch" />

Setting a Required Field

For reference, open HotelReservationForm.AJAX/HotelReservationForm.AJAX/Tabs/contact-information.php.

You will notice that the required form fields have a special attribute - data-required. Its value can be either true or false. If set to true, the field will be set as required and next to it will render a visual clue - a star. When the field is validated, against the rules for the respective field type (which is set in the data-type) attribute, the star icon will turn to a tick, indicating that the field has been filled correctly. To add a non-required form field, do not set the data-required attribute, or set its value to false.

The Book Now button will not be enabled until all required fields are successfully validated. One the button is enabled, users will be able to send the reservation.

Mandatory Required Fields

A few form inputs of the component cannot be set to non-required. These are:

The number of guests dropdown.
The type of room dropdown.
The datepickers dropdowns.
The Agree to Terms of Service checkbox.

Setting Prices to Form Inputs

You can set price-per-day to checkbox, radio button and dropdown form fields by using the data-price attribute, for example:

<input type="checkbox" id="meals-lunch" name="meals-lunch" data-required="false" data-price="20" />

Types of Form Inputs (data-type="")

The data-type attribute can be added to a form field, and according to its value (email, text, date or number) its user input will be validated against different rules, for example this input:

<input type="text" data-type="email" />

... will be checked for valid e-mail format if it's data-required is set to true.

Customizing the Terms of Service Text

To customize the Terms of Service text in the Finalize tab, modify the HotelReservationForm.AJAX/HotelReservationForm.AJAX/Tabs/terms-of-service-text.php file.

Customizing the Notification and Thankyou Emails

The notification email is the email that the administrator of the hotel will receive when a new reservation has been submitted. You can customize it by editing the file below:

HotelReservationForm.AJAX/Scripts/HotelReservationForm.AJAX.NOTIFICATION_TO_CUSTOMER.html

The thankyou email is the email that the user of the form after they have made the reservation. You can customize it by editing the file below:

HotelReservationForm.AJAX/Scripts/HotelReservationForm.AJAX.NOTIFICATION_TO_HOTEL.html

In order to format the emails you can use simple HTML tags, for example <p>...</p> (paragraph) or <br /> (line-break).

The Print Reservation Window

The Print Reservation window allows users to print the reservation after submitting it. The window can be opened by pressing the Print button that will appear at the bottm of the form after a reservation has been made. If you know a little of HTML, PHP and CSS you can customize and finetune the contents of the window by editing this file:

HotelReservationForm.AJAX/Tabs/print-form.php

To customize the print styles of the reservation, edit this file (it contains only print-repated styles and will not affect the appearance of the form):

HotelReservationForm.AJAX/HotelReservationForm.AJAX/Scripts/HotelReservationForm.AJAX.Print.css

Configuring the Admin of HotelReservationForm.AJAX

This topic describes the setup of the admin of the component. Please, refer to the Initialization and Client-side Properties of HotelReservationForm.AJAX topic in this manual for customization how-to's of the public side of the script.

The Admin of HotelReservationForm.AJAX

The admin of the component provides smooth workflow for the process of getting and confirming reservations, sending confirmation emails. Here you can also access the already confirmed reservations, archive or delete them.

The admin is accessible from the following URL:

http://yourwebsite.com/HotelReservationForm.AJAX/Admin/

If you are accessing it for the first time, the default username and password are admin / admin.

Setting Log-in Credentials

The default username and password values are admin / admin, and you should change these before going live. On the log-in page you can also select how long to remain logged in by selecting value from the dropdown.

To set username and password, open HotelReservationForm.AJAX/Admin/Assets/process-login.php and modify the values of the $user_name and $password variables, for example:

$user_name = "johnsmith";
$password = "smith567";

QUICK TIP: The login routine uses cookies, and in order to log in, the cookies in your browser should be enabled, otherwise the login will fail.

Setting Up the Admin for Work

Please, before using the admin, make sure you have followed carefully the steps in this chapter. This will ensure flawless operation of the admin.

The HotelReservationForm.AJAX/Admin/Assets/settings.php File

Basically, the admin should work without modifying its properties. However, if you want to change the dimensions of the popups, you can do it here. Make sure you do NOT change anything in the properties whose values are server-parsed, i.e:

hotelName: "<?= $hotel_name; ?>"

... Because they should be set in the HotelReservationForm.AJAX/Admin/Lang/en-US/language.php file (described later in the manual)

To change the dimensions of the different popups in the admin, set your own values for the properties in the Admin.DIMENSIONS object.

The HotelReservationForm.AJAX/Admin/Lang/en-US/language.php File

This file acts both as a localization and bootstrap file, and you should make sure you have set your own values to certain variable names, paying special attention to the hotel name, email, email subjects, etc. Among the most important variables which require special attention are:

$hotel_name - here you should set the name of the hotel, and this vaiable should be used not only for the admin itself, but also in the confirmation email, etc.
$hotel_email - here you should set the email of the hotel, and this vaiable should be used not only for the admin itself, but also in the confirmation email, etc.
$path_to_hotel_reservation_form_ajax - the absolute path (including http://yourwebsite.com) to the root folder of HotelReservationForm.AJAX.

The variable names are self-explanatory, so it should not take long to set the correct values. Please, also refer to the Localization chapter later in this manual for a detailed explanation of the language.php file.

Customizing the Confirmation Email

You can easily change the default text for the confirmation email by editing the following file:

HotelReservationForm.AJAX/Admin/Assets/confirmation-email.html

You need to have a basic knowledge of HTML, for example - <br /> - line break, <p>...</p> - new paragraph, etc.

The values in curly braces will be replaced automatically against some service values such as hotel name ({hotel-name}), customized PayPal payment link ({paypal-url}), reservation ID ({reservation-id}), public URL to view reservation online ({reservation-online-link}) and customer name ({name}). You can use these variables as many times as you need throughout the email, just make sure you don't keep their exact formatting.

Localization

The admin of the component is fully localizable. The default language is English (en-US) and currently we do not provide translations to other languages, but you can easily create your own localization file by following the steps below:

Make sure you are logged off from the admin.
Go to HotelReservationForm.AJAX/Admin/Lang/.
Copy the HotelReservationForm.AJAX/Admin/Lang/en-US/ folder.
Rename it with the language code of the translation, for example de-DE.
In the following files, replace the occurencies of "en-US" to "de-DE" in the $lang PHP variable:
- HotelReservationForm.AJAX/Admin/index.php
- HotelReservationForm.AJAX/Admin/show-reservation.php
- HotelReservationForm.AJAX/Admin/unsupported.php
Reload the admin and log in again. The localization strings should now be loaded from the new HotelReservationForm.AJAX/Admin/Lang/de-DE/language.php file
Open Lang/de-DE/language.php with your favorite code editor and start editing the variables. The variable names are pretty self-explanatory, and localizing them should not take long. You can reload the admin from time to time to see your changes taking place.

If your language contains special characters such as umlauts, diacritics, etc, please make sure you use HTML entities instead the symbols themselves, for example - ä should be represented as ä. Visit this page for a complete HTML entities reference.

Setting CHMOD to the Server Files and Directories

To ensure that the form is working properly on a live server you should:

Recursively (i.e. all files and folders) set the HotelReservationForm.AJAX/Reservations folder and its subfolders to read-write. Do not delete any of the nested directories as they are required for the correct operation of the admin.
Optionally (for some servers) set the correct read-write-execute rights to the files in the HotelReservationForm.AJAX/Admin/Assets folder.

If you are not acquainted with FTP and CHMOD, please, refer to the following pages:

If you do not have a FTP program, you may use FileZilla for free.

Difference Between the Trial and the Full Version

The trial version of the control is for consideration and testing purposes only. It cannot be used commercially on a production server to process actual reservations. Using the trial version for commercial purposes is unlawful, and legal steps may be taken against websites that use it. Please, refer to the License Agreement included in the distribution of the script prior to using it.

Below are the limitations of the trial version:

Public page (where the reservation form is):
- Only one skin is included instead of 12.
- Trial message.
- The notification and thank you emails sent to the hotel administrator and to the customer contain a trial notice.
Admin panel:
- Nag screen and page reload every 60 seconds.
- Trial message.
- Trial message is included to the confirmation email sent to the customer.

The full version can be purchased via PayPal from this link. It comes with a set of 12 skins and does not send or display any trial messages.

If you consider purchasing more than one Acid.JS component you may create and order a custom Creative Web 2.0 Bundle and save money. More information about the Creative Web 2.0 Bundle program is available on my blog.

Upgrade to the Full Version after Purchase

After getting the full version you will notice that it contains only certain files, not the entire distribution required to run the script - the rest of the skins and JavaScript. You have to replace the files in the trial version distribution with the ones that you have received after having purchased the full version manually. After this, the control should work without trial notices and the emails sent by it will not contain trial strings.