$.handleForm() is..

… a simple jQuery plugin that submits your forms with $.ajax(), without the hassle.

$.handleForm() is also..

Build specifically for use with Twitter's excellent Bootstrap CSS/JS framework.

It's flexibility, buildt with server-side validation in mind.

It's so pretty!

Coupled with Twitter Bootstrap, it makes it super easy to have functional, beautiful ajaxified forms interact with your backend of choice.

CakePHP you say?

Ajax based forms with the CakePHP framework used to drive me nuts and make me hate the $validate array.

Well, not anymore.

But I don't eat cake

No worries, a little PHP json_encode() (or similar) trickery on the backend should get you up and running.

Installation

Just add jquery.handleform.js to your existing script list (after jQuery, of course)

<script src="path/to/jquery.js"></script>
<script src="path/to/jquery.handleform.js"></script>
<!-- Might I recommend Twitter's Bootstrap too? -->
<link href="path/to/bootstrap.css" rel="stylesheet">

No, you don't NEED Bootstrap, but you'll want to implement the CSS classes the script uses to make things look non-ugly.

Using it

.. is pretty simple.

$(function() {
	$('#my_form').handleForm(); // That's it!
});

While no options are required, it won't be as exciting, obviously. Sure, you'll get a pretty message saying how the FORM request panned out, but that'll only get you so far.

$(selector).handleForm({

	// on submit, blur, change, etc.
	trigger : 'submit', 
	
	// Slide in/out errors & messages
	transitionTime : 250,
	
	// What should the submit button text read while working?
	loadingText : 'Saving…',
	
	// What DOM element should the response be placed in?
	target : false,
	
	// How do you want the response placed in the target?
	targetMethod : 'replaceWith', 
	
	// Using Bootstrap's modal script or Facebox? This one's for you:
	closeModal : false, 
	
	// What should the success message read? Set to false for no message.
	successMessage : 'Great success!',  
	
	// .. and with what (bootstrap) alert-message class? 
	successClass : 'info',
	
	// Or perhaps, forward to another URL when successful?
	successUrl : false,
	
	// Give the successMessage some screentime before moving on? (in ms)
	successUrlDelay : 0,
	
	// Where should the successMessage be shown?
	// If you don't specify the plugin will create and .append it to your $(selector)
	successContainer : '.success-message-container', 
	
	// When things go wrong, what should we tell the user?
	errorMessage : 'Uh oh, something went wrong skipper:',
	
	// .. and with what (bootstrap) alert-message class? 
	errorClass : 'warning',
	
	// When requests go sideways, place the errorMessage in...
	errorContainer : '.error-message-container', 
	
	// Send the user somewhere else if the request fails?
	errorUrl : false, 
	
	/*
	 Ah, the callbacks. These are pretty self explanatory. 
	 ie. onSuccess : function(data) { alert('Look ma, I got me some ' + data); }
	 
	 Also of note: var handleFormOptions.optionname are available in the callbacks.
	*/
		
	// Specific when recieving a JSON response
	onJsonSuccess : false, 
	
	// Always run on successful request.
	onSuccess : false,
	
	// Always run on unsuccessful request.
	onError : false,
});

Backend

is exactly this easy:

For validation error messages, add this to your Controller's action():

if($this->Modelname->invalidFields()) {
	header('Content-type: application/json');
	$this->autoRender = false;
	$response = array('validationErrors' => $this->Temp->invalidFields());
	echo json_encode($response);
	exit();
}

Yes, we're breaking the MVC a bit. A smoother solution would be to move this into a Component and trigged this on beforeRender() or similar, and render an actual json view. I'll leave that up to you guys for now.

Any other backend can respond with something like this

{"validationErrors":
	{"username":["You must supply a username"]}
}

Notice the peculiar formatting for the username object. That's because of CakePHP's insistence on sending us three validation errors per field. Maybe I'll clean that up in the future.

A heads up

If you want to make CakePHP forms look nicer in Bootstrap (and also, make error messages appear properly), try something this when creating your forms:

echo $this->Form->create('Modelname', array(
	'class' => 'form-stacked',
	'inputDefaults' => array(
		'div' => 'clearfix',
		'between' => '<div class="input">',
		'after' => '</div>',
    )
));

Note: This will probably break havoc on your radio/checkboxes and stuff.