home > support > solution library > simple ajax enquiry form

Simple AJAX enquiry form

The information in this article is outdated and remains only as a reference for those already using this method. If you are adding an enquiry form ("Contact us", "Brochure request" etc) to a website then please see: How to add an enquiry form.

The example below should help speed up your integration with the TourCMS enquiry API, feel free to use the code directly or as a base for your own implementation. While the API itself has been thoroughly tested the sample submission code is provided "as is" and without warranty. If you encounter any problems running this script please post in the forums here. If you have any suggestions / feedback on the code or the article itself please email support@tourcms.com.

View demo

More complex forms are possible, here's a screenshot of a form with more fields.

Requirements

A TourCMS account (free is fine) and a working knowledge of the customer and enquiry functionality
A web server that supports PHP
The ability to create / edit HTML forms

Step 1: Download the sample files

The first thing you will need to do is download the code via the link above and unzip it to your web server

The zip contains the following files:

easyAjaxEnquiry.php Contains the code that talks to the TourCMS API
submitEnquiry.php: Configuration page for the above
easyAjaxEnquiry.js: This enables the Ajax submission of the form and is mainly a tool to allow people who aren't familiar with server side scripting an easy way to plug a WYSIWYG form into a PHP submission. It would work equally fine by removing the Ajax call and just submitting the form normally.
sampleForm.html: A simple example form, you will need to create one of these for your own site.

Step 2: Configure your TourCMS account details and test the sample form

You will need your API login details (base URL and password key). To get these log into TourCMS, head to Configuration & Settings then to the Data API (REST XML) page and scroll down to the Legacy API section (You can ignore the boxes in the RESTful XML API section for now).

If the "API password key" box is empty you will first need to enter a password and click "Save changes")

Open up submitEnquiry.php in a text editor (e.g. notepad) and find these two lines:

// Copy the Tour CMS API URL exactly as it is written on your account settings page
$tourCMS_Api_URL = "YOUR_TOURCMS_API_BASE_URL";
	
// The API Password Key you entered in TourCMS
$tourCMS_Api_Password = "YOUR_TOURCMS_API_PASSWORD_KEY";

Replace them with your own details which will give you something like this:

// Copy the Tour CMS API URL exactly as it is written on your account settings page
$tourCMS_Api_URL = "https://live.tourcms.com/api/XXXX/1234/1234577fffff/";
	
// The API Password Key you entered in TourCMS
$tourCMS_Api_Password = "example";

Save submitEnquiry.php and close it.

Now open your web browser to the location you copied sampleform.html and enter a new enquiry into TourCMS, check this works and that you can see the enquiry in TourCMS before continuing.

Step 3: Setting up your own form

If you are converting an existing (non TourCMS linked) enquiry form

If you have an existing form that perhaps writes to a bespoke database or a form-to-email script it should only take a few changes to get it working with the code in this article:

Include easyAjaxEnquiry.js in the <head> section of your page.

<script type="text/javascript" src="easyAjaxEnquiry.js" />

Add an empty div on your page where you would like the error message / thankyou message to be displayed, usually this will be just before your opening form tag. This is just a placeholder and will be replaced with some content once a visitor has submitted the form.

<div id="easyAjaxResponse" style="display: none;"> </div>

Change the "action" of your form to point to submitEnquiry.php, give it an "id" of easyAjaxForm and an "onsubmit" as follows:

<form
action="submitEnquiry.php" method="post" id="easyAjaxForm"
onsubmit="easyAjaxEnquiry(this); return false;">

Add a field for the Enquiry type, in this example we are just adding a hidden field with the value of "Enquiry" however it could be "Brochure request" or anything you want, also rather than a hidden field you could use a select box to allow your visitor to enter the type themselves.

<input type="hidden" name="type" value="Enquiry" />

type is one example of several enquiry specific special fields, others are category which can be thought of as a sub-category for type (e.g. if for a brochure, the brochure name) and details which is a freetext. More information on Enquiry fields.

There are also various special fields that get entered into the customer record within TourCMS such as firstname, surname, postcode, telsms etc. These should be named exactly as they appear in the New Customer API documentation.

You should go through your form fieldnames and ensure any that should go into particular fields within either the TourCMS customer or enquiry record are correctly named so that they are recognised as special fields when the form is submitted. Any fields that aren't recognised as "special fields" will automatically be appended to the end of the details field within the TourCMS enquiry. As an example you could add a checkbox as to whether the customer holds a full driving license:

<input type="checkbox" name="License" value="Yes" />
		<label for="License">I hold a full driving license</label>

As this doesn't relate to any particular field either within the customer or enquiry records in TourCMS it will be automatically added to the end of the "details" within the enquiry as so:

License: Yes

If you are creating a new form from scratch

It's possible to use any field types and fieldnames within your enquiry form however certain fields will be recognised as special fields within TourCMS. These nclude enquiry fields such as type, category and details or customer fields such as firstname, surname, telsms etc. More information on Enquiry fields and there is a list of customer fields in the New Customer API documentation.

You MUST have a field with the name type, if you don't want to let the customer choose their enquiry type then just use a hidden field.

Other than the particular field names you will also need to make sure you include the easyEnquiry.js function and give your form a particular id and onsubmit function, this enables the AJAX submission.

In your document <head>:

<script type="text/javascript" src="easyAjaxEnquiry.js" />

Your <form> tag should look like this:

<form
action="submitEnquiry.php" method="post" id="easyAjaxForm"
onsubmit="easyAjaxEnquiry(this); return false;">

Finally you will need to create an empty div with a particular id so that the JavaScript knows where to place the success / error message once the user has submitted the form. This MUST be outside of the form, usually it's placed just before the opening form tag added in the last step giving you this:

<div id="easyAjaxResponse" style="display: none;"> </div>
<form
action="submitEnquiry.php" method="post" id="easyAjaxForm"
onsubmit="easyAjaxEnquiry(this); return false;">

Step 4: Test thoroughly!

While the API itself has been thoroughly tested he sample submission code above is provided "as is" and without warranty. If you encounter any problems running this script please post in the forums here

Step 5: Advanced configuration (optional)

Validation

Rather than submitting the form immediately it would be advisable to write some basic JavaScript validation that runs before the form is allowed to submit, here's a version of the form that forces the user to fill in their surname and email address.

Ignore fields

Any fields that aren't recognised as TourCMS enquiry or customer specific fields will be appended to the end of the details within the enquiry automatically, if there are any fields that you would prefer NOT to be automatically added to the end of the details then add their name to this comma separated list in submitEnquiry.php:

$ignoreFieldNames = "Submit,submit";

Anti-spam

The sample code includes some basic anti-spam methods (disabled by default), additional anti-spam methods such as Captchas could be added with little effort.

Enabling the included anti-spam check:

Add a hidden field named stamp which is populated with the current UNIX timestamp when the page loads (sample code shown below)
Open submitEnquiry.php in a text editor and change $checkTimestamp to true.

PHP code for hidden field (recommended)

print '<input type="hidden" name="stamp" value="'.time().'" />';

JavaScript code for hidden field (if PHP isn't possible)

<input type="hidden" name="stamp" id="stamp" value="" />
<script type="text/javascript">
	document.getElementById("stamp").value = Math.floor(new Date().getTime() / 1000);
</script>

Configure the success & failure messages

It's possible to configure the success and failure messages by editing the following lines in submitEnquiry.php:

// Message to be displayed if the enquiry is successfully stored by TourCMS
$successMessage = 
"<p>Thanks, your enquiry has been sent</p>
	<p><a href='/' onclick='return easyAjaxShowForm(true);'>Submit another</a></p>";
	
// Message to be displayed if there is a problem storing the enquiry in TourCMS
$errorMessage = 
"<p>Sorry, there was a problem with your enquiry</p>
	<p><a href='/' onclick='return easyAjaxShowForm(false);'>Ok</a></p>";

Tip: The JavaScript call to easyAjaxShowForm will hide the success/failure message and show the form again, there is a single boolean parameter for this which represents whether the contents of the form should be reset prior to displaying the form to the user (e.g. if there is a failure we pass false to save the user having to enter all of their details again prior to submitting).

View demo