milesjohnson

Before we begin creating the form, I will briefly go over how the attributes system work. Most, if not all the methods in Formation take an argument called $arguments, which will be equivalent to the HTML elements attributes. For example, if you pass a attribute of id equals "formation", then the HTML element will be populated with id="formation". By now you should get the jist of attributes, so lets begin by creating our form.

Opening the form
Like all forms, you need to create the opening form tag. You can do so by using the create() method. The first argument of create should be the name of the type of form, so if its a login form it should be named login; if no arguments are passed, it will default to "Form".

The second argument would be the attributes array. Additionally, create() comes with a special attribute called type. You can pass the the value of "file" or "app" which will auto-generate its value, instead of having to apply enctype equals multipart/form-data.

$form = new Form();
echo $form->create();
 
// Apply the file type and change method
echo $form->create('Login', array('type' => 'file', 'method' => 'get'));
 
// Outputs: <form id="LoginForm" action="" method="get" enctype="multipart/form-data">

Closing the form
This one is rather easy, seeing as how it takes no arguments. Simply place this at the very bottom of your form to close the form and its tags.

echo $form->close();

Creating the input fields
Now to create the HTML input fields you would use the robust all-purpose input() method. This method is an all around wrapper for all types of input elements. The first argument should be the name of the field to be applied to the element, and the second argument would be the attributes array. To do the most simply of fields, simply fill in the name argument.

echo $form->input('username');
// Outputs: <input id="LoginUsername" type="text" name="username" value="">

To make the fields more robust, simply pass an array of values to the attributes argument. For example, perhaps we want a password field thats limited in length.

echo $form->input('password', array('type' => 'password', 'maxlength' => 20));
// Outputs: <input id="LoginPassword" type="password" name="password" value="" maxlength="20">

By now you should of noticed the type attribute. This can be used to change what type of field the element should be. The following types are supported: text (default), textarea, password, hidden, image, file, select, radio, checkbox.

echo $form->input('comment', array('type' => 'textarea', 'rows' => 5, 'cols' => 50));
// Outputs: <textarea cols="50" rows="5" id="LoginComment" name="comment"></textarea>

Dealing with radio's and checkboxes
Radio's and checkboxes work a bit different then their text counterparts. For one thing you must pass an attribute value or the validation will fail, and secondly it has a more robust default/checking system. For example, say you want to make sure they read the Terms of Use.

echo $form->input('tos', array('type' => 'checkbox', 'value' => 'yes'));
// Outputs: <input id="LoginTos" type="checkbox" name="tos" value="yes">

When the form is posted and validated, you should see the "tos" index within the returned data array. If the checkbox was checked you would see "yes", and if it was not checked it would be empty and or fail the validation (if the rule was applied).

Radios work in the same manner where the value attribute must be supplied. Additionally you will need to supply your own id attribute or you may have conflicts.

<?php echo $form->input('gender', array('type' => 'radio', 'value' => 'male', 'id' => 'male', 'default' => true)); ?> Male
<?php echo $form->input('gender', array('type' => 'radio', 'value' => 'female', 'id' => 'female')); ?> Female
 
/* Outputs:
<input id="LoginMale" type="radio" name="gender" value="male" checked="checked"> Male
<input id="LoginFemale" type="radio" name="gender" value="female"> Female */

If you wish to set the "male" radio checked by default, you would pass an attribute of default equals true. However, you may also pass default equals "male", which would accomplish the same result.

Dealing with select drop downs
Now for the last input field type, the select. The select has a special attribute called "options" which is an array that would contain the value option pairs in the drop-down. Additionally, if you don't pass the type attribute of select, but did pass an options attribute, it will generate a select automatically.

echo $form->input('gender', array('options' => array('male' => 'Male', 'female' => 'Female')));
/* Outputs:
<select id="LoginGender" name="gender">
<option value="male">Male</option>
<option value="female">Female</option>
</select> */

Selects also support optgroups and can be done by creating a dimensional array. Below is an example of how the array should be formatted and the definite result. You may also set a default and an empty option by using the respective default and empty attributes.

// Games Array
$games = array(
	'First Person Shooter' => array(
		'cs' => 'Counter-Strike', 
		'tf2' => 'Team Fortress 2'
	),
	'Real-Time Strategy' => array(
		'sc' => 'Starcraft', 
		'wc3' => 'Warcraft 3'
	),
	'MMORPG' => array(
		'wow' => 'World of Warcraft'
	)
);
 
echo $form->input('games', array('options' => $games, 'empty' => '-- Select a Game --', 'default' => 'tf2'));
 
/* Outputs:
<select id="LoginGames" name="games">
<option value="">-- Select a Game --</option>
<optgroup label="First Person Shooter">
	<option value="cs">Counter-Strike</option>
	<option value="tf2" selected="selected">Team Fortress 2</option>
</optgroup>
<optgroup label="Real-Time Strategy">
	<option value="sc">Starcraft</option>
	<option value="wc3">Warcraft 3</option>
</optgroup>
<optgroup label="MMORPG">
	<option value="wow">World of Warcraft</option>
</optgroup>
</select> */

Adding the submit and reset buttons
You can't have a form without having buttons to post the data! To create a submit button you would use the submit() method, and to create a reset button you would use the reset() method, of course! Both take the same arguments, the first would be the text to display on the button, the second would be an array of attributes.

<?php echo $form->submit('Submit'); ?>
<?php echo $form->reset('Reset', array('class' => 'button'))?>
 
/* Outputs:
<input id="LoginSubmitButton" type="submit" value="Submit">
<input id="LoginResetButton" type="reset" value="Reset" class="button"> */

Adding labels
What kind of form would you have without labels? A terrible one that's for sure. To create labels you would use the label() method. The first argument would be the name of the input field you are applying it to, the second argument would be the text to be used in the label and the third would be the attributes. Simple as that.

<?php echo $form->label('name', 'Name'); ?>
<?php echo $form->input('name'); ?>
 
/* Outputs:
<label for="LoginName">Name</label>
<input id="LoginName" type="text" name="name" value=""> */

Now what good is a form if you can't post any data? The process() method can handle all your data posting and processing and supports multiple types of data: $_POST, $_GET, $_REQUEST, etc. The processing functionality should be placed at the top of your page, or if anything above your actual form. The first argument of process() would be the data type you want to use, in our examples we will use the most common of types, the $_POST.

if ($form->process($_POST)) {
	// Do validation and cleaning
}

You can pass a second argument with the name of an input field, usually the submit button's name attribute. When doing so, the form will only process if that name value exists in the data array.

if ($form->process($_POST, 'submit')) {
	// Do validation and cleaning if the submit name exists
}

Validation is always the fun and tedious part about dealing with form data, but don't fret, Formation comes pre-built with many methods of validation. The following types of validation are supported: notEmpty, all characters, alpha, numeric, alphanumeric, boolean, date, decimal, email, extension, ip, phone, date, time, website/url, within a list, within a range, within a character length, matching and custom regex.

The one plus side of Formations validation is that you don't have to call a validation method for each input field, nor do you have to do giant if statements. All you need to do is pass a validation schema, which should be an array containing the fields you want to validate and a set of rules and their options. The schema should be a dimensional array with the first index being the input field name (attribute) and its value being an array of rulesets. The rules will be parsed from top to bottom and will stop once it reaches an error, instead of parsing all rules at once.

As for the rulesets array, the index should be the name of the method (in the Formation class) that you want to use, and the value should be an array of options (if there are any) or the error message to display. You can determine if a rule has options by viewing its respective method in the class. If the method has additional arguments after the $message argument, those would be the extra options to apply. In the example below you will notice the checkLength rule has two additional options, these would correlate to the $max and $min arguments in the method.

By default, all fields are required. If you do not want a field to be required, set required equals false in the ruleset.

$schema = array(
	'name' => array(
		'notEmpty' => 'Your name is required'
	),
	'email' => array(
		'notEmpty' => 'Your email is required',
		'isEmail' => 'Your email is invalid'
	),
	'password' => array(
		'notEmpty' => 'Your password is required',
		'isAlnum' => 'Your password may only be alpha-numeric',
		'checkLength' => array('Password must be between 6-12 characters', 12, 6)
	)
);

Once you have your schema setup, you would validate it using the validates() method. This should be called once you have processed the form, like so.

if ($form->process($_POST)) {
	if ($form->validates($schema)) {
		// Clean data and do your logic
	}
 
	$errors = $form->getErrors();
}

Cleaning Your Data
Once your form validates, the next best thing is to clean your data. This is good practice, especially if the data will be inserted into a database. To clean the data, you would use the clean() method, which should be called within the validates() if statement.

$clean = $form->clean();

By default, it will clean all indexes in the array and strip all HTML. If you want to clean only certain indexes, you would pass an array of their names as the first argument. If you do not want HTML removed, pass false as the second argument.

$clean = $form->clean(array('name'), false);

To grab the errors in the current form process, you would use the getErrors() method. It's good practice to place this within the process() if statement so that errors aren't generated unless the form has been posted. The returned data would be an array containing the error messages from the validation schema, paired with the input field that failed.

if ($form->process($_POST)) {
	// Validation here
 
	$errors = $form->getErrors();
}

Once you have your errors returned into the $errors variable, you can just loop the errors in your template to display them. It's that easy!

<?php // Form errors
if (!empty($errors)) { ?>
<ul>
	<?php foreach ($errors as $error) { ?>
	<li><?php echo $error; ?></li>
	<?php } ?>
</ul>
<?php } ?>

I thought it would be best to put together a full example for you to base your code on.

// Include and initialize
require_once('form.php'); 
$form = new Form();

// Check to see if form is posted
if ($form->process($_POST)) {
	$schema = array(
		'name' => array(
			'notEmpty' => 'Your name is required',
			'isAllChars' => 'Your name contains invalid characters'
		),
		'email' => array(
			'notEmpty' => 'Your email is required',
			'isEmail' => 'Your email is invalid'
		),
		'website' => array(
			'isWebsite' => 'Your website URL is invalid',
			'required' => false
		),
		'password' => array(
			'notEmpty' => 'Your password is required',
			'isAlnum' => 'Your password may only be alpha-numeric',
			'checkLength' => array('Password must be between 6-12 characters', 12, 6)
		),
		'age' => array(
			'isNumeric' => 'Your age must be numeric',
			'required' => false
		),
		'tos' => array(
			'notEmpty' => 'You must agree to the TOS'
		)
	);
	
	// Validate form and pass
	if ($form->validates($schema)) {
		$clean = $form->clean();
		// Data is ready for use
	}
	
	$errors = $form->getErrors();
} 

$games = array(
	'First Person Shooter' => array(
		'cs' => 'Counter-Strike', 
		'tf2' => 'Team Fortress 2'
	),
	'Real-Time Strategy' => array(
		'sc' => 'Starcraft', 
		'wc3' => 'Warcraft 3'
	),
	'MMORPG' => array(
		'wow' => 'World of Warcraft'
	)
); ?>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Formation Test</title>
<style type="text/css">
.input-error { border: 1px solid red; }
</style>
</head>

<body>
<?php // Form errors
if (!empty($errors)) { ?>
<ul>
	<?php foreach ($errors as $error) { ?>
	<li><?php echo $error; ?></li>
	<?php } ?>
</ul>
<?php } ?>

<?php // Create form
echo $form->create('Login'); ?>

<p><?php echo $form->label('name', 'Name'); ?>
<?php echo $form->input('name'); ?></p>

<p><?php echo $form->label('email', 'Email'); ?>
<?php echo $form->input('email'); ?></p>

<p><?php echo $form->label('password', 'Password'); ?>
<?php echo $form->input('password', array('type' => 'password')); ?></p>

<p><?php echo $form->label('website', 'Website'); ?>
<?php echo $form->input('website'); ?></p>

<p><?php echo $form->label('age', 'Age'); ?>
<?php echo $form->input('age', array('size' => 1)); ?></p>

<p><?php echo $form->label('games', 'Favorite Games'); ?>
<?php echo $form->input('games', array('options' => $games, 'empty' => '-- Select a Game --', 'default' => 'tf2')); ?></p>

<p><?php echo $form->input('tos', array('type' => 'checkbox', 'value' => 'yes')); ?>
<?php echo $form->label('tos', 'Do you agree to the Terms of Service?'); ?></p>

<p>
    <?php echo $form->input('gender', array('type' => 'radio', 'value' => 'male', 'id' => 'male', 'default' => true)); ?> Male
    <?php echo $form->input('gender', array('type' => 'radio', 'value' => 'female', 'id' => 'female')); ?> Female
</p>	

<p><?php echo $form->submit('Submit'); ?>
<?php echo $form->reset('Reset', array('class' => 'button'))?></p>

<?php // Close form
echo $form->close(); ?>

</body>
</html>

Like any of my classes, I try to add in a few convenience methods to make it easier on you in some situations.

Manually calling an error
If you need to do some error checking and validation that is not supported by the default validation system, you can use the error() method. This will add an input and an error message to the error messages list.

$form->error('username', 'Your username is incorrect');

Resetting the data
If you need to reset the data and all error messages to null, you can use the resetData() method. A good place to use it is once a form validates, so that you clear the form so that it cannot be posted again.

$form->resetData();

Cleaning data outside of the form
If you wish to clean some data externally out of the form, you can use the static method cleanse();

Form::cleanse($data)

Getting a value from the data
If you need to grab a single value from the data array, you can use the get() method. This is extremely useful for the checkMatch() method.

$password = $form->get('password');
 
// Within validation rule
'checkMatch' => array('The two values do not match!', $form->get('confirmPassword'))

Using all the validation methods outside of the form
All the pre-built validation methods are created to be used statically so that you may use them everywhere else in your application.

if (Form::isEmail($email)) {
	// Correct!
}