Greyhead.net

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 …

1. 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.
2. 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.



3. To complete the form add the Button element, then save your form, publish it, and view it in your browser.
4. 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.