Data validation, an important part of any application, is useful to ensure that your users enter data properly.
When you create forms, you will need to determine which validation strategy to use, client-side, server-side or maybe mixed. Client-side validation has advantages for the server, the user and the developer, but the problem is that anything running on the client end can never be trusted.
Speaking of server-side validation in CakePHP, its built-in validation mechanism provides a powerful, yet easy-to-use environment. However, when it comes to Ajax form submission, the reality is that it involves a lot of technologies. There are already a number of examples on the web on how to implement data validation with the Prototype JavaScript framework and CakePHP's AJAX helper. But so far there are not so many examples of an integration with CakePHP + jQuery.
Now, we'll take a look at how to do Ajax form validation with CakePHP and jQuery.
Before we start, let's set some goals first:
- We need to ensure that the user enter data properly by using CakePHP's validation class
- We would like to display an individual error message below each field
- We would like to display flash messages on success and failure
- We would like to validate multiple models in a single form view
- We would like to switch languages based on Localization (shortened to 'l10n')
- If the data is saved, we want the user to redirect to another location
Whew... That's a lot, isn't it?
Let's start with our typical Post Model with some validation rules.
<?php
class Post extends AppModel {
var $name = 'Post';
var $validate = array(
'title' => array(
'required' => array('rule' => 'notEmpty'),
'maxlength' => array('rule' => array('maxLength', 30))
),
'body' => array(
'required' => array('rule' => 'notEmpty'),
'maxlength' => array('rule' => array('maxLength', 200))
)
);
}
?>
We have two fields, “title” and “body” to be validated. We'll ensure that the fields are not empty, and the data stays within a maximum length requirement.
Let's do a simple view (posts/edit.ctp) which we'll use for both “add” and “edit” actions:
<?php
if (isset($javascript)) {
$javascript->link(array(
'jquery/jquery.min',
'page_specific/posts_edit'
), false);
}
?>
<div class="posts form">
<?php echo $form->create();?>
<fieldset>
<legend><?php $this->action == 'add' ? __('Add Post') : __('Edit Post'); ?></legend>
<?php
echo $form->input('id');
echo $form->input('title');
echo $form->input('body');
echo $form->input('published', array('checked' => true));
?>
</fieldset>
<div id="loadingDiv" style="display:none;">
<?php echo $html->image('ajax-loader.gif', array('alt' => 'Loading...')); ?>
</div>
<?php echo $form->end(__('Submit', true));?>
</div>
We have included the jQuery core and a file that will be specific to this view (No worries, we'll create this file next).
Also, we have added a loading div element with an image inside to handle the loading status of the request. When the user submit the form, the loading image will be displayed until the Ajax call is completed.
Okay, now let's create the page specific .js file (posts_edit.js):
$(function() {
var _loadingDiv = $("#loadingDiv");
$('#PostAddForm, #PostEditForm').submit(function(){
_loadingDiv.show();
$.post('/posts/ajax_edit',
$(this).serializeArray(),
afterValidate,
"json"
);
return false;
});
function afterValidate(data, status) {
$(".message").remove();
$(".error-message").remove();
if (data.errors) {
onError(data.errors);
} else if (data.success) {
onSuccess(data.success);
}
}
function onSuccess(data) {
flashMessage(data.message);
_loadingDiv.hide();
window.setTimeout(function() {
window.location.href = '/posts';
}, 2000);
};
function onError(data) {
flashMessage(data.message);
$.each(data.data, function(model, errors) {
for (fieldName in this) {
var element = $("#" + camelize(model + '_' + fieldName));
var _insert = $(document.createElement('div')).insertAfter(element);
_insert.addClass('error-message').text(this[fieldName])
}
_loadingDiv.hide();
});
};
function flashMessage(message) {
var _insert = $(document.createElement('div')).css('display', 'none');
_insert.attr('id', 'flashMessage').addClass('message').text(message);
_insert.insertBefore($(".posts")).fadeIn();
}
function camelize(string) {
var a = string.split('_'), i;
s = [];
for (i=0; i<a.length; i++){
s.push(a[i].charAt(0).toUpperCase() + a[i].substring(1));
}
s = s.join('');
return s;
}
});
Our jQuery code might be confusing to some of you. Yeah, it's kind of a bit long too. If we see those method names, we'll find out briefly what each method does.
We'll submit the form data to /posts/ajax_edit with jQuery's $.post method, and receive data in JSON format.
Let's take a look at the onError method. What's most important here is that the default DOM ID of each field is different from the name we gave it by default. For example, our “title” field corresponds to the DOM ID “PostTitle” (Camel-cased model and field name). So, we need to modify a little the returned JSON data for error messages to show.
NOTE: You may want to change the URL path to meet your Cake settings. We can't use $this->webroot to point to the web root in a separated .js file, so...for example:
// We can use an absolute URL like this:
$.post('/app/posts/ajax_edit', ...
window.location.href = '/app/posts';
// Or simply use a full URL:
$.post('http://www.example.com/posts/ajax_edit', ...
window.location.href = 'http://www.example.com/posts';
Now let's create a scenario for our controller.
class PostsController extends AppController {
var $name = 'Posts';
var $uses = array('Post');
var $helpers = array('Html', 'Form', 'Javascript');
var $components = array('RequestHandler');
function index() {}
function add() {
$this->render('edit');
}
function edit($id = null) {
if (!$id && empty($this->data)) {
$this->Session->setFlash(__('Invalid Post', true));
$this->redirect(array('action'=>'index'));
}
if (empty($this->data)) {
$this->data = $this->Post->read(null, $id);
}
}
function ajax_edit() {
Configure::write('debug', 0);
$this->layout = 'ajax';
if ($this->RequestHandler->isAjax()) {
if (!empty($this->data)) {
$this->Post->create();
$this->Post->set($this->data['Post']);
if($this->Post->validates()) {
if ($this->Post->save($this->data)) {
$message = __('The Post has been saved.', true);
$data = $this->data;
$this->set('success', compact('message', 'data'));
}
} else {
$message = __('The Post could not be saved. Please, try again.', true);
$Post = $this->Post->invalidFields();
$data = compact('Post');
$this->set('errors', compact('message', 'data'));
}
}
}
}
}
The index() is just an empty action which we send the user to after successful form submission, so just skip it. You can also skip the edit and add actions, but notice that we use the same view template (edit.ctp) for both actions just for convenience.
By the way, don't forget to add the RequestHandler component to the $components array, and the Html, Form and Javascript helpers to the $helpers array.
Let's look at our ajax_edit() closely.
We put the actual form elements in our edit (or add) view. Indeed, we post all the data to our Post's controller ajax_edit action.
Technically, there's no big difference with the way we do normally (other than the message handling). The point is that we simply attempt to validate the data, and send all the infomation (no matter what messages we receive after validating or saving the data) to our view.
Now we need some view to return the success/error messages back to jQuery script.
So, let's make the ajax_edit.ctp:
<?php
$output = array();
if($this->validationErrors) {
$output = Set::insert($output, 'errors', array('message' => $errors['message']));
$errorMessages = array(
'Post' => array(
'title' => array(
'required' => __("This field cannot be left blank.", true),
'maxlength' => sprintf(__("Maximum length of %d characters.", true), 30)
),
'body' => array(
'required' => __("This field cannot be left blank.", true),
'maxlength' => sprintf(__("Maximum length of %d characters.", true), 200)
)
)
);
foreach ($errors['data'] as $model => $errs) {
foreach ($errs as $field => $message) {
$output['errors']['data'][$model][$field] = $errorMessages[$model][$field][$message];
}
}
} elseif ($success) {
$output = Set::insert($output, 'success', array(
'message' => $success['message'],
'data' => $success['data']
));
}
echo $javascript->object($output);
?>
What does the output look like? We should get JSON output, something like this:
// Error output
{"errors":{
"message":"The Post could not be saved. Please, try again.",
"data":{
"Post":{
"title":"This field cannot be left blank.",
"body":"This field cannot be left blank."
}
}
}}
// Success output
{"success":{
"message":"The Post has been saved.",
"data":{
"Post":{
"id":"",
"title":"Lorem ipsum dolor sit amet",
"body":"Lorem ipsum dolor sit amet, aliquet ...",
"published":"1"
}
}
}}
Alright, let's take another look at a part of our jQuery code:
function onError(data) {
flashMessage(data.message);
$.each(data.data, function(model, errors) {
for (fieldName in this) {
var element = $("#" + camelize(model + '_' + fieldName));
var _insert = $(document.createElement('div')).insertAfter(element);
_insert.addClass('error-message').text(this[fieldName])
}
_loadingDiv.hide();
});
};
If any errors came back from our ajax_edit() action, we create a div element on the fly with the error message using createElement(), a DOM method that creates new document elements.
function flashMessage(message) {
var _insert = $(document.createElement('div')).css('display', 'none');
_insert.attr('id', 'flashMessage').addClass('message').text(message);
_insert.insertBefore($(".posts")).fadeIn();
}
Well, the flashMessage(), which is used by both success and failure, uses the createElement() as well to flash messages just above the form area.
function onSuccess(data) {
flashMessage(data.message);
_loadingDiv.hide();
window.setTimeout(function() {
window.location.href = '/posts';
}, 2000);
};
If there is no error, we happily send the user to /posts/index action. We added one gimmick here. We ask the script to wait for 2 seconds before the redirect so that the user can see the success message.
Alright, all done? Did we fulfill the goals we had in the beginning?
There might be some items that are not clear cut:
- We would like to validate multiple models in a single form view
- We would like to switch languages based on Localization (l10n)
Here is a tip for the first one. Write a proper code for saving multiple models (we don't go through the multiple save stuff here). We can add as many models as we want by doing something like:
// Our Post's controller ajax_edit action
$Post = $this->Post->invalidFields();
$AnotherModel = $this->AnotherModel->invalidFields();
$data = compact('Post', 'AnotherModel');
And don't forget to add error messages for “AnotherModel” to the $errorMessages array (ajax_edit.ctp)
Okay, let's move to the second one. Since we do view-side validation messages instead of putting error messages into our Post Model, it enables support for multiple languages (l10n).
Phew! All done.
You can download the code of this tutorial at http://code.google.com/p/jamnite/
