Greyhead.net

It's not very difficult to add Ajax functionality to ChronoForms, but it's not the easiest task in the world either.

We'll walk through a fairly simple example here which will provide you with the basic experience to build more complex applications. You will need some knowledge of JavaScript to follow through this recipe.

Normally, the only communication between the ChronoForms client (the user in their browser) and the server (the website host) is when a page is loaded or a form is submitted. Form HTML is sent to the client and a $_POST array of results is returned. Ajax is a technique, or a group of techniques, that enables communication while the user is browsing the page without them having to submit the form.

As usual, at the browser end the Ajax communication is driven by JavaScript and at the server end we'll be responding using PHP. Put simply, the browser asks a question, the server replies, then the browser shows the reply to the user.

For the browser JavaScript and the server PHP to communicate, there needs to be an agreed set of rules about how the information will be packaged. We'll be using the JSON (www.json.org) format.

The task we will work on will use a newsletter form. We'll check to see if the user's e-mail is already listed in our user database. This is slightly artificial but the same code can easily be adapted to work with the other database tables and use more complex checks.

Getting ready

We'll need a form with an e-mail text input. The input id needs to be email for the following code to work:

<div class="form_item">
  <div class="form_element cf_textbox">
    <label class="cf_label"
      style="width: 150px;">Email</label>
    <input class="cf_inputbox" maxlength="150" size="30"
      title="" id="email" name="email" type="text" />
  </div>
  <div class="cfclear">&nbsp;</div>
</div>

The form we use will also have a name text input and a submit button, but they are to make it look like a real form and aren't used in the Ajax coding.

How to do it . . .

We'll follow the action and start with the user action in the browser. We need to start our check when the user makes an entry in the e-mail input. So, we'll link our JavaScript to the blur event in that input. Here's the core of the code that goes in the Form JavaScript box:

/ set the url to send the request to
var url = 'index.php?option=com_chronocontact
  &chronoformname=form_name&task=extra&format=raw';
// define 'email'
var email = $('email');
// set the Ajax call to run
// when the email field loses focus
email.addEvent('blur', function() {
  // Send the JSON request
  var jSonRequest = new Json.Remote(url, {
    . . .
  }).send({'email': email.value});
});

Note that the long line starting with var url = . . . &format=raw'; is all one line and should not have any breaks in it. You also need to replace 'form_name' with the name of your form in this URL.

There really isn't too much to this. We are using the MooTools JSON functions and they make sending the code very simple.

The next step is to look at what happens back on the server.

The URL we used in the JavaScript includes the task=extra parameter. When ChronoForms sees this, it will ignore the normal Form Code and instead run the code from the Extra Code boxes at the bottom of the Form Code tab.

By default, ChronoForms will execute the code from Extra code 1. If you need to access one of the other boxes, then use for example, task=extra&extraid=3 to run the code from Extra Code box 3.

Now, we are working back on the server. So, we need to use PHP to unpack the Ajax message, check the database, and send a message back:

<?php
// clean up the JSON message
$json = stripslashes($_POST['json']);
$json = json_decode($json);
$email = strtolower(trim($json->email));
// check that the email field isn't empty
$response = false;
if ( $email ) {
  // Check the database
  $db =& JFactory::getDBO();
  $query = "
    SELECT COUNT(*)
      FROM `#__users`
      WHERE LOWER(`email`) = ".$db->quote($email).";
  ";
  $db->setQuery($query);
  $response = (bool) !$db->loadResult();
}
$response = array('email_ok' => $response );
//send the reply
echo json_encode($response);
// stop the from running
$MyForm->stopRunning = true;
die;
?>

This code has three main parts:

1. To start with, we "unwrap" the JSON message.
2. Then, we check if it isn't empty and run the database query.
3. Lastly, we package up the reply and tidy up at the end to stop any more form processing from this request.

The result we send will be array('email_ok' => $response ) where $response will be either true or false. This is probably the simplest JSON message possible, but is enough for our purpose.

Note that here, true means that this e-mail is not listed and is OK to use.

The third step is to go back to the form JavaScript and decide how we are going to respond to the JSON reply. Again, we'll keep it simple and just change the background color of the box – red if the e-mail is already in use (or isn't a valid e-mail) or green if the entry isn't in use and is OK to submit.

Here's the code snippet to do this using the onComplete parameter of the MooTools JSON function:

onComplete: function(r) {
  // check the result and set the background color
  if ( r.email_ok ) {
    email.setStyle('background-color', 'green');
  } else {
    email.setStyle('background-color', 'red');
  }
}

Instead of (or as well as) changing the background color, we could make other CSS changes, display a message, show a pop-up alert, or almost anything else.

Lastly let's put the two parts of the client-side JavaScript together with a little more code to make it run smoothly and to check that there is a valid e-mail before sending the JSON request.

window.addEvent('domready', function() {
  // set the url to send the request to
  var url = 'index.php?option=com_chronocontact
    &chronoformname=form_name&task=extra&format=raw';
  var email = $('email');
  email.addEvent('blur', function() {
    // clear any background color from the input
    email.setStyle('background-color', 'white');
    // check that the email address is valid
    regex = /^([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i;
    var value = email.value.trim();
    if ( value.length > 6 && regex.test(value) ) {
      // if all is well send the JSON request
      var jSonRequest = new Json.Remote(url, {
        onComplete: function(r) {
          // check the result and set the background color
          if ( r.email_ok ) {
            email.setStyle('background-color', 'green');
          } else {
            email.setStyle('background-color', 'red');
          }
        }
      }).send({'email': email.value});
    } else {
      // if this isn't a valid email set background color red
      email.setStyle('background-color', 'red');
    }
  });
});

Note that the long line starting with var url = . . . &format=raw'; is all one line and should not have any breaks in it. You also need to replace form_name with the name of your form in this URL.

Make sure both the code blocks are in place in the Form JavaScript box and in the Extra Code 1 box, save, and publish your form. Then, test it to make sure that the code is working OK. The Ajax may take a second or two to respond but once you move out of the e-mail, input by tabbing on to another input or clicking somewhere else; the background colour should go red or green.

How it works...

As far as the Ajax and JSON parts of this are concerned, all we can say here is that it works. You'll need to dig into the MooTools, Ajax, or JSON documents to find out more.

From the point of view of ChronoForms, the "clever" bit is the ability to interpret the URL that the Ajax message uses. We ignored most of it at the time but the JavaScript included this long URL (with the query string broken up into separate parameters):

index.php
?option=com_chronocontact
&chronoformname=form_name
&task=extra
&format=raw

The option parameter is the standard Joomla! way to identify which extension to pass the URL to.

The chronoformname parameter tells ChronoForms which form to pass the URL to.

The task=extra parameter tells ChronoForms that this URL is a little out of the ordinary (you may have noticed that forms usually have &task=send in the onSubmit URL). When ChronoForms sees this, it will pass the URL to the Extra Code box for processing and bypass the usual OnSubmit processing.

Lastly, the format=raw parameter tells Joomla! to show the resulting code without any extra formatting and without adding the template code. This means that all that is sent back is just the JSON message. Without it we'd have to dig the message out from loads of surrounding HTML we don't need.

---

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.