Outlast

Form validation

Manual form validation

Form data should be sent with Outlast Framework’s $('#formid').$ofw().submit() method. This will allow you to send the request to a controller where you can manually validate the data and provide a proper response.

Go see the documentation on how to send form data via ajax requests and provide proper responses.

In short, you can validate the form data using your own custom code and then return something like this:

	<?php
	/** This will display an alert message and highlight the fields by adding the has-error class to each. */
	$this->zajlib->json(array(
	'status'=>'error',
	'message'=>'An optional message that will be displayed to the user.',
	'highlight'=>array('name','email')
	));

view raw 1. response-error.php hosted with ❤ by GitHub

	<?php
	/** This will show Bootstrap tooltips for each field in the errors object. It will also add the has-error class to each. */
	$this->zajlib->json(array(
	'status'=>'error',
	'errors'=>array('name'=>'Please fill out your name!','email'=>'Invalid email address provided!')
	));

view raw 2. response-error-messages.php hosted with ❤ by GitHub

	<?php
	/** This is a success message, so that the client side can perform the success callback or redirect to the success url. */
	$this->zajlib->json(array(
	'status'=>'ok',
	));

view raw 3. response-success-message.php hosted with ❤ by GitHub

Automatic form validation

You can validate form fields based on their built-in validation methods (see below on defining how validation methods are defined for each field type).

	<?php
	// Validate data automatically for a single field 'email' in the model FormSignup
	$this->zajlib->form->validate('FormSignup', 'email', 'Invalid email address specified!');

view raw 1. single-validation.php hosted with ❤ by GitHub

	<?php
	// Validate data automatically for many fields...
	$this->zajlib->form->validate(
	'FormSignup',
	array('email', 'last', 'first', 'phone'),
	array('Invalid email address specified!', 'Last name required', 'First name required', 'Phone number required')
	);

view raw 2. multiple-validation.php hosted with ❤ by GitHub

For now, you must specify the error messages because default error messages are not provided by OFW.

Handling errors on the client side

All you need to do on the client side is to use the standard ajax request methods of the OFW Javascript API and use Bootstrap.

If you are using a callback function to handle the response you’ll need to manually call ofw.validate():

	$('#form').$zaj().submit('register/', function(response, responseJson){
	// Perform validation
	var validated = ofw.validate(response);
	// Invite if everything is ok
	if(validated){
	// Everything is valid, time to do something!
	}
	});

view raw manual-validation.js hosted with ❤ by GitHub

If a status error is returned, the following will happen automatically:

if you returned the message property, a zaj.alert() will pop up
if you returned the highlight property, all fields with errors will receive the .has-error Bootstrap class
if you returned the errors property, the fields will receive the .has-error Bootstrap class and a standard Bootstrap tooltop will be popped up displaying the error message
when .has-error is added, it will check to see if the input is in a form-group and will add the class to the form-group parent as well
if you used a callback function as the second parameter of your ajax request, the json data will simply be returned (as a string) and no automatic actions will be performed

Defining validation methods

Validation methods are set in each field-type’s field definition class. Open up the file /system/plugins/_jquery/fields/email.field.php and take note of the class’s validation method:

	<?php
	/**
	* Field definition for dates.
	* @package Fields
	* @subpackage BuiltinFields
	**/

	zajLib::me()->load->file('/fields/text.field.php');

	class zajfield_email extends zajfield_text {
	// similar to text, validation and editor differs
	const edit_template = 'field/email.field.html'; // string - the edit template, false if not used

	/**
	* Check to see if input data is valid.
	* @param mixed $input The input data.
	* @return boolean Returns true if validation was successful, false otherwise.
	**/
	public function validation($input){
	// Check to see if email is valid
	return zajLib::me()->email->valid($input);
	}
	}

view raw email.field.php hosted with ❤ by GitHub

If the validate() method of a field definition class returns true for the given value then the value will be considered valid. If false is returned, then it will be considered invalid.

This is designed to be simple. If you need more control than simply stating valid or invalid, you can always create additional manual form validations and return more specific error messages.

Defining the default error message

[todo: implement this!]

Until this is implemented, always use the 3rd parameter of $this->zajlib->form->validate() to specify your own error message.