Acid.JS Web 2.0 Components Help Topics

ContactForm.JS

ContactForm.JS Setup, Installation and Help Topics

Powerful AJAX component for feedback forms with a state-of-the-art adapter mechanism that allows the creation of any kind of forms.

The control supports 11 types of different HTML5 form fields - from the ordinary textboxes to date pickers and customizable dropdowns. The forms created with it have Web 2.0 looks - rounded corner input fields, custom checkboxes and radio buttons, modal overlay and message upon form submission, user-friendly client validation, etc.

View online demo of ContactForm.JS 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

Supported Browsers

  • 6
  • 7
  • 8
  • 9
  •  
  •  
  •  
  •  

Installing and Running 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.

1. Copy the entire ContactForm.JS/ directory in the root of the website that you are going to use it on. You cannot add the folder as a child of another folder, otherwise the component will fail to initialize. When the directory is copied, the folder structure should look like this:

ContactForm.JS
index.php
some-page.php

2. In the header (between the <head>...</head> tags) section of the page on which you will use ContactForm.JS, add the runtime directive of ContactForm.JS, which will import the scripts of the component:

<?php include "ContactForm.JS/Assets/ContactForm.JS.Runtime.inc" ?>

3. In the <body>...</body> section of the page where the form will reside, at the place where the form will appear, add the placeholder directive of the control:

<?php include "ContactForm.JS/Assets/ContactForm.JS.PlaceHolder.inc" ?>

4. In the header (between the <head>...</head> tags), below the runtime directive from Step 1, add the initialization method of the control:

<script type="text/javascript">
contactformjs.pageload({
	// general settings
	enabled: true,
	showresetbutton: false,
	disableaftersubmit: true,
	skin: "Vista",
	width: '540',
	submitbuttontext: "Submit Form",
	resetbuttontext: "Reset Form",
	formdisabledmessage: "We do not accept any comments right now.",
	formsubmittedtext: "Thank you for contacting us. We will get in touch with you soon.",
	dateformat: "DD, d MM, yy",
	// adapter file and fine-tune css
	adapterfile: "ContactForm.JS.DreamGuitar.xml",
	finetunecss: "ContactForm.JS.DreamGuitar.css",
	// e-mail settings
	email: "acid_martin@yahoo.com",
	subject: "DreamGuitars Query",
	defaultfromemail: "postmaster@dreamguitars.com",
	messagebodyheading: "Hello,%0A%0ABelow are the results of the feedback form submitted at DreamGuitars:%0A%0A",
	labelvaluedelimiter: ": ",
	// carbon copy message settings
	cctosender: true,
	cctosenderdefaultchecked: true,
	cctosendertext: "Send a copy of this form to my email",
	ccformfieldname: "email_box",
	ccsubject: "Copy of DreamGuitars Query",
	// form submission modal overlay and loading panel settings
	formsubmittingtext: "Contacting Server. Please, wait...",
	formsubmittingfont: "normal 14px 'Segoe UI', 'Trebuchet MS', Arial, Verdana, Serif",
	formsubmittingcolor: "#fff",
	formsubmittingtextalign: "center",
	formsubmittingoverlay: "#3b3b3b",
	submittingmessagewidth: "240",
	submittingmessageheight: "46",
	formsubmittingmsgbackground: "#3b3b3b",
	formsubmittingmsgborderradius: "large",
	formsubmittingmsgborderdithercolor: "#777",
	formsubmittingmsgspinnerposition: "center",
	formsubmittingmsgoverlayopacity: "6",
	formsubmittingmsgspinnerurl: "Loading_00.gif",
	formsubmittingmsgroundedcorners: "true, true, true, true",
	// message for Internet Explorer 6 users
	ie6message: "<p>We are sorry for the inconvenience, but your browser (Internet Explorer 6) is not supported by the contact form.</p><p>To contact us, please use Internet Explorer 7, Internet Explorer 8, Mozilla FireFox, Opera, Apple Safari or Google Chrome.</p>"
});
</script>

The properties of the initialization method are explained in detail later in this manual, and this default setup can be taken directly from the distribution file of ContactForm.JS - Common/Includes/index.php or any other demo page.

Quick Tip: Please, note that if you are testing at your http://localhost and your server is not set to send emails the form will not send any. If your forms created with ContactForm.JS fail to send emails locally, check your server settings or test on a live server.

5. Reload the page. If the steps have been followed correctly, at this stage the form should be up and running with its default configuration.

Properties of the pageload() and demand() Methods of ContactForm.JS

ContactForm.JS has two methods for form initialization - on page load and on demand. Please, refer to the demos (the Favorite Guitarist Form and Load on Demand page) included in the distribution of the control for information about how to load a form on demand without refreshing the page. The properties of the two methods are the same and are explained below.

The properties of the pageload() and demand() methods of ContactForm.JS should be used to customize and adapt the form for the needs of the website it is used. You can use the code in Step 5 of the previous chapter as a reference. All properties should be separated with comma.

enabled

Boolean (true or false). If set to false, the form will not render and will just display the string that is specified in the formdisabledmessage property.

showresetbutton

Boolean (true or false). If set to false, the "reset form" button won't render. Recommended is false.

disableaftersubmit

Boolean (true or false). If set to false, the submit button of the form will be disable after form submission to prevent spam. Recommended is true.

skin

The skin that will be applied to the current form. Refer to the Skins topic in this manual for more information about the skinning of ContactForm.JS.

width

Width of the control in pixels. Do not px, just leave the number; otherwise the control will throw an exception.

submitbuttontext

Text for the submit button of the form.

resetbuttontext

Text for the reset button of the form.

formdisabledmessage

The message that is displayed if the enabled property of the form is set to false.

formsubmittedtext

Custom message that is displayed after the form has been submitted.

dateformat

Default format of the date values created with the date picker form fields.

QUICK TIP: If you are unsure how to set the dateformat variable, check this article.

adapterfile

The adapter .xml file associated with the current form. Please, refer to the Adapter Files and Understanding the Adapter Files topics in this manual for detailed information about their purpose, usage and creation.

finetunecss

The fine-tune CSS file associated with the current form. A fine-tune CSS file is a small .css file that allows additional customization of the form it is associated with - for example - setting of input widths, etc. The fine-tune CSS files are stored in the ContactForm.JS/FineTuneCss and this location cannot be changed.

email

Email to which the form results will be sent to after submission.

subject

Subject of the email with the form results that is sent to the address specified in the email property.

defaultfromemail

"From" email that will appear in your mailbox when form results message is received, for example:

defaultfromemail: "postmaster@mysite.com"
messagebodyheading

Greeting part of the messages that are sent by this form. You can use %0A to add new lines to it. For example:

messagebodyheading: "Hello,%0A%0ABelow are the results of the feedback form submitted at DreamGuitars:%0A%0A"

... Will look like this in your mailbox:

Hello,

Below are the results of the feedback form submitted at DreamGuitars:

--- rorm results follow ---

labelvaluedelimiter

Separating character of the label and values associated with a form field in the mailbox. For example:

Form Field Label - Submitted Form Field Data
cctosender

Boolean (true or false). If set to false, the form will render a checkbox, which when checked will send a copy of the form to the user that has submitted it.

cctosenderdefaultchecked

Boolean (true or false). If set to false, the checkbox of the cctosender will be checked by default.

cctosendertext

The label text associated with the checkbox of the cctosender and cctosenderdefaultchecked properties.

ccformfieldname

The name of an existing formfield that is specified in the adapter file. For example, if the name of the email box in the current form is "visitor_email":

<formfield type="email" name="visitor_email " labeltext="Your Email" validate="true" />

... The value of the ccformfieldname must be:

ccformfieldname: "visitor_email "

If the element name specified in the property does not exist, ContactForm.JS will throw an exception. Please, refer to Exception Handling topic in this manual for more information about exceptions in ContactForm.JS.

ccsubject

Default subject of the carbon copy with the form results sent to your visitors.

ie6message

Internet Explorer 6 is no longer supported by ContactForm.JS and when users with that browsers visit the page on which resides a form created by ContactForm.JS they will see this message. The value of the property can contain HTML.

formsubmittingtext

Text of the loading message during the AJAX form submission.

formsubmittingfont

CSS string - form properties of the loading message during the AJAX form submission.

formsubmittingcolor

HEX color value - color of the loading message during AJAX form submission.

formsubmittingtextalign

CSS property value for text-align. Allows setting text alignment of the loading message.

formsubmittingoverlay

HEX color value. Allows to set background color of the semi-transparent modal overlay during form submission.

submittingmessagewidth

Width of the the loading message box upon AJAX form submission.

submittingmessageheight

Height of the the loading message box upon AJAX form submission.

formsubmittingmsgbackground

HEX color value. Allows the setting of background color to the loading message box upon form submission.

formsubmittingmsgborderradius

Border-radius of the loading message box. Accepted values are large, medium and small.

formsubmittingmsgborderdithercolor

HEX color value. Alows to set antialiasing color to the rounded corners of the loading message box so it dithers better with the color specified in the formsubmittingoverlay property.

formsubmittingmsgspinnerposition

Spinner image position within the loading message box.

formsubmittingmsgoverlayopacity

Opacity rate of the modal overlay.

formsubmittingmsgspinnerurl

Filename of the animated .gif spinner image. The location of the spinners in ContactForm.JS is ContactForm.JS/LoadingPanel.JS/LoadingIndicators. You can create your own loading images at http://preloaders.net and http://www.ajaxload.info/.

formsubmittingmsgroundedcorners

Boolean (true or false). The four values represent the rounded corners of the loading message box clockwise. If a values is false, the respective corner will not be rounded.

Adapter Files

The adapter files of ContactForm.JS make the creation of any forms with any number and type of input boxes with various options possible. With an adapter file you can:

  • Create a form with any form fields.
  • Define the order in which the input boxes will render on the page.
  • Associate each input field with a label and make it accessible.
  • Determine whether an input field should validate or not.
  • Determine the type of the input box - textbox, email, url, numeric, country dropdown, html box, combo, checkbox, date picker, multiline checkbox or radio button group.

You can associate any number of adapter files with ContactForm.JS and hence have an arbitrary number of different feedback forms on your pages. The only limitation is that you can have only one form created by ContactForm.JS on a single page.

An adapter file is a simple .xml file that can be edited with any text editor. The adapter files of ContactForm.JS are stored in the ContactForm.JS/Adapters directory of the distribution of the control and this location cannot be changed.

To learn how to create custom forms with adapter files, please refer to the Understanding the Adapter Files topic in this manual.

The format of the adapter file is pretty self-explanatory and you can easily learn how to create adapter files for your form by referring to the adapter files included in the distribution of the control located at ContactForm.JS/Adapters.

Understanding the Adapter Files

An adapter file is a simple .xml file that can be edited with any text editor. The adapter files of ContactForm.JS are stored in the ContactForm.JS/Adapters directory of the distribution of the control and this location cannot be changed.

The format of the adapter file is pretty self-explanatory and you can easily learn how to create adapter files for your form by referring to the adapter files included in the distribution of the control located at ContactForm.JS/Adapters.

The <formfield /> Element

Apart from the <contactformjs //> root tag of the adapter file, the main element of an adapter file is the <formfield />. The <formfield /> represents a single HTML input element that will be rendered on the page.

11 types of <formfield /> elements are supported by ContactForm.JS. To specify an input, use the type attribute of the form field:

  • <formfield type="textbox" /> - renders a single line input box whose validation, if set to true looks for empty value as users type.
  • <formfield type="email" /> - renders a single line input box whose validation, if set to true looks for incorrect email format and empty value as users type.
  • <formfield type="url" /> - renders a single line input box whose validation, if set to true looks for incorrect URL format and empty value as users type.
  • <formfield type="numeric" /> - renders a single line input box whose validation, if set to true looks for non-numeric or empty value as users type. It can be used for input boxes that require phone numbers, for example.
  • <formfield type="country" /> - renders a drop down with the countries of the world. The country array file is located at ContactForm.JS/ContactForm.JS/Scripts/ContactForm.JS.Countries.js. If validation is turned on, users cannot submit the form until they select a country from the list.
  • <formfield type="radiobuttons" /> - renders a radio button group and requires <item /> elements. The control does not validate and requires a zero-index value for default selected radio button.
  • <formfield type="combo" /> - renders a dropdown with custom options, specified as <item /> elements. If validation is turned on, users cannot submit the form until they select an item from the list.
  • <formfield type="checkbox" /> - renders a single checkbox whose validation, if set to true looks-up the checked / unchecked state of the control.
  • <formfield type="datepicker" /> - renders a single line input box, that when clicked opens a calendar, so users can select dates. If validation is turned on, users cannot submit the form until they select a date. The date format is set via the dateformat property of the pageload() and demand() methods of ContactForm.JS.
  • <formfield type="multiline" /> - renders a multiline text area whose validation, if set to true looks for empty value as users type.
  • <formfield type="html" /> - renders the HTML that is specified as its content. This type of <formfield /> does not validate and does not submit anything to the server. It can be used as instructions placeholder, semantic separation of form elements or anything else.
Other Attributes of <formfield />

Along with type, there are several other attributes required by a <formfield /> that differ among the different types with a few exceptions:

  • name - mandatory for all form fields except for <formfield type="html" />. The name attribute should be a unique value that will be associated with the control specified in the type attribute. Each <formfield /> should be associated with a unique name. No spaces or special characters are allowed in the property values.
  • labeltext - the descriptive text label that will be associated with the form field. This attribute is required for all form field types except for the <formfield type="radiobuttons" /> and <formfield type="html" />.
  • validate - requires a Boolean value (true or false). When set to true, the respective form field will start validating itself upon user input or interaction. It is required by all form fields except by <formfield type="radiobuttons" /> and <formfield type="html" />.
  • defaultselecteditem - requires a zero-based integer representing the default selected item of <formfield type="country" />, <formfield type="radiobuttons" /> and <formfield type="combo" />. The value of this attribute is disregarded if the validate property of the respective form field is set to true.
  • defaulttextifvalidateistrue - if the validation of the respective control is turned on, the string specified in this attribute will render as default text informing that users should select another value in order to pass the validation. The attribute is required by <formfield type="country" /> and <formfield type="combo" />.
  • groupdescription - required by <formfield type="radiobuttons" /> and submitted as label text for the selected radio button. The value set in this attribute is used only when form is submitted and is not visible on the page.
  • selected - the attribute is required by <formfield type="checkbox" /> and should be a Boolean - true or false. If set to true, a selected checkbox will render on the page. If both selected and validate attributes of a <formfield type="checkbox" /> are set to true, ContactForm.JS will throw an exception, because the validation routine of that type looks up the checked / unchecked state of the control and a checkbox selected by default is actually validated already.
  • groupdescription - required by <formfield type="radiobuttons" />. Its value should be a unique name associated with the respective radio button group.
The <item /> Element

The <item /> is required by <formfield type="radiobuttons" /> and <formfield type="combo" />.

If set to <formfield type="radiobuttons" />, each <item /> will represent a single radio button of the group.

If set to <formfield type="combo" />, each <item /> will render a single <option /> of the dropdown.

The <item /> element requires two attributes:

  • value - this string will be sent to server when the form is submitted.
  • labeltext - this string is the label text of the respective radio button or option of a dropdown.

Skins

ContactForm.JS supports skinning via automatic skinning mechanism. The full version of the control includes 12 skins, while the trial version is shipped with 1 skin only. Please, refer to the Differences between the Trial and the Full Version topic of this manual for more information about the differences between the trial and the full versions of the control.

Unlike the previous versions of the control, since version 2.0, ContactForm.JS does not have skins of its own, as it is made-up of two other Acid.JS controls - Forms.JS and LoadingPanel.JS and a third-party control - the jQuery.UI.DatePicker.

The runtime of the component will automatically load the CSS files associated with the skins of Forms.JS and the date picker. The name of the skin is the name of an existing folder inside the directories of these controls, for example:

  • ContactForm.JS/Forms.JS/Skins/Vista/

The skins of jQuery.UI.DatePicker are stored in:

  • ContactForm.JS/DatepickerSkins

... And also load automatically according to the value of the skin property of the pageload() method of the form. The skin name is a part of the file name of the CSS file, for example:

  • ContactForm.JS/DatepickerSkins/DatePicker.Vista.css.

In order to create a custom skin for the control, you need to actually create skins for:

The easiest way to create a custom skin named MyNewSkin is to modify an existing one. If, for example your custom skin will be based on Vista, you have to:

  • Copy the folder Vista in Forms.JS (ContactForm.JS/Forms.JS/Skins).
  • Rename the folder, for example to MyNewSkin.
  • Open Styles.css files in the MyNewSkin folder with your editor and replace all occurrences of Vista with MyNewSkin in the CSS code, and then save file.
  • Copy DatePicker.Vista.css, and rename it to DatePicker.MyNewSkin.css (ContactForm.JS/DatepickerSkins).
  • Set skin: "MyCustomSkin" in contactformjs.pageload().
  • Reload the page. If everything is done correctly, the control will be styled with a copy of the Vista skin, i.e. your MyCustomSkin.
  • Do all necessary changes in the CSS code and the images of the skin.

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.

Exception Handling

Since version 2.0, the control implements custom exception handling that is useful for debugging and troubleshooting. If you see the following message at the place where your form is expected:

ContactForm.JS threw an exception. Check your browser's error console for details.

... Check your browser's error console for more information about the error and how to fix it.

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 forms. Using the trial version on live servers 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.

The trial version is fully functional, but:

  • Displays a distinctive trial message and purchase link on each form.
  • Appends a trial message to all of the emails sent by the form.
  • Only one skin (Mac) is included in the trial distribution of the control.

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

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.