Table of contentsSearch
InstallationTop
How to install
To install the form into your web page, there are 5 things you must do:
- 1. Copy the HTML code for the form into your web page
- 2. Copy the CSS stylesheet link(s) into your web page
- 3. Copy the JavaScript links into your web page
- 4. Configure the form to send messages to your email address
- 5. Upload the
quform
folder to your web server
Each step is explained in more detail below.
1. Copy the HTML code for the form into your web page
Open the index.html
file and locate the HTML code for the
form, it is located between the HTML comments <!-- To copy the form start here -->
and <!-- To copy the form end here -->
. Select all of this code then copy and paste
it into the body of your web page.
2. Copy the link to the CSS stylesheet into your web page
There is one main stylesheet used by the form, the base.css
located in quform/css/
The other optional stylesheet is a Theme style, these are located in quform/themes/
. There are 6 options for Themes 3 dark and 3 light, for more information on this visit the Changing and adding a theme section.
- 1. Base:
- quform/css/base.css
- 2. Themes:
- quform/themes/light/light.css
- quform/themes/light/rounded.css
- quform/themes/dark/dark.css
- quform/themes/dark/rounded.css
- quform/themes/minimal/light.css
- quform/themes/minimal/dark.css
Here is an example of the stylesheets in the head. NB: if you change the theme stylesheet you will also need to add a new class into the quform-outer
div. You can get more information on this in the Changing and adding a theme section.
<link rel="stylesheet" type="text/css" href="quform/css/base.css" /><!-- Base form styles --> <link rel="stylesheet" type="text/css" href="quform/themes/light/light.css" /><!-- Theme styles -->
3. Copy the JavaScript links into your web page
The form requires the 3 JavaScript files shown below, to include them in your web page, copy the lines below and
paste them into your web page. Note: if your web page already uses the jQuery library you can skip copying the first line, jQuery needs to be version
1.5.1 or later for the form to work in Internet Explorer 9. The best place to put these is at the end of the page, just before the closing </body>
tag.
<script type="text/javascript" src="quform/js/jquery-1.8.3.min.js"></script> <script type="text/javascript" src="quform/js/plugins.js"></script> <script type="text/javascript" src="quform/js/scripts.js"></script>
4. Configure the form to send messages to your email address
To configure the form, open quform/process.php
and search for the code below.
$config['recipients'] = '';
Inside the single quotes enter the email address that you would like to recieve the submitted form data. For example:
$config['recipients'] = 'me@example.com';
Set the "From" address
While you are in quform/process.php
you should also set the "From" email address,
search for the term $config['from'] = ''; and enter an email address inside the single quotes.
Any emails you get from the script will appear to be sent from this address. Some web hosts will block emails sent from an
email address that is not hosted on their servers, so it's usually a good idea to set this
to an email address that has the same domain as the site that the form is hosted on.
$config['from'] = 'company@example.com';
If you want to include your name or company name in the "From" address you can also use the code below.
$config['from'] = array('company@example.com' => 'Company');
Further configuration
You have now completed is the minimal setup that is required for the form to work, you can now upload the form to your web server as described in step 5. You can also continue to change the settings in process.php at this time or upload additional changes as you build your form. Each setting in process.php is accompanied by a comment explaining what it does and what the options are. You can also refer the customization sections below for further help.
5. Upload the quform
folder to your web server via FTP
You should now upload the quform
folder so that it resides in the same
place as your web page containing the form. The quform
folder and your PHP/HTML file should be in the same folder on your web server.
If this setup is not possible, just change the action=""
attribute of the <form>
tag to point to the location of the quform/process.php
file
relative to the page with your form on it.
Now visit your web page in your browser, the form should appear and the contact form should work correctly. See the troubleshooting section below if you are having problems.
Customising your formTop
Adding a form element
To add a form element, there are three steps.
- 1. Pick a unique name for the element
- 2. Add the HTML for the form element to your web page
- 3. Add the form element to the
process.php
file to make the PHP script aware of the new form element
Each step is explained in more detail below.
1. Pick a unique name for the element
Choose a name for your new element that is not currently used by another element. The name should be all lower case and multiple words should be joined by an underscore.
For example, fax_number
.
2. Add the HTML for the form element to your web page
The easiest way to add another form element is to copy the existing HTML code from another element, including
all surrounding wrappers. Each element included with the form has comments surrounding it and the file example-all-elements.html
has example code
for most form elements you will ever need to use.
To copy the entire element,
you would select the all the HTML code between the comments. For example, lets say we wanted
to add a new required field called "Fax number". We would copy the HTML for the "Name" field by searching
in index.html for <!-- Begin Text input element, you will be taken to the code for the name
element, copy the code inside the HTML comments surrounding the name element. Paste the code in between the form elements that you would like your new element
to be between. You would then change all occurrences of "name" in your copied code with your
unique name "fax_number" (except in this case do not change the actual name attribute key i.e. it
should be name="fax_number"
NOT fax_number="fax_number"
on the
input), after all the highlighted changes have been made we have:
<!-- Begin Text input element --> <div class="quform-element quform-element-text"> <div class="quform-spacer"> <label for="fax_number">Fax number <span class="quform-required">*</span></label> <div class="quform-input"> <input id="fax_number" type="text" name="fax_number" /> </div> </div> </div> <!-- End Text input element -->
3. Add the form element to the process.php
file to make the PHP script aware of the
new form element
To make the PHP script aware of the new element, you will need to edit the quform/process.php
file.
You will need to create a new Quform_Element object for your new field, if you don't know how to do that just copy the existing code
for the name element. In process.php
search for the term $name and you should find
4 lines of PHP code. Copy and paste this code above or below the existing 4 lines of code and then change everything that says "name" to your unique name "fax_number", giving us:
$fax_number = new Quform_Element('fax_number', 'Fax number'); $fax_number->addFilter('trim'); $fax_number->addValidator('required'); $form->addElement($fax_number);
IMPORTANT: The parts in red above must match the name=""
attribute of the form element in the HTML, they should both be identical
to your unique name you created in Step 1. This tells the PHP script what element you are referring to.
The filter you are adding to the element in the code above will trim whitespace from the start and end of the value submitted by the form user. The validator you are adding in the code above will make the field required. If you do not want those filters or validators for the element just delete the line that adds them. For more help on Filters and Validators see the Advanced form customisation section below.
The other text we changed ('Fax number'
) sets the label in the email and the
non-JavaScript version of the form.
Adding a Date form element
Adding a Date element is slightly different from adding any other element, there are three steps.
- 1. Pick a unique name for the element
- 2. Add the HTML for the form element in your web page
- 3. Add the form element to the process.php file to make the PHP script aware of the new form element
Each step is explained in more detail below.
1. Pick a unique name for the element
Choose a name for your new element that is not currently used by another element. The name should be all lower case and multiple words should be joined by an underscore.
If this is the first date element in your form a good name would be date
.
2. Add the HTML for the form element in your web page
The easiest way to add another form element is to copy the existing HTML code for the element, including
all surrounding wrappers. There is an example of the Date element HTML in the
file example-all-elements.html
. So to copy the entire element
you would select the all the HTML code between the comments:
<!-- Begin Date element --> ... <!-- End Date element -->
Paste the HTML into your own form in the position you desire.
3. Add the form element to the process.php file to make the PHP script aware of the new form element
To make the PHP script aware of the new element, you will need to edit the file quform/process.php
.
You will need to create a new Quform_Element_Date object for your new field, if you don't know how to do that just copy the existing code
for the Date element in the file quform/process-all-elements.php
. If your unique name from step one is not date
,
replace the red parts of the code with your unique name.
$date = new Quform_Element_Date('date', 'Date'); $date->addValidators(array('required', 'date')); $form->addElement($date);
IMPORTANT: The second occurrence date in red above must match the first part of the name=""
attribute of the select elements in the HTML (before the [month], [day], [year] parts). This tells the PHP script
what element you are referring to.
Adding a Time form element
Adding a Time element is slightly different from adding any other element, there are three steps.
- 1. Pick a unique name for the element
- 2. Add the HTML for the form element in your web page
- 3. Add the form element to the process.php file to make the PHP script aware of the new form element
Each step is explained in more detail below.
1. Pick a unique name for the element
Choose a name for your new element that is not currently used by another element. The name should be all lower case and multiple words should be joined by an underscore.
If this is the first date element in your form a good name would be time
.
2. Add the HTML for the form element in your web page
The easiest way to add another form element is to copy the existing HTML code for the element, including
all surrounding wrappers. There is an example of the Time element HTML in the
file example-all-elements.html
. So to copy the entire element
you would select the all the HTML code between the comments:
<!-- Begin Time element --> ... <!-- End Time element -->
Paste the HTML into your own form in the position you desire.
3. Add the form element to the process.php file to make the PHP script aware of the new form element
To make the PHP script aware of the new element, you will need to edit the file quform/process.php
.
You will need to create a new Quform_Element_Time object for your new field, if you don't know how to do that just copy the existing code
for the Time element in the file quform/process-all-elements.php
. If your unique name from step one is not time
,
replace the red parts of the code with your unique name.
$time = new Quform_Element_Time('time', 'Time'); $time->addValidators(array('required', 'time')); $form->addElement($time);
IMPORTANT: The second occurrence of time in red above must match the first part of the name=""
attribute of the select elements in the HTML (before the [hour], [minute] parts). This tells the PHP script
what element you are referring to.
Adding a multiple value form element
There are a couple of elements that can have multiple values, for example, a group of checkboxes or a multiple select element.
When adding these elements, you need to add a pair of square brackets to the name attribute of the element []
.
To add a multiple form element, there are three steps.
- 1. Pick a unique name for the element
- 2. Add the HTML for the form element in your web page
- 3. Add the form element to the process.php file to make the PHP script aware of the new form element
Each step is explained in more detail below.
1. Pick a unique name for the element
Choose a name for your new element that is not currently used by another element. The name should be all lower case and multiple words should be joined by an underscore.
Because this is a multiple value element, you should also add a pair of square brackets to the end. For example, pizza_toppings[]
.
2. Add the HTML for the form element in your web page
The easiest way to add another form element is to copy the existing HTML code for the element, including
all surrounding wrappers. There is an example of most HTML form elements and the code you should use in the
file example-all-elements.html
. Each element included with the form has comments surrounding it. So to copy the entire element
you would select the all the HTML code between the comments. For example, lets say we wanted
to add a multi checkbox field. We would copy the HTML for the "Multi checkbox" element by searching inside
example-all-elements.html for the term Multi Checkbox
then copying the HTML for the element and pasting the code in between the form elements that you would like your new element
to be between. You would then change all occurences of "multi_checkbox[]" in your copied code with the name you want to give your new element, below I have given
it the name "pizza_toppings[]" so I've updated all surrounding wrappers aswell to reflect this and so you can style
the element individually if you need to.
<!-- Multi Checkbox element --> <div class="quform-element quform-element-checkbox"> <div class="quform-spacer"> <label>Multi checkbox <span class="quform-required">*</span></label> <div class="quform-input"> <div class="quform-options"> <div class="quform-option"> <label><input name="pizza_toppings[]" value="Ham" type="checkbox" /> Ham</label><br /> </div> <div class="quform-option"> <label><input name="pizza_toppings[]" value="Pepperoni" type="checkbox" /> Pepperoni</label> </div> <div class="quform-option"> <label><input name="pizza_toppings[]" value="Pineapple" type="checkbox" /> Pineapple</label> </div> <div class="quform-option"> <label><input name="pizza_toppings[]" value="Mushrooms" type="checkbox" /> Mushrooms</label> </div> <div class="quform-option"> <label><input name="pizza_toppings[]" value="Olives" type="checkbox" /> Olives</label> </div> </div> </div> </div> </div> <!-- End Multi Checkbox element -->
3. Add the form element to the process.php file to make the PHP script aware of the new form element
To make the PHP script aware of the new element, you will need to edit the file quform/process.php
.
You will need to create a new Quform_Element object for your new field, if you don't know how to do that just copy the existing code
for the one of the existing elements then change the name to suit your new element or use the code below. The difference with multiple elements
is the you need to add []
to the end of the name in process.php also. Continuing the above example would give us:
$pizzaToppings = new Quform_Element('pizza_toppings[]'); $form->addElement($pizzaToppings);
IMPORTANT: The part in red above must match the name=""
attribute of the form element in the HTML. This tells the PHP script
what element you are referring to.
Removing a form element
To remove a form element, there are two steps.
- 1. Remove the HTML for the form element in your web page
- 2. Remove the form element from the process.php file to make the PHP script aware that the form element is no longer there
Both steps are explained in more detail below.
1. Remove the HTML for the form element in your web page
Each form element and it's associated wrappers are commented individually in index.html. Find the form element you want to remove by looking at the class names of the elements, each element has their own class names that should help you identify them. Once you've found it, delete the HTML code between the comments surrounding the element. For example, to remove the Subject element, search index.html for the term <!-- Begin Subject and delete the lines between the start and end comments surrounding the subject element HTML. Proceed to step 2.
2. Remove the form element from the process.php file to make the PHP script aware that the form element is no longer there
In quform/process.php
, locate the code that creates the form element you want to remove.
If you wanted to delete the phone element, search for the term $subject, the code you are looking for would be:
$subject = new Quform_Element('phone'); $subject->addFilter('trim'); $form->addElement($subject);
Remove (or just comment out) these lines.
Making a field required
A required field simply has a validator called required
added to it. You can use the
method addValidator()
on your element to add the required validator.
In process.php
enter code on a new line to
add the validator, for example if you wanted to make the subject field required, search for the term $subject
and add the highlighted line of code as shown below.
$subject = new Quform_Element('subject'); $subject->addFilter('trim'); $subject->addValidator('required'); $form->addElement($subject);
It may also be a good idea to add an asterisk to the element label on your web page to let users know that the element is now required. Here is the preset HTML we have for this on a form element label:
<label>Grouped file upload <span class="quform-required">*</span></label>
Adding an element description
Simply add the highlighted HTML inside the input wrapper under the input, select textarea etc.
<div class="quform-input"> <input type="file" id="upload" name="upload" /> <p class="quform-description">All files allowed. Maximum size 10MB.</p> </div>
Changing the required error message - "This field is required"
To change the required message, pass in an additional parameter to the addValidator
line, containing
an array of options with your message, the syntax and array nesting is important. Copying the code here is a good idea,
just be sure to change $element
to match your element's unique name.
$element->addValidator('required', array( 'messages' => array('required' => 'This is a required field') ));
NOTE: if you are having any problems with this, you can change the message directly in the file lib/Quform/Validator/Required.php near the top of the file. The same goes for the other validators.
Making a field not required
To make a field not required you need to remove the 'required' validator. Open process.php
and find the PHP code for the element you want to change. There should be code that looks like the following:
$element->addValidator('required'); // Single validator or $element->addValidators(array('required', 'email')); // Multiple validators
If the element has the single validator line of code, simply delete or comment out the line adding the required validator. If the element has the multiple validators line, remove the 'required' string and the comma after it. The multiple validators line would now look like this:
$element->addValidators(array('email')); // Multiple validators (required removed)
It might also be a good idea to remove the asterisk from the element label on your web page to let users know that the field is no longer required.
Input and button sizes
There are a list of CSS preset sizes for form input and button sizes. Use the classes listed below to modify your element sizes quickly and consistently throughout your form.
Input, select and textarea sizes
You can add any of the styles below to the element outer wrapper (quform-element
).
Add the class like this example:
<!-- Begin Text input element --> <div class="quform-element quform-small quform-element-text">
- quform-small
- quform-med
- quform-large
- quform-huge
- quform-full-width
- quform-fat
Button sizes
You can add any of the styles below to the button outer wrapper (quform-submit
).
Add the class like this example:
<!-- Begin Submit button --> <div class="quform-submit quform-button-small">
- quform-button-small
- quform-button-med
- quform-button-large
- quform-button-full-width
- quform-button-fat
If you would like to change the sizes of these styles you can find them in the base.css, search the document for /*Preset element sizes for the start of the code.
Styling forms
How to style
Quform comes with three themes; Dark and Dark rounded, Light and Light rounded, and Minimal Light and Dark. You can choose to style the form using a theme or you can start with the base styles and create your own styles in another stylesheet.
Probably the simplest method of making your form design is to copy an existing Qufrorm theme, change the name and edit the styles and images within it. More details on this are given below.
Adding / changing a theme
Follow these steps to change the Quform theme to one of the four theme options available. I'm using Quform Light Rounded in this example:
1: Add the stylesheet for the theme in the header. The theme CSS should be below the base.css
link. Like this:
<link rel="stylesheet" type="text/css" href="quform/css/base.css" /><!-- Base form styles --> <link rel="stylesheet" type="text/css" href="quform/themes/light/rounded.css" /><!-- Theme styles -->
Here are the stylesheet links for the other available themes:
- Light - quform/themes/light/light.css
- Light Rounded - quform/themes/light/rounded.css
- Dark - quform/themes/dark/dark.css
- Dark Rounded - quform/themes/dark/rounded.css
- Minimal Light - quform/themes/minimal/light.css
- Minimal Dark - quform/themes/minimal/dark.css
2: Add a class to quform-outer
wrapper specifying the Theme class name.
Locate the div with class name quform-outer – this is at the very start of the form HTML.
Add the class quform-theme-light-rounded
to use the Light Rounded theme. Like this:
<div class="quform-outer quform-theme-light-rounded">>/div>
Here are the class names for the other available themes:
- Light - quform-theme-light-light
- Light Rounded - quform-theme-light-rounded
- Dark - quform-theme-dark-dark
- Dark Rounded - quform-theme-dark-rounded
- Minimal Light - quform-theme-minimal-light
- Minimal Dark - quform-theme-minimal-dark
Creating a new theme:
You can either create a new theme by copying one of the existing theme folders and editing the CSS or use the Blank theme in resources/themes/blank
In both cases you will need to do the following:
- 1: Change the name of the directory / folder name and add it to
quform/themes/
folder. - 2: Change the name of the CSS file(s) within the theme.
- 3: Change the details in the comment at the top of the document with your new themes details.
- 4: Change the main selector for all of the classes in the form. You can use find and replace (usually ctr+F) to do this. If you copied the light theme for example find
.quform-theme-light-light
and replace all with your new name. If you are starting with the Base theme find and replace all.quform-theme-blank-new.
You could replace this class with any name you like. However, we would recommend using the structure below especially if you would like to sell or share your new theme. Whatever this new class name is must be added to the quform-outer
div as shown above in the Adding / changing a theme section.
.quform-theme-[Theme folder name]-[Theme CSS file name]
Non-JavaScript layout
We have minimally styled a page that non JavaScript users will see errors and the success message on using neutral colors.
If you want to change the style of this page edit the file quform/nojs.php
. To see what the page
looks like, disable JavaScript in your browser and submit the form.
Label options
There are two label positioning options available with the current CSS, left labels and above labels (default). You can easily swap between them simply by adding a new class on the outer wrapper of any Element, a Group wrapper or the Form outer wrapper. The current CSS supports 3 levels, if you need more please contact support.
Changing the label position
Here is an example of all three positions to add the label position class. The two class options are listed below.
Labels set on the form outer wrapper. This will effect all elements in the form.
<!-- To copy the form HTML, start here --> <div class="quform-outer quform-theme-light-rounded quform-labels-left">
Labels set on the Group outer wrapper. This will effect all elements in the Group.
<!-- Begin 2 column Group --> <div class="quform-group-wrap quform-labels-above quform-group-style-plain quform-group-alignment-left">
Labels set on the Element outer wrapper. This will effect only one element.
<!-- Begin Text input element --> <div class="quform-element quform-labels-left quform-element-text">
Class names:
- Left labels: quform-labels-left
- Above labels: quform-labels-above (default)
Changing layout using Groups
Most complex layouts can be achieved using the Groups. For more advanced layouts you will need to modify your own CSS. Labels also have two options of being above or to the left of the input element.
Adding a group and configuring:
Here is an example of a Group HTML layout structure. This example has elements floating left in 2 columns and two rows, it also has a bordered style. The changeable classes have been highlighted.
<!-- Begin 2 column Group --> <div class="quform-group-wrap quform-group-style-bordered quform-group-alignment-left"> <div class="quform-group-elements"> <div class="quform-group-row quform-group-row-2cols"> <!-- Begin Text input element --> <div class="quform-element quform-element-text"> ... </div> <!-- End Text input element --> <!-- Begin Text input element --> <div class="quform-element quform-element-text"> ... </div> <!-- End Text input element --> </div> <div class="quform-group-row quform-group-row-2cols"> <!-- Begin Text input element --> <div class="quform-element quform-element-text"> ... </div> <!-- End Text input element --> <!-- Begin Text input element --> <div class="quform-element quform-element-text"> ... </div> <!-- End Text input element --> </div> </div> </div> <!-- End 2 column Group -->
Setting the group column alignment
You can choose to either have the columns in your Group all using proportional space or you can choose to have the side by side using their true width.
Add the class quform-group-alignment-proportional
or quform-group-alignment-left
to the Group wrapper div which has the class name quform-group-wrap
. Here is an example:
Left aligned group elements:
<!-- Begin 2 column Group --> <div class="quform-group-wrap quform-group-style-bordered quform-group-alignment-left">
Proportionally aligned group elements:
<!-- Begin 2 column Group --> <div class="quform-group-wrap quform-group-style-bordered quform-group-alignment-proportional">
Plain groups and bordered group style
You can choose to have a pre designed bordered box around your group or you can have the group plain – with no styles.
Add the class quform-group-style-bordered
or quform-group-style-plain
to the Group wrapper div which has the class name quform-group-wrap
. Here is an example:
Bordered group class:
<!-- Begin 2 column Group --> <div class="quform-group-wrap quform-group-style-bordered quform-group-alignment-proportional">
Plain group class:
<!-- Begin 2 column Group --> <div class="quform-group-wrap quform-group-style-plain quform-group-alignment-proportional">
Changing label position within a Group
If you like you can choose to change the label style for all elements within a certain group. You can also change this for any nested Groups.
Add the class quform-labels-above
or quform-labels-left
to the Group wrapper div which has the class name quform-group-wrap
. Here is an example:
Labels above in Group
<!-- Begin 2 column Group --> <div class="quform-group-wrap quform-labels-above quform-group-style-bordered quform-group-alignment-proportional">
Lables left in Group:
<!-- Begin 2 column Group --> <div class="quform-group-wrap quform-labels-left quform-group-style-bordered quform-group-alignment-proportional">
NB: You can override the labels within a group for a particular element by adding one of the same classes to the element wrapper (quform-element
). Like this:
<div class="quform-element quform-element-text quform-labels-left">
Add a Group Title, Description or both.
Add the following HTML directly under the div with class name quform-group-elements
.
<div class="quform-group-title-description-wrap"> <div class="quform-group-title">Title</div> <p class="quform-group-description">Description</p> </div>
Simply remove the line for Title or Description if it is not required for your Group.
Creating columns
You can create up to 5 columns with the existing CSS. To create columns you first need to decide how many you would like. For this example I will make a 3 column layout with 2 rows.
You need to locate (or create) a quform-group-row wrapper
which you will apply a column number class on it, for example; quform-group-row-2cols
(full list shown below).
<!-- Begin 3 column Group --> <div class="quform-group-wrap quform-group-style-bordered quform-group-alignment-left"> <div class="quform-group-elements"> <div class="quform-group-row quform-group-row-3cols"> <!--Add three elements here--> </div> <div class="quform-group-row quform-group-row-3cols"> <!--Add three elements here--> </div> </div> </div> <!-- End 3 column Group -->
NB: Add the same number of form elements as columns to ensure the code works correctly.
List of column classes:
- quform-group-row-1cols
- quform-group-row-2cols
- quform-group-row-3cols
- quform-group-row-4cols
- quform-group-row-5cols
Nested Groups
You can add Groups inside Groups simply by adding the new group HTML inside the quform-group-row
, just like you would an element.
Here is an example of a two column Group with another two column Group nested in the 2nd column.
<!-- Begin 2 column Group --> <div class="quform-group-wrap quform-group-style-bordered quform-group-alignment-proportional"> <div class="quform-group-elements"> <div class="quform-group-row quform-group-row-2cols"> <!-- Begin Text input element --> <div class="quform-element quform-element-text"> ... </div> <!-- End Text input element --> <!-- Nested Group --> <div class="quform-group-wrap quform-group-style-bordered quform-group-alignment-proportional"> <div class="quform-group-elements"> <div class="quform-group-row quform-group-row-2cols"> <!-- Begin Text input element --> <div class="quform-element quform-element-text"> ... </div> <!-- End Text input element --> <!-- Begin Text input element --> <div class="quform-element quform-element-text"> ... </div> <!-- End Text input element --> </div> </div> </div> <!-- Nested Group --> </div> </div> </div> <!-- End 2 column Group -->
Changing the tooltips
The form tooltips are created using the qTip jQuery plugin. See the sections below on changing the tooltips.
Changing the text of a tooltip
The tooltips become active when the form element has the class quform-tooltip and it uses the
content of the title=""
attribute of the form element. If you want to change the text of a
tooltip, locate the form element in the HTML and change the title=""
attribute to the text you want to
display.
Adding or removing a tooltip
The tooltips become active when the form element has the class quform-tooltip and it uses the
content of the title=""
attribute of the form element. If you want to show
a tooltip on an element that doesn't have one already, add the class quform-tooltip to
the form element and add a title=""
attribute containing the text you
want to display in the tooltip.
To remove a tooltip from an element that already has one, remove the class quform-tooltip from the form element and remove the title=""
attribute.
Changing the look of the tooltips
The tooltip settings are contained in quform/js/scripts.js
, near the top of the file.
The current style is set by the classes line show below.
classes: 'qtip-default qtip-shadow quform-tt',
We are using the default tooltip style qtip-default
and adding on CSS3 shadows using qtip-shadow
. If you want to change these settings
then consult the documentation of qTip available at here.
You may also want to change the CSS styles of the tooltip, this is found at the in the base stylesheet (base.css), search for quform-tt.
Using a Help icon for the tooltip
There is an option to use a Help icon as the tooltip trigger. All you need to do is add the following CSS inside the label
.
The icon will change depending on the theme you are using and can be found in the theme image folder, quform/images/. If no theme is used it will be set to the default image found in the quform/theme/[theme]/images/.
<label for="first_name">First name <span class="quform-required">*</span> <span class="quform-tooltip-icon quform-tooltip" title="Tooltip text here"></span></label>
Changing the success message
The success message is the message that is displayed to the user when the form has been successfully
submitted. To change it open process.php
and search for the term $config['successMessage'],
it's right at the top of the file.
Change the success message to suit, you can add or remove as much HTML or text as you want there.
Since the string is enclosed in single quotes '
, if
you want to include a single quote in your text or HTML you will need to escape it, by adding a
backslash before it e.g. \'
Using form submitted data in the success message
You can also put submitted form data into the success message, such as the persons name. To do that just include the unique element name surrounded by percentage signs. For example to have a message containing the person's name:
$config['successMessage'] = 'Thank you for your message, %name%.';
Changing / adding notification email recipients
Email recipients are the list of email addresses who will be sent the data of the form when
it is submitted by the user. Some people may want this to go to multiple people so we have added
the facility to do that. To add or change the recipients, open process.php
and search
for the code below.
$config['recipients'] = '';
You will find the array of current recipients. If you just want the email to go to one email address, then just enter your email address inside the single quotes.
Single recipient
$config['recipients'] = 'me@example.com';
Multiple recipients
$config['recipients'] = array( 'me@example.com', 'you@example.com', 'another@example.com' );
Setting the "From" address
Open process.php
and search for the term $config['from'] = '';, you will see the
email address that is currently set as the "From" address, change it to suit.
$config['from'] = 'company@example.com';
Setting a name with your "From" address
You can also set a name to be sent with the address using the code below.
$config['from'] = array('company@example.com' => 'Company');
Setting the "From" address to the submitted email address
You can also set the from address to a submitted email address. To do that set it to be the unique element name surrounded by percent signs, e.g.
$config['from'] = '%email%';
Setting the "From" address to the submitted email address and name
You can also set the from address to a submitted email address and name combination. To do that, set it to be an array with the email unique element name surrounded by percent signs as the key and the name unique element name surrounded by percent signs as the array value, e.g.
$config['from'] = array('%email%' => '%name%');
Different notification email recipients based on chosen subject
You might want to change the recipients of the email based on the subject chosen by the form user. To do this you will need to change the recipients array
depending on which subject was chosen. The code below shows an example of how you would do this and this code will replace the existing
code that sets the notification recipients in process.php
. The string after case
should match the value
attribute of the option in the HTML of the form.
Different recipients per subject
switch($_POST['subject']) { case 'General enquiry': $config['recipients'] = array( 'email1@example.com', 'email2@example.com', 'email3@example.com' ); break; case 'Sales enquiry': $config['recipients'] = array( 'email4@example.com', 'email5@example.com', 'email6@example.com' ); break; case 'Support enquiry': $config['recipients'] = array( 'email7@example.com', 'email8@example.com', 'email9@example.com' ); break; default: // These will be the recipients if the subject does not match any above $config['recipients'] = array( 'email1@example.com', 'email4@example.com', 'email7@example.com' ); break; }
Changing the notification email subject
You can change the email subject to something that is more relevant to your form. To do this, open quform/process.php
and search for the term $config['subject']. Change the text inside the quotes to the subject you want. You can use placeholder values inside % signs to have the
value replaced by the form value of that name, such as in the default subject %name%
will be replaced by the submitted value of the "name" field.
Changing the label of an element in the email
The element's label is shown in two places:
- The error page for non-JavaScript users (nojs.php)
- The notification email
To change the label of the element, locate the line of code that creates the element in
process.php
. The second string of text you specify when creating the element
is the label.
If you wanted to change the type_the_word element to say Security code in the non-JavaScript page for example, then do this:
$captcha = new Quform_Element('type_the_word', 'Security code');
Changing the animated loading gif
Allan?
Changing the CAPTCHA image
It is possible that the captcha (Type the word) image that is included with the form does not match your design and you can change it quite simply.
We have created 8 CAPTCHA image styles that you can use by simply changing the image in the HTML. Here is a list of the image names:
- ar-carter-dark.png
- ar-carter-light.png
- courier-new-dark.png
- courier-new-light.png
- crime-scene-dark.png
- crime-scene-light.png
- dripping-marker-dark.png
- dripping-marker-light.png
In the Resources folder you will see a PSD (Photoshop) file so you can modify any one of our captcha images to suit your site.
- 1. Replace the file
quform/images/courier-new-light.png
with your new image - 2. You can choose any word you want for the image, if you change it from the default, you will need to
change the
process.php
file to change the token of the captcha validator to match the word contained in your new image. See below for more information.
In process.php
locate the configuration for the CAPTCHA field by searching
for the term $captcha, you will see the code below.
$captcha->addValidator('identical', array('token' => 'catch'));
Change the text catch to match the word or letters that are in your new CAPTCHA image.
NOTE: The CAPTCHA system is very simple and will prevent random form submissions by bots roaming around the internet (which happens a lot). It will not prevent targeted attacks however, but the chances of that happening are small and most other CAPTCHAs are not safe against targeted attacks either. We believe that an easy, simple CAPTCHA is a good trade off between the spam, usability and browser compatability of the form. Since at the end of the day you don't want to miss messages for new business by users being put off or unable to pass a complex CAPTCHA challenge. If you do need a more complex CAPTCHA field, see the sections below "Using reCAPTCHA" and "Using a custom CAPTCHA".
Redirecting to another page after the form is submitted
Open quform/process.php
and search for the term $config['redirect'].
You can set this variable to the URL you would like to redirect to:
$config['redirect'] = 'http://www.example.com/your_thanks_page.html';
Quform in a popup (lightbox)
You can make the form appear in a popup lightbox by following these instructions. We will use the Colorbox jQuery plugin as our lightbox script. There are 6 steps.
- 1. Download and extract the Colorbox files
- 2. Add the link to the Colorbox CSS file
- 3. Add the link to the Colorbox JS file
- 4. Hide the Quform in the HTML
- 5. Set up your trigger element
- 6. Add the JavaScript to show the Quform when the trigger is clicked
Each step is explained in more detail below.
1. Download and extract the Colorbox files
For the rest of this example, I am assuming that you have copied the root colorbox
folder from the zip file to inside the quform/js
folder.
2. Add the link to the Colorbox CSS file
Add a link to the CSS file in the head of your page e.g.
<link rel="stylesheet" type="text/css" href="quform/js/colorbox/example1/colorbox.css" />
Note: this example uses the "example1" Colorbox theme, if you choose another theme just replace example1 in the path with the theme that you have chosen.
3. Add the link to the Colorbox JS file
Then add a link to the jquery.colorbox-min.js
file, put this on the line before the link to
scripts.js file (but after the link to the jQuery library) in the head of the page e.g.
<script type="text/javascript" src="quform/js/colorbox/colorbox/jquery.colorbox-min.js"></script>
4. Hide the Quform in the HTML
With your Quform HTML already in your page, wrap the entire Quform HTML in a div
with the style display: none;
e.g.
<div style="display: none;"> // Your Quform HTML </div>
5. Set up your trigger element
Add your link that will trigger the form to be displayed, put this anywhere on your page outside the div you added above, e.g.
<a href="#" id="show-quform">Contact us</a>
6. Add the JavaScript to show the Quform when the trigger is clicked
Add this code to js/scripts.js
inside the document.ready() function (on line 3 for example):
$("#show-quform").colorbox({ inline: true, href: '.quform-outer' });
Additional options
You can pass in any other Colorbox options in the code in step 6 above, you may want to set a fixed height and width of the popup so that when the form errors show the scroll bars do not appear:
$("#show-quform").colorbox({ inline: true, href: '.quform-outer', height: 850, width: 400 });
For more options see the Colorbox documentation.
Confirm email field
To add a confirmation email field, create a new form element in the HTML by copying the HTML in the box below and paste it into your form.
<!-- Begin Text input element - Email confirm --> <div class="quform-element quform-element-text"> <div class="quform-spacer"> <label for="email_confirm">Confirm Email <span class="quform-required">*</span></label> <div class="quform-input"> <input id="email_confirm" type="text" name="email_confirm" /> </div> </div> </div> <!-- End Text input element - Email confirm -->
Add the following code to your process.php
file, at the element configuration section.
$emailConfirm = new Quform_Element('email_confirm', 'Confirm email address'); $emailConfirm->addValidator('required'); $emailConfirm->addValidator('emailConfirm', array( 'messages' => array('not_match' => 'The email addresses do not match') )); $emailConfirm->setIsHidden(true); $form->addElement($emailConfirm);
If you'd like, you can change the error message by changing the text 'The email addresses do not match'.
Displaying a global form error
If you want to display an error message above the form when there are errors, open the process.php
file
and search for the term // Form data failed validation. Make a new line immediately after this line
and add the following code.
$form->setError('There is an error with the submitted form. Please correct any errors below.');
Customize the message to suit, you can enter HTML so you are able to style your message to suit using CSS.
Advanced form customisationTop
Multiple forms
You may want to have more than one form on the same site but with different fields. Such as
a register form and a contact form. To do that, set up the first form as instructed in the
installation guide at the start of this document. To make the second form, copy the HTML for
the Quform again into the body of the page that you want your second form on and customise your new
form as described in the Customising your form section above. Then make a copy of the
quform/process.php
file and call it something else, for example quform/process-register.php
.
That file you should customise with the fields for your register form as described in the Customising your form section above. You should then
change the action
attribute of your register form so that it now points to your
new file e.g. <form class="quform" action="quform/process-register.php" ...
.
Multiple forms on the same page
To have more than one Quform on the same page, just copy the HTML for the Quform again and paste it into another area of your page. You will then need
to create a new config file and change the form action
attribute as described in the section Multiple forms above. There is only
one issue and that is that the form elements in the Quform have an id=""
attribute, so when you have more than one element with the same id on
a page, it is no longer valid HTML, however the form will still work. If you want your page to pass W3C validation then you should change or remove the id
attributes for the elements in the second form or change the name of the elements with the same id to something else.
Email settings
The emails sent out by the system are sent by the PHPMailer script, which allows you to do pretty much anything you need to do with sending emails in PHP.
The PHP code for the configuration and sending of emails is in process.php and you can find the start of it by searching for the term $mailer. If you need to make a change to these settings you can do it there, most of the code is commented to help you make changes. You should also check out this PHPMailer tutorial to help you customise the settings.
The email is sent using PHP's mail()
function by default, if your host does not
support this, you can change it to use a SMTP server instead. See the section further down
called "Sending emails via a SMTP server" for how to do this.
Customising the email
The email body is formatted in HTML, you can customise the email body to suit your needs. Edit the file quform/emails/notification.php
,
to customise it. We recommend using tables and inline CSS for maximum compatibility. Check out this page
for help.
Accessing submitted form data from inside the emails
You have access to the form object in the email $form
and therefore you can access submitted form data by using the code below. The
string you pass in to getValue()
should be the name of the element that you specified in the process.php file and the name attribute in the form HTML. The code
below will display the submitted email address. You can use this code in both notification
email and the autoreply email.
<?php echo $form->getValue('email'); ?>
Display submitted form data formatted in HTML
The above code will return the raw value of the form element, which can sometimes be an array (for multi-checkbox elements for example). If you
use the method getValueHtml()
instead, it will guarantee that the value will be displayed properly in the HTML email.
This method takes two arguments, the first argument is the unique element name, the second argument (optional) is the string separator that will be used to join array types, this defaults to '<br />'
.
Use the code below to safely display a submitted value in the HTML email file.
<?php echo $form->getValueHtml('unique_element_name'); ?>
Note: just replace unique_element_name
with the name of the element you specified in process.php to get any submitted form value. The returned
data is filtered according to any filters you added in process.php.
Sending the form user an autoreply email
You may want to send the form user an email to let them know that their enquiry was sent successfully. To do this you will need
to open the file quform/process.php
and search for the term $config['autoreply'].
Set this variable to true
.
If you look on the lines below this, you'll see the code that sets the subject
of the autoreply as well as the names of the files that contain the content of the email.
The subject can contain placeholder variables, which is your form element unique name surrounded by %
signs. The submitted value of the form element with that name will be used in its place.
With the default settings the autoreply will contain the content found in the file below. You
can simply edit this file to change the content of the autoreply email. If you need to access
a submitted form value from inside the email, see the section above called "Accessing submitted form data from inside the emails".
quform/emails/autoreply.php
- HTML body the email
Different autoreply emails per form
If you want another form to have another autoreply, you should make a copy of autoreply.php
and name it something different then customise the content. Then in the process.php
file for your new form, use the new filename instead for the
variable $config['autoreplyBody']
. For example if you have named the autoreply file for your second form autoreply-register.php
$config['autoreplyBody'] = '/emails/autoreply-register.php';
Customising the autoreply email
To customise the autoreply email you will need to edit the file that you specified to be used as the autoreply email as described in the above section. By default this fils is:
quform/emails/autoreply.php
- HTML body of the email
You can use HTML tags in this file such as <br />
for a new line.+
How to remove the IP address from the email
If you search in process.php for $config['extra'], you will find the line that adds the IP address to the notification email. To stop this, remove this line (or just comment it out).
Adding extra data to the notification email
If you search in process.php for $config['extra'], you will find the line that passes the submitter IP
address to the notification email. You can send any other data you wish by adding more entries to
this $config['extra']
array. The label will be the array key and the displayed value will be the
array value. For example to show the time and date the form was submitted, add this code:
$config['extra']['Date'] = date('g:ia jS F Y');
To show the page that the form was submitted from, you can use this code:
$config['extra']['Form URL'] = Quform::getReferer();
Sending emails via a SMTP server
To use a SMTP server to send the emails you will need to enter your SMTP server connection information in
process.php. In process.php
search for the term $config['smtp']. You will end up
at an array of key and value pairs fill out the corresponding empty quotes on the right hand side of the array
with your connection details. For example, to send mail via Gmail it may look something like this.
$config['smtp'] = array( 'host' => 'smtp.gmail.com', 'port' => 465, 'username' => 'YOUR_GMAIL_USERNAME', 'password' => 'YOUR_GMAIL_PASSWORD', 'encryption' => 'ssl' );
Saving form data to a MySQL database
Quform includes code to save form data to a MySQL database. To use this feature, open process.php
and search for the term
$config['database'] and change it to true
. Then search for the term MySQL and you should
end up above the block of code that does the saving to the database, you'll need to change a few settings here to get it working.
First of all, you should change the line that connects to MySQL with your correct host, username and password.
mysql_connect('localhost', 'username', 'password') or die(mysql_error());
Secondly, change the database name to match your database on the line below.
mysql_select_db('database') or die(mysql_error());
Thirdly, a few lines below you should change the table name to match your table name.
$query = "INSERT INTO table SET ";
Finally, inspect the query to see if there is anything you want to change. You can add new fields or remove fields to suit your needs. You can access any submitted form values, using the code below.
$form->getValue('unique_element_name');
The default data entered in to the database is escaped using mysql_real_escape_string()
so it is safe from MySQL Injection attacks.
Adding custom form processing code
You can run your own custom code on the form values when the form is submitted by adding code to process.php
. We have
set aside two areas for you to do this before and after all other form processing has taken place. In process.php
, search for these terms
- // Custom code section #1
- // Custom code section #2
You can add any code you like to either section. Below are examples of what you can do in each section. You have
access to the form instance $form
and you can iterate through the form elements using the method $form->getElements()
. You
can get specific element values using the code $form->getValue('unique_element_name');
.
Custom code section #1
In this section you can add further form validation before the rest of the process code is done. You can return from the process function, display an error to the form user and stop further processing. For example if you wanted to log a user into your website, you could use code similar to below.
$username = $form->getValue('username'); $password = $form->getValue('password'); if (!login($username, $password)) { $form->setError('The username or password is incorrect'); return false; }
NOTE: this is example code and will not actually work as a login system
Custom code section #2
In this section you can perform any further processing actions, for example saving the form data to your subscriber email list.
Using another character encoding
You should make sure the form is using the same character encoding as your website. By default the Quform works with UTF-8 encoding and will expect form data sent from your web page to be in this encoding. If you are using the form in another language and if you have strange characters in the email or similar issues this may be something to you need to check.
Using UTF-8 encoding (recommended)
Quform is already set up to use UTF-8 encoding, to set your web page to use UTF-8 encoding, insert the following meta tag just after the opening <head>
tag of the web page your form is on:
For HTML4 / XHTML1.0 websites
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
For HTML5 websites
<meta charset="UTF-8" />
Using another encoding such as ISO-8859-1
If your web page uses another charset and you want the Quform to use the same charset, you change the existing code that sets the charset inside common.php
(for example to use the ISO-8859-1 charset):
defined('QUFORM_CHARSET') || define('QUFORM_CHARSET', 'ISO-8859-1');
For a list of all valid character encodings, see the charset section of this page.
File uploads
You can add file upload form elements to your form and you can attach the uploaded files to the email that is sent out to you. You will need to do two things to get file uploads working:
- 1. Add your file upload HTML element to your form
- 2. Add code to
process.php
to make the PHP code aware of your file element
Each step is explained in more detail below:
1. Add your file upload HTML element to your form
Below is sample HTML for a file upload field with standard Quform wrappers:
<!-- Begin Upload element --> <div class="quform-element quform-element-file"> <div class="quform-spacer"> <label for="upload">Upload <span class="quform-required">*</span></label> <div class="quform-input"> <input class="upload-element" id="upload" type="file" name="upload" /> <p class="quform-description">All files allowed. Maximum size 10MB.</p> </div> </div> </div> <!-- End Upload element -->
NOTE: The PHP manual recommends that you add a hidden input before your file input with the maximum allowed file size in bytes, this way users do not have to wait for files to be uploaded before being told that they are too large. The code you need to add is below and should be placed before your file input element. The number is the maximum file size in bytes (1048576 bytes = 1MB) so if you wanted to allow a 10MB file set the value to 1048576 x 10 = 10485760.
<input type="hidden" name="MAX_FILE_SIZE" value="10485760" />
2. Add code to process.php
to make the PHP code aware of your file element
Now you need to make the PHP script aware of your new file upload field. The code you need to do that is shown below.
$upload = new Quform_Element_File('upload'); $form->addElement($upload);
See the troubleshooting section if you are having problems with the file uploads.
Attaching the file upload to the notification email
Any file uploads are automatically added to the email as attachments.
Preventing a file upload from attaching to the notification email
To prevent a file upload automatically attaching to the notification email, you can use the code below after creating your element in process.php
.
$upload->setAttach(false);
Making the upload required
To make the upload required use the following code:
$upload->getFileUploadValidator()->setRequired(true);
Setting allowed file extensions
You can set the allowed file extensions so that any other files will be rejected by the form. You should pass in an array of lowercase file extensions e.g.:
$upload->getFileUploadValidator()->setAllowedExtensions(array('gif', 'jpeg', 'jpg', 'png'));
Setting a maximum file size
You can also limit the upload by file size. The default upload limit is 10MB since many email providers do not support attachments larger than that. To set the maximum upload size, use this code:
$upload->getFileUploadValidator()->setMaximumFileSize(10485760);
The maximum file size is in bytes which is (Size in MB x 1048576)
NOTE: The file upload size can be limited by 4 things:
- Your hidden input MAX_FILE_SIZE as shown above
- The Quform max size setting
$upload->getFileUploadValidator()->setMaximumFileSize(10485760);
, you can set this to no limit by using$upload->getFileUploadValidator()->setMaximumFileSize(0);
- The PHP configuration setting post_max_size
- The PHP configuration setting upload_max_filesize
Chaining upload validator methods
You can chain the methods together to save yourself repeating code a lot. E.g.
$upload->getFileUploadValidator()->setRequired(true)->setAllowedExtensions(array('jpg'))->setMaximumFileSize(1024055);
Grouping multiple file uploads
If you have multiple upload fields you can group them under the same element using the multiple field syntax (square brackets) e.g. element_name[]
. This way you
do not need to create a Quform_Element_File object in the PHP code for each upload element and they can all share the same settings. For example you could have the following code to group 3 uploads:
<!-- Begin Grouped Upload element --> <div class="quform-element quform-element-file"> <div class="quform-spacer"> <label>Grouped file upload <span class="quform-required">*</span></label> <div class="quform-input"> <div class="quform-input-file"> <input type="file" class="upload-element" name="uploads[]" /> </div> <div class="quform-input-file"> <input type="file" class="upload-element" name="uploads[]" /> </div> <div class="quform-input-file"> <input type="file" class="upload-element" name="uploads[]" /> </div> <p class="quform-description">Allowed extensions .jpg, .jpeg, .png, .gif. Maximum size 1MB (each). Two uploads required.</p> </div> </div> </div> <!-- End Grouped Upload element -->
And in your process.php the code would look like:
$uploads = new Quform_Element_File('upload[]'); $form->addElement($uploads);
Require a specific number of uploads for a multiple element
If you used the grouped upload code above and you set the field to be required using $upload->getFileUploadValidator()->setRequired(true);
then all 3 uploads would be
required. If you wanted only one upload to be required from the group then you should add the code below:
$upload->getFileUploadValidator()->setRequired(true)->setRequiredCount(1);
Storing file uploads
To enable the storage of file uploads to the server you need to do 3 things.
- 1. Add the HTML for the file upload field to your form
- 2. Add the file element to
process.php
- 3. Enable and configure file uploads in
process.php
1. Add the HTML for the file upload field to your form
Here's the HTML for a file upload field called upload
, you should add this inside your form.
<!-- Begin Upload element --> <div class="quform-element quform-element-file"> <div class="quform-spacer"> <label for="upload">Upload <span class="quform-required">*</span></label> <div class="quform-input"> <input id="upload" type="file" name="upload" /> <p class="quform-description">All files allowed. Maximum size 10MB.</p> </div> </div> </div> <!-- End Upload element -->
2. Add the file element to process.php
Open process.php
and add the code to create the file element at the element configuration section.
$upload = new Quform_Element_File('upload'); $form->addElement($upload);
3. Enable and configure file uploads in process.php
In process.php
search for the term $config['saveUploads'] and set it to true
. Also
check the setting below $config['uploadPath']
, by default this will save the uploads into the quform/uploads/
folder,
you should make sure that this folder is writable by the web server user, this may require setting permissions 0777 on the folder.
More than one upload field
To add another upload field, simply repeat the steps above, you will need to change the unique name of the element to something other than upload and change the HTML and PHP code to match.
Changing the upload save path per element
You can have a different file upload path for each element. To do that use the code below after you have created your element
in process.php
.
$upload->setSavePath(QUFORM_ROOT . '/folder');
The above will set the save path to the directory quform/folder/
. If you want the path to be outside the quform folder then
you should enter the path to the folder you want to save the files to. For example:
$upload->setSavePath('/home/user340349/web/public_html/files');
Preventing the file from being uploaded
By default, if saving to the server is enabled then all uploaded files will be saved to the server. If you want to disable a file upload element
from saving the uploaded files to the server, use the code after you have created the element in process.php
.
$upload->setSave(false);
Using reCAPTCHA
To use reCAPTCHA there are 3 things you need to do.
- 1. Get your reCAPTCHA keys
- 2. Put the code for the reCAPTCHA into your form HTML
- 3. Set up the element in
process.php
Each step is explained in more detail below.
1. Get your reCAPTCHA keys
To use reCAPTCHA you will need both a public and private key, you can get these from Google for free by clicking here.
2. Put the code for the reCAPTCHA into your for HTML
The reCAPTCHA will only work with a PHP page, so if your form is currently on an HTML page such as index.html then rename it to index.php
Next, you should copy and paste the following code into your form at the location you would like the reCAPTCHA to appear. Replace YOUR_PUBLIC_KEY with your reCAPTCHA public key obtained in Step 1.
<div class="quform-element quform-element-recaptcha"> <div class="quform-spacer"> <div class="quform-input"> <?php include_once 'quform/lib/recaptchalib.php'; echo recaptcha_get_html('YOUR_PUBLIC_KEY'); ?> </div> </div> </div>
3. Set up the element in process.php
Open process.php
and paste the following code into the file, where you paste it
is not really important just find a blank line around where the other elements are configured.
$recaptcha = new Quform_Element('recaptcha_response_field', 'reCAPTCHA'); $recaptcha->addValidator('required'); $recaptcha->addValidator('recaptcha', array('privateKey' => 'YOUR_PRIVATE_KEY')); $recaptcha->setIsHidden(true); $form->addElement($recaptcha);
Replace YOUR_PRIVATE_KEY with your reCAPTCHA private key obtained in Step 1.
Changing the reCAPTCHA theme
There are 4 reCAPTCHA themes available, to see what they look like click here. To use
another theme copy the code below and paste it into the <head>
of your web page.
<script type="text/javascript"> var RecaptchaOptions = { theme : 'theme_name' }; </script>
Replace theme_name with one of the following:
- red
- white
- blackglass
- clean
Using a custom CAPTCHA
I will explain briefly how to make a CAPTCHA field that will generate a random image, store the result using PHP sessions, then use an Quform validator to check if the entered result is correct. There are three things you will need to do:
- 1. Create a PHP file that will generate the CAPTCHA image and store the expected result
- 2. Change the existing CAPTCHA image to link to the PHP file above
- 3. Customise the supplied CAPTCHA validator to check the submitted result against the expected result
- 4. Add the CAPTCHA validator to the form element
Each step is explained in more detail below.
1. Create a PHP file that will generate the CAPTCHA image and store the expected result
Create a random CAPTCHA image using PHP and the GD image extension. There are many examples
on the internet on how to do this, for example, Step 1 of this page.
Make sure to save the expected result in $_SESSION['captcha']
. Save the file as captcha.php
2. Change the existing CAPTCHA image to link to the PHP file above
Change the img src=""
attribute of the existing CAPTCHA to point to your new captcha.php file.
3. Customise the supplied CAPTCHA validator to check the submitted result against the expected result
Open the file lib/Quform/Validator/Captcha.php an make sure the code looks to suit your requirements, e.g.
your security code expected result is stored in $_SESSION['captcha']
. You should also add
<?php session_start(); ?>
to the web page with your form on it, and also at the top of
quform/process.php
.
4. Add the CAPTCHA validator to the form element
In quform/process.php
add the 'captcha' validator to your CAPTCHA element.
$captcha->addValidator('captcha');
The instructions are probably too difficult for a novice web designer to do, so if that's you then you should either stick with the basic CAPTCHA field or hire a professional web developer to set it up for you.
Custom JavaScript success callbacks
There are 3 success callbacks available for you to alter the behaviour when the form is successfully submitted.
- successStart
- success
- successEnd
successStart
successStart is called when the form has been successfully submitted and before any other
success code is run. If you want to run any code before anything else this is the place to do it.
You can add this on line 2 of js/scripts.js
$('form.quform').Quform({ successStart: function (response) { // Your custom JavaScript } });
success
If you specify a success
callback this will override the default form success functionality of
resetting the form and fading in the success message. If you do specify a custom success function
the successEnd function hook will no longer be available, unless you include it in your own code of course. You can add this on line 2 of js/scripts.js
$('form.quform').Quform({ success: function (response) { // Your custom JavaScript } });
successEnd
The successEnd function is called after the default success functionality of fading out
the form and fading in the success message has finished animating. You can add this on line 2 of js/scripts.js
$('form.quform').Quform({ successEnd: function (response) { // Your custom JavaScript } });
Data accessible from inside your custom functions
- this - The Quform object instance
- this.$form - The jQuery object representing your form
- this.options - The options object passed to the Quform instance
- this.$container - The jQuery object representing the form element container
- this.$loading - The jQuery object representing the loading text/gif
- this.$submitButton - The jQuery object representing the submit button
- response - The Ajax response from the server
Custom JavaScript error callbacks
There are 3 error callbacks available for you to alter the behaviour when the form contains errors. These callbacks are called when the form contains errors i.e. elements have not passed validation.
- errorStart
- error
- errorEnd
errorStart
errorStart is called before any other error processing code is run. If you want to run any
code before anything else this is the place to do it. You can add this on line 2 of js/scripts.js
$('form.quform').Quform({ errorStart: function (response) { // Your custom JavaScript } });
For example to show a message after the submit button if the form has errors, use the following code in
quform/js/scripts.js
and change the code on line 2:
$('form.quform').Quform({ errorStart: function(response) { $('.form-error', this.$form).remove(); // Remove any previous error messages this.$container.after('<div class="form-error">There was an error in the form</div>'); } });
error
If you specify an error
callback this will override the default form error functionality of
appending the errors beneath the input for each element, so you will be able to customise how
the errors are displayed. If you do specify a custom error function
the errorEnd function hook will no longer be available, unless you include it in your own code of course. You can add this on line 2 of js/scripts.js
$('form.quform').Quform({ error: function (response) { // Your custom JavaScript } });
errorEnd
The errorEnd function is called after the default error functionality of displaying
the errors underneath the input elements has completed. You can add this on line 2 of js/scripts.js
$('form.quform').Quform({ errorEnd: function (response) { // Your custom JavaScript } });
Data accessible from inside your custom functions
- this - The Quform object instance
- this.$form - The jQuery object representing your form
- this.options - The options object passed to the Quform instance
- this.$container - The jQuery object representing the form element container
- this.$loading - The jQuery object representing the loading text/gif
- this.$submitButton - The jQuery object representing the submit button
- response - The Ajax response from the server
Quform JavaScript options
There are a number of options you can use to customize the Quform JavaScript. See the table below for all options and below the table for examples.
Option | Default | Notes |
---|---|---|
container | .quform-elements | The jQuery selector of the element container |
loading | .quform-loading-wrap .loading | The jQuery selector of the loading image/text |
submitButton | .quform-submit-button | The jQuery selector of the submit button |
reset | true | Reset the form to it's default state after successful submit |
hideFormSpeed | false | The jQuery animate speed that the form will fade out, if false the form will not fade out |
successFadeInSpeed | slow | The jQuery animate speed that the success message will fade in |
successFadeOutSpeed | slow | The jQuery animate speed that the success message will fade out |
successTimeout | 8000 | The time to display the success message in milliseconds. 1000 = 1 second. Set to 0 to never hide the message. |
scrolling | true | Scroll automatically to errors and messages |
scrollSpeed | 400 | The jQuery animate speed of the scrolling animation |
scrollThreshold | 20 | If the scroll target is this number of pixels or less inside the viewport, scrolling to it will still happen |
scrollOffset | -50 | How far above the target to scroll too |
errorTitle | There was a problem | The title of the error message if a serious error occurs |
errorResponseEmpty | An error occurred and the response from the server was empty. | The error message text if there is a server side problem |
errorAjax | An Ajax error occurred. | The error message if there is an Ajax problem |
errorPosition | above | The position of global form error message, 'above' or 'below' the form |
Filters
You can use Filters to strip data from the user submitted value such as HTML tags (which may be harmful) and useless white space and the start and end of the value. There are filters included with the form that do just that and more, although you can add your own too - see Adding a new filter below.
Included filters
- trim - strips whitespace and other characters from the start and end
- stripTags - strips all HTML tags
- digits - filters everything except digits
- alphaNumeric - filters everything except alphanumeric characters
- alpha - filters everything except alphabet characters
- regex - filters everything matching the given regular expression
So if you assign a Filter to an Element then the value that will appear in the email will be the filtered value. The values are filtered before they are validated too.
As an extreme example, a value like ' <script></script> ' with the stripTags and trim filter and the required validator will actually fail validation, because once the tags are stripped and the white space is trimmed the value is empty so it fails the required validator.
Adding a filter to a form element
To add a filter to an element, you will need to open process.php
and find the
code that creates the element you want to add the filter to. It may already have a line below it
that is calling addFilters()
, in that case just add the name of the filter you want to add at the
end of the array that is passed in. If the element had the following code.
$element->addFilter('trim');
You can just add another line below that adds the new filter. For example if you wanted to add the alphaNumeric filter also you can make the code:
$element->addFilter('trim'); $element->addFilter('alphaNumeric');
You could also use the following code
$element->addFilters(array('trim', 'alphaNumeric'));
For the geeks out there you can also instantiate the filter directly then add it to the element. Which may help with your own custom filters if you need to make any that you need to pass options to, for example.
$trimFilter = new Quform_Filter_Trim(); $element->addFilter($trimFilter);
Removing a filter from a form element
To remove a filter from a form element, find the code that creates and configures the element
in process.php
. Look for the line that is adding the filters e.g.
$element->addFilters(array('stripTags', 'trim'));
To remove only the stripTags filter:
$element->addFilters(array('trim'));
To remove both the filters delete or comment out the entire line.
Filter options (Advanced)
You can pass in options to filters to change the way they operate. You can pass in options using the addFilter()
method on
an element. Pass in an array as the second argument containing the array keys that are options of the filter. See the documentation below on
each filter or the code for the filters in the quform/lib/Quform/Filter/
folder to see the options you can use.
$element->addFilter('stripTags', array('allowableTags' => array('<br>', '<p>')));
You can also pass in options at instantiation and then add the filter object to your element.
$stripTagsFilter = new Quform_Filter_StripTags(array('allowableTags' => array('<br>'))); $element->addFilter($stripTagsFilter);
Trim filter
No options.
$element->addFilter('trim');
StripTags filter
Options
- allowableTags - an array of strings of the tags you do not want to be stripped
$element->addFilter('stripTags', array('allowableTags' => array('<br>', '<p>')));
Digits filter
Options
- allowWhiteSpace - boolean true or false, if true white space is not filtered, default false
$element->addFilter('digits', array('allowWhiteSpace' => true));
Alphanumeric filter
Options
- allowWhiteSpace - boolean true or false, if true white space is not filtered, default false
$element->addFilter('alphaNumeric', array('allowWhiteSpace' => true));
Alpha filter
Options
- allowWhiteSpace - boolean true or false, if true white space is not filtered, default false
$element->addFilter('alpha', array('allowWhiteSpace' => true));
Regex filter
Options
- pattern - string regex pattern passed as-is to preg_replace
$element->addFilter('regex', array('pattern' => '/\d+/'));
Validators
Validators check the user submitted values against a set of rules to see if they are valid. If the value is valid nothing happens, the next validator and form element will be checked for validity. If the value is not valid, the error messages generated by the Validator will be returned back to the user and the form will not be submitted. If the value submitted to every form element passes that form element's validators then the entire form is valid and it is submitted.
There are 12 validators included with the form, although you are free to add as many as you want - see Adding a new validator below.
- required - The value is required and it cannot be empty
- email - The value must be a valid email address
- captcha - The value must match the letters set by a captcha script
- stringLength - The length of the value must be between the set min and max
- lessThan - The value must be less than the set max (numerically)
- greaterThan - The value must be greater than the set min (numerically)
- digits - The value must be only digits
- alphaNumeric - The value must have only alphanumeric characters
- alpha - The value must have only alphabet characters
- fileUpload - Validates the file upload against set options
- identical - The value must be identical to the set token
- recaptcha - The value is validated by the reCAPTCHA service
- inArray - The value must be in the given array
- wordCount - The word count of the value must be between the set min and max
- regex - The value is validated by the given regular expression pattern
Adding a validator to a form element
To add a validator to an element, you will need to open process.php
and find the
code that creates the element you want to add the validator to. It may already have a line below it
that is calling addValidators()
, in that case just add the name of the validator you want to add at the
end of the array that is passed in. If the element had the following code.
$element->addValidator('required');
You can just add another line below that adds the new validator. For example if you wanted to add the digits validator also you can make the code:
$element->addValidator('required'); $element->addValidator('digits');
You could also use the following code
$element->addValidators(array('required', 'digits'));
For the geeks out there you can also instantiate the validator directly then add it to the element. Which may help with your own custom validators if you need to make any that you need to pass options to, for example.
$emailValidator = new Quform_Validator_Email(); $element->addValidator($emailValidator);
Removing a validator from a form element
To remove a validator from an element, you will need to open process.php
and find the
code that creates and configures the element you want to remove the validator from. Look for the
line that has code similar to the code below.
$element->addValidators(array('required', 'email'));
To remove only the email validator make it like so.
$element->addValidators(array('required'));
To remove all validators, delete or comment out the entire line.
Changing the error message generated by a validator
Changing a single error message without affecting any other elements or forms
The preferred way to do this is to pass an options array to the validator when adding it to an element, with the 'messages' key and this contains another array with the key of the error message and your new error message text. You can use this method to set different error messages for different elements that have the same validator. For example, to change the email address validator message.
$element->addValidator('email', array( 'messages' => array('invalid' => 'The email address is invalid') ));
The message keys and available placeholders are shown in the Validator options (Advanced) section below.
Changing the default error messages (affects other forms and elements)
In some situations (such as translating) it may be faster to just change the default error messages.
You will need to go to quform/lib/Quform/Validator/
and find the
file for the Validator you want to change. Once you've found it, open the file and look
inside and near the top of the file you should see a PHP array that sets the default error messages e.g.
protected $_messageTemplates = array( 'invalid' => 'Invalid email address' );
This is the messages that is returned to the form when validation fails, change it to whatever you like. Note: some validators have more than one message for different errors.
Validator options (Advanced)
You can pass in options to validators to change the way they operate. You can pass in options using the addValidator()
method on
an element. Pass in an array as the second argument containing the array keys that are options of the validator. See the documentation below on
each validator or the code for the validators in the files in the quform/lib/Quform/Validator/
folder to see the options you can use.
$element->addValidator('stringLength', array('min' => 5, 'max' => 10));
You can also pass in options at instantiation and then add the validator object to your element.
$stringLengthValidator = new Quform_Validator_StringLength(array('min' => 5, 'max' => 10)); $element->addValidator($stringLengthValidator);
Email validator
Options
None
Error messages
Key | Default | Placeholders |
---|---|---|
invalid | Invalid email address | %s = the submitted value |
Examples
$element->addValidator('email');
$element->addValidator('email', array( 'messages' => array('invalid' => 'The email address %s is invalid') ));
Required validator
Options
None
Error messages
Key | Default | Placeholders |
---|---|---|
required | This field is required |
Examples
$element->addValidator('required');
$element->addValidator('required', array( 'messages' => array('required' => 'Please fill out this field') ));
EmailConfirm validator
Options
- key - (string) the unique name of the other email element, default 'email'
Error messages
Key | Default | Placeholders |
---|---|---|
not_match | The email addresses do not match | %s = the submitted value |
Examples
$element->addValidator('emailConfirm');
$element->addValidator('emailConfirm', array( 'messages' => array('not_match' => 'The email addresses are not the same') ));
Captcha validator
Options
None
Error messages
Key | Default | Placeholders |
---|---|---|
not_match | The value does not match |
Examples
$element->addValidator('captcha');
$element->addValidator('captcha', array( 'messages' => array('not_match' => 'Incorrect captcha solution') ));
StringLength validator
Options
- min - (integer) the minumum length of the string
- max - (integer) the maximum length of the string, if not specified there is no maximum
Error messages
Key | Default | Placeholders |
---|---|---|
invalid | Value is an invalid type, it must be a string | |
too_short | Value must be at least %1$d characters long | %1$d = the set minimum %2$s = the submitted value %3$d = the length of the submitted value |
too_long | Value must be no longer than %1$d characters | %1$d = the set maximum %2$s = the submitted value %3$d = the length of the submitted value |
Examples
$element->addValidator('stringLength', array('min' => 5, 'max' => 10));
$element->addValidator('stringLength', array( 'messages' => array( 'invalid' => 'Sorry, the value must be a string', 'too_short' => 'Your submitted value %2$s must be at least %1$d characters long, but it was %3$d', 'too_long' => 'Your submitted value %2$s must be no longer than %1$d characters, but it was %3$d' ) ));
LessThan validator
Options
- max - (integer|string) the value must be less than max (numerically)
Error messages
Key | Default | Placeholders |
---|---|---|
not_less_than | %1$s is not less than %2$d | %1$s = the submitted value %2$d = the set maximum |
Examples
$element->addValidator('lessThan', array('max' => 10));
$element->addValidator('lessThan', array( 'messages' => array( 'not_less_than' => '%1$s is not less than %2$d, please change the value' ) ));
GreaterThan validator
Options
- min - (integer|string) the value must be greater than min (numerically)
Error messages
Key | Default | Placeholders |
---|---|---|
not_greater_than | %1$s is not greater than %2$d | %1$s = the submitted value %2$d = the set minimum |
Examples
$element->addValidator('greaterThan', array('min' => 3));
$element->addValidator('greaterThan', array( 'messages' => array( 'not_greater_than' => '%1$s is not greater than %2$d, please change the value' ) ));
Digits validator
Options
- allowWhiteSpace - boolean true or false, if true white space is allowed, default false
Error messages
Key | Default | Placeholders |
---|---|---|
invalid | Only digits are allowed | %s = the submitted value |
Examples
$element->addValidator('digits', array('allowWhiteSpace' => true));
$element->addValidator('digits', array( 'messages' => array( 'invalid' => '%s does not contain only digits' ) ));
AlphaNumeric validator
Options
- allowWhiteSpace - boolean true or false, if true white space is allowed, default false
Error messages
Key | Default | Placeholders |
---|---|---|
invalid | Only alphanumeric characters are allowed | %s = the submitted value |
Examples
$element->addValidator('alphaNumeric', array('allowWhiteSpace' => true));
$element->addValidator('alphaNumeric', array( 'messages' => array( 'invalid' => '%s does not contain only alphanumeric characters' ) ));
Alpha validator
Options
- allowWhiteSpace - boolean true or false, if true white space is allowed, default false
Error messages
Key | Default | Placeholders |
---|---|---|
invalid | Only alphabet characters are allowed | %s = the submitted value |
Examples
$element->addValidator('alpha', array('allowWhiteSpace' => true));
$element->addValidator('alpha', array( 'messages' => array( 'invalid' => '%s does not contain only alphabet characters' ) ));
FileUpload validator
The validator is automatically registered with your file upload elements, see the file uploads section above for options.
Error messages
Key | Default | Placeholders |
---|---|---|
x_required | At least %d files are required | %d = the number of required files |
one_required | At least 1 file is required | |
required | This field is required | |
all_required | All files are required | |
x_too_big | '%s' exceeds the maximum allowed file size | %s = the filename |
too_big | File exceeds the maximum allowed file size | |
x_only_partial | '%s' was only partially uploaded | %s = the filename |
only_partial | File was only partially uploaded | |
no_file | No file was uploaded | |
missing_temp_folder | Missing a temporary folder | |
failed_to_write | Failed to write file to disk | |
stopped_by_extension | File upload stopped by extension | |
x_bad_type | File type of '%s' is not allowed | %s = the filename |
bad_type | File type is not allowed | |
x_not_uploaded | File '%s' is not an uploaded file | %s = the filename |
not_uploaded | File is not an uploaded file | |
unknown | Unknown upload error |
Examples
$upload->getFileUploadValidator()->setMessageTemplates(array( 'required' => 'Please upload a file', 'unknown' => 'Upload failed, please try again' ));
Identical validator
Options
- token - (mixed) the token to compare the value against
Error messages
Key | Default | Placeholders |
---|---|---|
not_match | Value does not match | %1$s = the submitted value %2$s = the set token |
Examples
$element->addValidator('identical', array('token' => 'light'));
$element->addValidator('identical', array( 'messages' => array( 'not_match' => '%1$s does not match %2$s' ) ));
Date validator
Options
None
Error messages
Key | Default | Placeholders |
---|---|---|
invalid | This is not a valid date |
Examples
$element->addValidator('date', array( 'messages' => array( 'invalid' => 'Please enter a valid date' ) ));
Time validator
Options
None
Error messages
Key | Default | Placeholders |
---|---|---|
invalid | This is not a valid time |
Examples
$element->addValidator('time', array( 'messages' => array( 'invalid' => 'Please enter a valid time' ) ));
InArray validator
Options
- haystack - (array) the array of possible values
- strict - (boolean) whether to check data type as well as value, default true
Error messages
Key | Default | Placeholders |
---|---|---|
not_in_array | The given value is not valid |
Examples
$element->addValidator('inArray', array( 'haystack' => array( 'Value 1', 'Value 2', 'Value 3' ), 'messages' => array( 'not_in_array' => 'This value is not allowed' ) ));
WordCount validator
Options
- min - (integer) the minumum number of words
- max - (integer) the maximum number of words, if not specified there is no maximum
Error messages
Key | Default | Placeholders |
---|---|---|
invalid | Value is an invalid type, it must be a string | |
too_short | Value must contain at least %1$d words | %1$d = the set minimum %2$s = the given value %3$d = the number of words in the given value |
too_long | Value must contain no more than %1$d words | %1$d = the set maximum %2$s = the given value %3$d = the number of words in the given value |
Examples
$element->addValidator('wordCount', array( 'min' => 10, 'max' => 100 'messages' => array( 'too_short' => 'Please enter more than %1$d words', 'too_long' => 'Please enter no more than %1$d words, you entered %3$d words' ) ));
Regex validator
Options
- pattern - (string) the regex pattern
Error messages
Key | Default | Placeholders |
---|---|---|
invalid | Invalid type given. String, integer or float expected | |
not_match | The given value is not valid | %s = the given value |
Examples
$element->addValidator('regex', array( 'pattern' => '/\d+/', 'messages' => array( 'not_match' => 'The given value "%s" is not a valid number' ) ));
Adding a new filter (Advanced)
If you want to add a new filter you should first check out the files in the folder quform/lib/Quform/Filter/
.
You will find the code for existing filters which should give you an idea of how to make your
own. What you need to do is add a new class in that folder for your new filter, however there are a few things you should note.
- Your filter must have it's own class with a name that begins with Quform_Filter_
- The name of the file should be the part of the class name after Quform_Filter_ and end with .php
- Your filter class must implement Quform_Filter_Interface
- Your filter class must have a method called
filter()
that takes the given value and returns the filtered value
Naming your filter
Filters have a special naming system in order to add them to an element. If you notice two of the
existing filter classes called Quform_Filter_StripTags and Quform_Filter_Trim which are added to element using
the names stripTags and trim. The conversion between short name and
class name happens automatically. To convert from short name to class name, make the first letter
uppercase and add Quform_Filter_ to the beginning. To convert from class name to short name make the first letter
lowercase and remove Quform_Filter_ from the beginning. If you made a new filter with the class name Quform_Filter_MyNewFilter
you could add it to an element using:
$element->addFilters(array('myNewFilter'));
You can also add the filter to the element by passing in an instance of it:
$element->addFilter(new Quform_Filter_MyNewFilter());
Adding a new validator (Advanced)
Before adding a new validator you should take a look at the files in the folder quform/lib/Quform/Validator/
.
You will find the code for existing validators which should give you an idea of how to make your own.
What you need to do is add a new class in that folder for your new validator, however there are a few things you should note.
- Your validator must have it's own class with a name that begins with Quform_Validator_
- The name of the file should be the part of the class name after Quform_Validator_ and end with .php
- Your validator class must extend Quform_Validator_Abstract
- Your validator class must have a method called
isValid()
that takes the given value and returns true if the value is valid and false otherwise. - Inside the
isValid()
method you can add messages to display back to the user to tell them why the value failed validation by using the code$this->addMessage('Message to send to user');
. That message will appear under the form element by default.
Naming your validator
Validators have a special naming system in order to add them to an element. If you notice two of the
existing validator classes called Quform_Validator_Required and Quform_Validator_Email which are added to element using
the names required and email. The conversion between short name and
class name happens automatically. To convert from short name to class name, make the first letter
uppercase and add Quform_Validator_ to the beginning. To convert from class name to short name make the first letter
lowercase and remove Quform_Validator_ from the beginning. If you made a new validator with the class name Quform_Validator_MyNewValidator
you could add it to an element using:
$element->addValidators(array('myNewValidator'));
You can also add the validator to the element by passing in an instance of it:
$element->addValidator(new Quform_Validator_MyNewValidator());
Working with forms with deep nested arrays (Advanced)
If you have set up your form elements such that they are using deep nested array structure in their names as shown below.
<input type="text" name="customer_info[delivery_details][postcode]" />
You will need to call the following code during form element configuration:
$element->setIsArray(true);
This will tell the form to expect an array for the value submitted and the element will not work properly without it. NOTE: Single level arrays such as multiple value elements:
<input type="checkbox" name="toppings[]" />
DO NOT need the setIsArray(true);
code. One level deeper than that and things will not work (the value will not be passed correctly to the form
element so it may appear blank in the email) and you WILL NEED to use setIsArray(true);
.
TroubleshootingTop
You do not receive the email
This is usually caused by one of the following reasons:
- Your host is blocking the email being sent
- Your server is not configured to send email via the PHP mail() function
See below for solutions.
Your host is blocking the email being sent
Some hosts may block emails under certain circumstances, the most common reason is that the "From" address of the email is not set
to an email address that is associated with your hosting account. You can try changing the $config['from']
setting in process.php
so that it's set to an address that is associated with your hosting account. If this still does not work, you can set the form up
to send via a SMTP server. See the section above called "Sending emails via a SMTP server".
Your server is not configured to send email via the PHP mail() function
You should contact your hosting company and ask them to set this up on your server. If this is not a possibility, you can set the form up to send via a SMTP server. See the section above called "Sending emails via a SMTP server".
Test email sending on your server
Quform uses PHP's mail()
function (via the PHPMailer library) to send the email by default. Some web hosts may
not allow you to use this function or require that you set certain headers. So we need to find out if you can send a simple email using your web server.
We have created a test script so that you can check to see if you can do that. The script is located quform/mail-check.php
, to set up
the script:
- 1. Open the file and read the introductory comment
- 2. Enter your email address on line 27
- 3. Upload the file to your web server
- 4. Visit the page in your web browser
If the script indicates there is a problem with the mail()
function and your hosting company
then you can try and set up the form to send the email via a SMTP server instead, such as your
ISP's server. See the section called Sending emails via a SMTP server in the Advanced form customisation section above.
Finding out what you need to do to use mail() with your web host
Search Google for "[your hosting company] php mail", usually there are forum posts by other people who are having trouble with the host and mail() and there is usually a solution in the forum. For example some hosts require that the "From" address is an email address from your domain that is hosted with them. See the installation guide for how to set the "From" address.
Form does not submit
This could happen for a lot of reasons. Look for JavaScript errors in the status bar of your web browser, if there is an error with another script it may also break the contact form.
We recommend using the Firebug extension for debugging if you do not already. If you enable the Net tab you will be able to see the Ajax requests being sent and received by the form and this can help to debug any problems you have in the PHP code because it isn't obvious when working with an Ajax application.
A good way to check for errors is to disable JavaScript in your browser and submit the form, any errors that are in your PHP code will be sent to the browser instead of silently back to the JavaScript so this might help you find some problems.
Submitting the form takes me to another page
This most likely means there is a JavaScript error on the page and the form is reverting to submitting in non-JavaScript mode. Once you find and fix the error the form should submit in Ajax mode. It could also mean that the Quform JavaScipt links in the head of the page are missing or loaded incorrectly.
File upload troubleshooting
Email does not arrive
If your email doesn't arrive, try it again without the file upload field. If it still doesn't arrive then try the suggestions in the "You do not recieve email" section above. If the email only doesn't arrive when you have a file upload field, you might be exceeding email size limits of your web host or one of the relays, so try a really small attachment. If it still does not work, contact us and we'll try and help you fix it.
Email does not have attachments
Double check you have added the file upload element to the form in process.php
, as described in the file uploads section above.
Maximum file size problems
By default PHP only allows an upload_max_filesize
of 2MB. You will need to change this setting
in php.ini to your value, if you don't have access to change php.ini check with your web host
about how to change PHP settings. Many hosts will allow you to make changes to these values. The other
value you will need to check is post_max_size
, which is needs to be larger than your
upload_max_filesize
value.
Form returns this field is required for all fields
You may be exceeding limit the PHP ini directive post_max_size
which apparently
sets $_POST and $_FILES to empty arrays, thus your form will say that these fields are required. So
increase the limit.
Conflicts with other JavaScript libraries (prototype or Mootools etc)
If your web page uses another JavaScript library such as prototype or Mootools etc your form might not submit so you may need to
set jQuery into noConflict mode for the form to still work correctly. To do this, open js/scripts.js
and on
line 1 add this code before anything else:
jQuery.noConflict();
Fatal error: Uncaught exception 'phpmailerException' with message 'Could not instantiate mail function.'
This error is caused by one of the following reasons:
- Your host is blocking the email being sent
- Your server is not configured to send email via the PHP mail() function
See below for solutions.
Your host is blocking the email being sent
Some hosts may block emails under certain circumstances, the most common reason is that the "From" address of the email is not set
to an email address that is associated with your hosting account. You can try changing the $config['from']
setting in process.php
so that it's set to an address that is associated with your hosting account. If this still does not work, you can set the form up
to send via a SMTP server. See the section above called "Sending emails via a SMTP server".
Your server is not configured to send email via the PHP mail() function
You should contact your hosting company and ask them to set this up on your server. If this is not a possibility, you can set the form up to send via a SMTP server. See the section above called "Sending emails via a SMTP server".
Fatal error: Uncaught exception 'phpmailerException' with message 'Invalid address: '
You are recieveing this error because you have not specified at least one recipient for the notification email. To fix this, open process.php
and enter an email address for the $config['recipients']
setting. For example:
$config['recipients'] = 'me@example.com';
The emails are shown to be from "Root User <root@localhost>"
You have not specified a "From" address for the email. The steps to fix this are different for the notification email and the autoreply email, see the revelant sections below.
Notification email
Open process.php
and enter an email address for the $config['from']
setting. For example:
$config['from'] = 'company@example.com';
Autoreply email
Open process.php
and enter an email address for the $config['autoreplyFrom']
setting. For example:
$config['autoreplyFrom'] = 'company@example.com';
Non-English characters are shown as ?
Quform supports most non-English languages. If you have problems with characters not displaying correctly, you may have inadvertantly changed the character encoding of the index.html file or the file containing your form is not saved in UTF-8 encoding.
To save the file in UTF-8 encoding the method varies for different text editors, Google [your text editor] save as utf-8 for instructions.
Also make sure you have a charset meta tag set to UTF-8 in the head of the page, see the section above Using another character encoding for examples.
There was a problem: An error occurred and the response from the server was empty.
There is something wrong but error reporting is turned off on your server and our script was not able to enable error reporting. You will need to enable error reporting on your server, or if your server is set up to log PHP errors to a file, check the error log file (if you don't know where it is, ask your host).
Enable error reporting on your server
In your php.ini file modify the display_errors
directive so that its On. If you don't know how to do this, ask your host.
display_errors = On
Debug mode
By default debug mode is enabled, this means that Quform will try to show PHP errors and exceptions inside your form, otherwise they would be silently hidden in an Ajax request.
Disable debug mode
To disable debug mode change the code at the top of process.php to define('QUFORM_DEBUG', false);
.
Enable debug mode
To enable debug mode change the code at the top of process.php to define('QUFORM_DEBUG', true);
.
Errors are still not showing
You should disable JavaScript (or comment out line 2 of js/scripts.js) and any PHP errors will be shown when submitting the form.
Errors are STILL not showing
In this case, you may need to check your PHP or Apache error logs.
Further supportTop
For additional help, please visit our support website and support forums. You can also contact us using the form on our CodeCanyon profile page. You must be logged in to CodeCanyon to see the form.