Welcome to the Cookbook

The FormHelper is one of the most frequently used classes in CakePHP, and has had several improvements made to it.

Entity depth limitations

In 1.2 there was a hard limit of 5 nested keys. This posed significant limitations on form input creation in some contexts. In 1.3 you can now create infinitely nested form element keys. Validation errors and value reading for arbitrary depths has also been added.

Model introspection

Support for adding 'required' classes, and properties like maxlength to hasMany and other associations has been improved. In the past only 1 model and a limited set of associations would be introspected. In 1.3 models are introspected as needed, providing validation and additional information such as maxlength.

Default options for input()

In the past if you needed to use 'div' => false, or 'label' => false you would need to set those options on each and every call to input(). Instead in 1.3 you can declare a set of default options for input() with the inputDefaults key.

echo $this->Form->create('User', array(
        'inputDefaults' => array(
            'label' => false,
            'div' => false
        )
    ));

1. echo $this->Form->create('User', array(
2. 'inputDefaults' => array(
3. 'label' => false,
4. 'div' => false
5. )
6. ));

All inputs created from that point forward would inherit the options declared in inputDefaults. You can override the defaultOptions by declaring the option in the input() call.

echo $this->Form->input('password'); // No div, no label
echo $this->Form->input('username', array('label' => 'Username')); // has a label element

1. echo $this->Form->input('password'); // No div, no label
2. echo $this->Form->input('username', array('label' => 'Username')); // has a label element

Omit attributes

You can now set any attribute key to null or false in an options/attributes array to omit that attribute from a particular html tag.

echo $this->Form->input('username', array(
	'div' => array('class' => false)
)); // Omits the 'class' attribute added by default to div tag

1. echo $this->Form->input('username', array(
2. 'div' => array('class' => false)
3. )); // Omits the 'class' attribute added by default to div tag

Accept-charset

Forms now get an accept-charset set automatically, it will match the value of App.encoding, it can be overridden or removed using the 'encoding' option when calling create().

// To remove the accept-charset attribute.
echo $this->Form->create('User', array('encoding' => null));

1. // To remove the accept-charset attribute.
2. echo $this->Form->create('User', array('encoding' => null));

Removed parameters

Many methods such as select, year, month, day, hour, minute, meridian and datetime took a $showEmpty parameter, these have all been removed and rolled into the $attributes parameter using the 'empty' key.

Default url

The default url for forms either was add or edit depending on whether or not a primary key was detected in the data array. In 1.3 the default url will be the current action, making the forms submit to the action you are currently on.

Disabling hidden inputs for radio and checkbox

The automatically generated hidden inputs for radio and checkbox inputs can be disabled by setting the 'hiddenField' option to false.

button()

button() now creates button elements, these elements by default do not have html entity encoding enabled. You can enable html escaping using the escape option. The former features of FormHelper::button have been moved to FormHelper::submit.

submit()

Due to changes in button(), submit() can now generate reset, and other types of input buttons. Use the type option to change the default type of button generated. In addition to creating all types of buttons, submit() has before and after options that behave exactly like their counterparts in input().

$options['format']

The HTML generated by the form helper is now more flexible than ever before. The $options parameter to Form::input() now supports an array of strings describing the template you would like said element to follow. It's just been recently added to SCM, and has a few bugs for non PHP 5.3 users, but should be quite useful for all. The supported array keys are array('before', 'input', 'between', 'label', 'after', 'error').