(For more resources on ChronoForms, see here.)
Introduction
We have so far mostly worked with fairly standard forms where the user is shown some inputs, enters some data, and the results are e-mailed and/or saved to a database table. Many forms are just like this, and some have other features added. These features can be of many different kinds and the recipes in this article are correspondingly a mixture.
Some, like Adding a validated checkbox, change the way the form works. Others, like Signing up to a newsletter service change what happens after the form is submitted.
While you can use these recipes as they are presented, they are just as useful as suggestions for ways to use ChronoForms to solve a wide range of user interactions on your site.
Adding a validated checkbox
Checkboxes are less often used on forms than most of the other elements and they have some slightly unusual behavior that we need to manage. ChronoForms will do a little to help us, but not everything that we need.
In this recipe, we’ll look at one of the most common applications—a stand alone checkbox that the user is asked to click to ensure that they’ve accepted some terms and conditions. We want to make sure that the form is not submitted unless the box is checked.
Getting ready
We’ll just add one more element to our basic newsletter form. It’s probably going to be best to recreate a new version of the form using the Form Wizard to make sure that we have a clean starting point.
How to do it…
-
- In the Form Wizard, create a new form with two TextBox elements. In the Properties box, add the Labels “Name” and “Email” and the Field Names “name” and “email” respectively.
- Now drag in a CheckBox element.
You’ll see that ChronoForms inserts the element with three checkboxes and we only need one. In the Properties box remove the default values and type in “I agree”.
While you are there change the label to “Terms and Conditions”.
Lastly, we want to make sure that this box is checked so check the Validation | One Required checkbox and add “please confirm your agreement” in the Validation Message box. Apply the changes to the Properties.
- To complete the form add the Button element, then save your form, publish it, and view it in your browser.
- To test, click the Submit button without entering anything. You should find that the form does not submit and an error message is displayed.
How it works…
The only special thing to notice about this is that the validation we used was validate-one- required and not the more familiar required. Checkbox arrays, radio button groups, and select drop-downs will not work with the required option as they always have a value set, at least from the perspective of the JavaScript that is running the validation.
There’s more…
Validating the checkbox server-side
If the checkbox is really important to us, then we may want to confirm that it has been checked using the server-side validation box.
We want to check and, if our box isn’t checked, then create the error message. However, there is a little problem—an unchecked checkbox doesn’t return anything at all, there is just no entry in the form results array.
Joomla! has some functionality that will help us out though; the JRequest::getVar() function that we use to get the form results allows us to set a default value. If nothing is found in the form results, then the default value will be used instead.
So we can add this code block to the server-side validation box:
<?php
$agree = JRequest::getString(‘check0[]’, ’empty’, ‘post’);
if ( $agree == ’empty’ ) {
return ‘Please check the box to confirm your agreement’;
}
?>
Note: To test this, we need to remove the validate-one-required class from the input in the Form HTML.
Now when we submit the empty form, we see the ChronoForms error message.
Notice that the input name in the code snippet is check0[]. ChronoForms doesn’t give you the option of setting the name of a checkbox element in the Form Wizard | Properties box. It assigns a check0, check1, and so on value for you. (You can edit this in the Form Editor if you like.) And because checkboxes often come in arrays of several linked boxes with the same name, ChronoForms also adds the [] to create an array name. If this isn’t done then only the value of the last checked box will be returned.
Locking the Submit button until the box is checked
If we want to make the point about terms and conditions even more strongly then we can add some JavaScript to the form to disable the Submit button until the box is checked.
We need to make one change to the Form HTML to make this task a little easier. ChronoForms does not add ID attributes to the Submit button input; so open the form in the Form Editor, find the line near the end of the Form HTML and alter it to read:
<input value=”Submit” name=”submit” id=’submit’
type=”submit” />
Now add the following snippet into the Form JavaScript box:
// stop the code executing
// until the page is loaded in the browser
window.addEvent(‘load’, function() {
// function to enable and disable the submit button
function agree() {
if ( $(‘check00’).checked == true ) {
$(‘submit’).disabled = false;
} else {
$(‘submit’).disabled = true;
}
};
// disable the submit button on load
$(‘submit’).disabled = true;
//execute the function when the checkbox is clicked
$(‘check00’).addEvent(‘click’, agree);
});
Apply or save the form and view it in your browser.
Now as you tick or untick the checkbox, the submit button will be enabled and disabled.
This is a simple example of adding a custom script to a form to add a useful feature. If you are reasonably competent in JavaScript, you will find that there is quite a lot more that you can do.
There are different styles of laying out both JavaScript and PHP and sometimes fierce debates about where line breaks and spaces should go. We’ve adopted a style here that is hopefully fairly clear, reasonably compact, and more or less the same for both JavaScript and PHP. If it’s not the style you are accustomed to, then we’re sorry.
Adding an “other” box to a drop-down
Drop-downs are a valuable way of offering a list of choices to your user to select from. And sometimes it just isn’t possible to make the list complete, there’s always another option that someone will want to add. So we add an “other” option to the drop-down. But that tells us nothing, so we need to add an input to tell us what “other” means here.
Getting ready
We’ll just add one more element to our basic newsletter form. We haven’t used a drop-down before but it is very similar to the check-box element from the previous recipe.
How to do it…
-
- Use the Form Wizard to create a form with two TextBox elements, a DropDown element, and a Button element.
-
- The changes to make in the element are:
- Add “I heard from” in the Label
- Change the Field Name to “hearabout”
- Add some options to the Options box—”Google”, “Newspaper”, “Friend”, and “Other”
Leave the Add Choose Option box checked and leave Choose Option in the Choose Option Text box. Apply the Properties box.
- Make any other changes you need to the form elements; then save the form, publish it, and view it in your browser.
- The changes to make in the element are:
Notice that as well as the four options we added the Choose Option entry is at the top of the list. That comes from the checkbox and text field that we left with their default values.
It’s important to have a “null” option like this in a drop-down for two reasons. First, so that it is obvious to a user that no choice has been made. Otherwise it’s very easy for them to leave the first option showing and this value—Google in this case—will be returned by default. Second, so that we can validate select-one-required if necessary. The “null” option has no value set and so can be detected by validation script.
-
- Now we just need one more text box to collect details if Other is selected.
Open the form in the Wizard Edit; add one more TextBox element after the DropDown element. Give it the Label please add details and the name “other”.
Even though we set the name to “other”, ChronoForms will have left the input ID attribute as text_4 or something similar. Open the Form in the Form Editor and change the ID to “other” as well. The same is true of the drop-down. The ID there is select_2, change that to hearabout.
- Now we need a script snippet to enable and disable the “other” text box if the Other option is selected in the drop-down. Here’s the code to put in the Form JavaScript box:
window.addEvent(‘domready’, function() {
$(‘hearabout’).addEvent(‘change’, function() {
if ($(‘hearabout’).value == ‘Other’ ) {
$(‘other’).disabled = false;
} else {
$(‘other’).disabled = true;
}
});
$(‘other’).disabled = true;
});This is very similar to the code in the last recipe except that it’s been condensed a little more by merging the function directly into the addEvent().
- When you view the form you will see that the text box for please add details is grayed out and blocked until you select Other in the drop-down.
Make sure that you don’t make the please add details input required. It’s an easy mistake to make but it stops the form working correctly as you have to select Other in the drop-down to be able to submit it.
How it works
Once again, this is a little JavaScript that is checking for changes in one part of the form in order to alter the display of another part of the form.
There’s more…
Hiding the whole input
It looks a little untidy to have the disabled box showing on the form when it is not required. Let’s change the script a little to hide and unhide the input instead of disabling and enabling it.
To make this work we need a way of recognizing the input together with its label. We could deal with both separately, but let’s make our lives simpler. In the Form Editor, open the Form HTML box and look near the end for the other input block:
<div class=”form_item”>
<div class=”form_element cf_textbox”>
<label class=”cf_label”
style=”width: 150px;”>please add details</label>
<input class=”cf_inputbox” maxlength=”150″ size=”30″
title=”” id=”other” name=”other” type=”text” />
</div>
<div class=”cfclear”> </div>
</div>
That <div class=”form_element cf_textbox”> looks like it is just what we need so let’s add an ID attribute to make it visible to the JavaScript:
<div class=”form_element cf_textbox” id=”other_input”>
Now we’ll modify our script snippet to use this:
window.addEvent(‘domready’, function() {
$(‘hearabout’).addEvent(‘change’, function() {
if ($(‘hearabout’).value == ‘Other’ ) {
$(‘other_input’).setStyle(‘display’, ‘block’);
} else {
$(‘other_input’).setStyle(‘display’, ‘none’);
}
});
// initialise the display
if ($(‘hearabout’).value == ‘Other’ ) {
$(‘other_input’).setStyle(‘display’, ‘block’);
} else {
$(‘other_input’).setStyle(‘display’, ‘none’);
}
});
Apply or save the form and view it in your browser. Now the input is invisible see the following screenshot labeled 1 until you select Other from the drop-down see the following screenshot labeled 2.
The disadvantage of this approach is that the form can appear to “jump around” as extra fields appear. You can overcome this with a little thought, for example by leaving an empty space.
See also
- In some of the script here we are using shortcuts from the MooTools JavaScript framework. Version 1.1 of MooTools is installed with Joomla! 1.5 and is usually loaded by ChronoForms. You can find the documentation for MooTools v1.1 at http://docs111.mootools.net/
Version 1.1 is not the latest version of MooTools and many of the more recent MooTools script will not run with the earlier version. Joomla 1.6 is expected to use the latest release.
