FormHelper¶

Creating Forms¶

The first method you’ll need to use in order to take advantage of the FormHelper is create(). This special method outputs an opening form tag.

FormHelper::create(string $model = null, array $options = array())¶

All parameters are optional. If create() is called with no parameters supplied, it assumes you are building a form that submits to the current controller, via the current URL. The default method for form submission is POST. The form element is also returned with a DOM ID. The ID is generated using the name of the model, and the name of the controller action, CamelCased. If I were to call create() inside a UsersController view, I’d see something like the following output in the rendered view:

<form id="UserAddForm" method="post" action="/users/add">

Note

You can also pass false for $model. This will place your form data into the array: $this->request->data (instead of in the sub-array: $this->request->data['Model']). This can be handy for short forms that may not represent anything in your database.

The create() method allows us to customize much more using the parameters, however. First, you can specify a model name. By specifying a model for a form, you are creating that form’s context. All fields are assumed to belong to this model (unless otherwise specified), and all models referenced are assumed to be associated with it. If you do not specify a model, then it assumes you are using the default model for the current controller:

// If you are on /recipes/add
echo $this->Form->create('Recipe');

Output:

<form id="RecipeAddForm" method="post" action="/recipes/add">

This will POST the form data to the add() action of RecipesController. However, you can also use the same logic to create an edit form. The FormHelper uses the $this->request->data property to automatically detect whether to create an add or edit form. If $this->request->data contains an array element named after the form’s model, and that array contains a non-empty value of the model’s primary key, then the FormHelper will create an edit form for that record. For example, if we browse to https://site.com/recipes/edit/5, we would get the following:

// Controller/RecipesController.php:
public function edit($id = null) {
    if (empty($this->request->data)) {
        $this->request->data = $this->Recipe->findById($id);
    } else {
        // Save logic goes here
    }
}

// View/Recipes/edit.ctp:
// Since $this->request->data['Recipe']['id'] = 5,
// we will get an edit form
<?php echo $this->Form->create('Recipe'); ?>

Output:

<form id="RecipeEditForm" method="post" action="/recipes/edit/5">
<input type="hidden" name="_method" value="PUT" />

Note

Since this is an edit form, a hidden input field is generated to override the default HTTP method.

When creating forms for models in plugins, you should always use plugin syntax when creating a form. This will ensure the form is correctly generated:

echo $this->Form->create('ContactManager.Contact');

The $options array is where most of the form configuration happens. This special array can contain a number of different key-value pairs that affect the way the form tag is generated.

Changed in version 2.0: The default URL for all forms, is now the current URL including passed, named, and querystring parameters. You can override this default by supplying $options['url'] in the second parameter of $this->Form->create().

Closing the Form¶

FormHelper::end($options = null, $secureAttributes = array())¶

The FormHelper includes an end() method that completes the form. Often, end() only outputs a closing form tag, but using end() also allows the FormHelper to insert needed hidden form elements that SecurityComponent requires:

<?php echo $this->Form->create(); ?>

<!-- Form elements go here -->

<?php echo $this->Form->end(); ?>

If a string is supplied as the first parameter to end(), the FormHelper outputs a submit button named accordingly along with the closing form tag:

<?php echo $this->Form->end('Finish'); ?>

Will output:

<div class="submit">
    <input type="submit" value="Finish" />
</div>
</form>

You can specify detail settings by passing an array to end():

$options = array(
    'label' => 'Update',
    'div' => array(
        'class' => 'glass-pill',
    )
);
echo $this->Form->end($options);

Will output:

<div class="glass-pill"><input type="submit" value="Update" name="Update">
</div>

See the Form Helper API for further details.

Note

If you are using SecurityComponent in your application you should always end your forms with end().

Changed in version 2.5: The $secureAttributes parameter was added in 2.5.

Creating form elements¶

There are a few ways to create form inputs with the FormHelper. We’ll start by looking at input(). This method will automatically inspect the model field it has been supplied in order to create an appropriate input for that field. Internally input() delegates to other methods in FormHelper.

FormHelper::input(string $fieldName, array $options = array())¶

Creates the following elements given a particular Model.field:

• Wrapping div.

• Label element

• Input element(s)

• Error element with message if applicable.

The type of input created depends on the column datatype:

Column Type

Resulting Form Field

string (char, varchar, etc.)

text

boolean, tinyint(1)

checkbox

text

textarea

text, with name of password, passwd, or psword

password

text, with name of email

email

text, with name of tel, telephone, or phone

tel

date

day, month, and year selects

datetime, timestamp

day, month, year, hour, minute, and meridian selects

time

hour, minute, and meridian selects

binary

file

The $options parameter allows you to customize how input() works, and finely control what is generated.

The wrapping div will have a required class name appended if the validation rules for the Model’s field do not specify allowEmpty => true. One limitation of this behavior is the field’s model must have been loaded during this request. Or be directly associated to the model supplied to create().

New in version 2.5: The binary type now maps to a file input.

New in version 2.3.

Since 2.3 the HTML5 required attribute will also be added to the input based on validation rules. You can explicitly set required key in options array to override it for a field. To skip browser validation triggering for the whole form you can set option 'formnovalidate' => true for the input button you generate using FormHelper::submit() or set 'novalidate' => true in options for FormHelper::create().

For example, let’s assume that your User model includes fields for a username (varchar), password (varchar), approved (datetime) and quote (text). You can use the input() method of the FormHelper to create appropriate inputs for all of these form fields:

echo $this->Form->create();

echo $this->Form->input('username');   //text
echo $this->Form->input('password');   //password
echo $this->Form->input('approved');   //day, month, year, hour, minute,
                                       //meridian
echo $this->Form->input('quote');      //textarea

echo $this->Form->end('Add');

A more extensive example showing some options for a date field:

echo $this->Form->input('birth_dt', array(
    'label' => 'Date of birth',
    'dateFormat' => 'DMY',
    'minYear' => date('Y') - 70,
    'maxYear' => date('Y') - 18,
));

Besides the specific options for input() found below, you can specify any option for the input type & any HTML attribute (for instance onfocus). For more information on $options and $htmlAttributes see HtmlHelper.

Assuming that User hasAndBelongsToMany Group. In your controller, set a camelCase plural variable (group -> groups in this case, or ExtraFunkyModel -> extraFunkyModels) with the select options. In the controller action you would put the following:

$this->set('groups', $this->User->Group->find('list'));

And in the view a multiple select can be created with this simple code:

echo $this->Form->input('Group', array('multiple' => true));

If you want to create a select field while using a belongsTo - or hasOne - Relation, you can add the following to your Users-controller (assuming your User belongsTo Group):

$this->set('groups', $this->User->Group->find('list'));

Afterwards, add the following to your form-view:

echo $this->Form->input('group_id');

If your model name consists of two or more words, e.g., “UserGroup”, when passing the data using set() you should name your data in a pluralised and camelCased format as follows:

$this->set('userGroups', $this->UserGroup->find('list'));
// or
$this->set(
    'reallyInappropriateModelNames',
    $this->ReallyInappropriateModelName->find('list')
);

Note

Try to avoid using FormHelper::input() to generate submit buttons. Use FormHelper::submit() instead.

FormHelper::inputs(mixed $fields = null, array $blacklist = null, $options = array())¶

Generate a set of inputs for $fields. If $fields is null all fields, except of those defined in $blacklist, of the current model will be used.

In addition to controller fields output, $fields can be used to control legend and fieldset rendering with the fieldset and legend keys. $this->Form->inputs(array('legend' => 'My legend')); Would generate an input set with a custom legend. You can customize individual inputs through $fields as well.

echo $this->Form->inputs(array(
    'name' => array('label' => 'custom label')
));

In addition to fields control, inputs() allows you to use a few additional options.

• fieldset Set to false to disable the fieldset. If a string is supplied it will be used as the class name for the fieldset element.

• legend Set to false to disable the legend for the generated input set. Or supply a string to customize the legend text.

<input type="text" id="ModelnameFieldname" name="data[Modelname][fieldname]">

echo $this->Form->input('Modelname.fieldname');

echo $this->Form->input('Modelname.0.fieldname');
echo $this->Form->input('Modelname.1.fieldname');

<input type="text" id="Modelname0Fieldname"
    name="data[Modelname][0][fieldname]">
<input type="text" id="Modelname1Fieldname"
    name="data[Modelname][1][fieldname]">

echo $this->Form->input('Model.year', array(
    'type' => 'text',
    'name' => 'data[Model][year]'
));

// Makes <input name="email" type="text" />
echo $this->Form->input('User.email');

// Makes <select name="Tags" multiple="multiple">
echo $this->Form->input('Tags.Tags', array('multiple' => true));

// Makes the more typical <input name="data[User][email]" type="text" />
echo $this->Form->input('User.email', array('name' => 'data[User][email]'));

Generating specific types of inputs¶

In addition to the generic input() method, FormHelper has specific methods for generating a number of different types of inputs. These can be used to generate just the input widget itself, and combined with other methods like label() and error() to generate fully custom form layouts.

Form Element-Specific Methods¶

All elements are created under a form for the User model as in the examples above. For this reason, the HTML code generated will contain attributes that reference to the User model. Ex: name=data[User][username], id=UserUsername

FormHelper::label(string $fieldName, string $text, array $options)¶

Create a label element. $fieldName is used for generating the DOM id. If $text is undefined, $fieldName will be used to inflect the label’s text:

echo $this->Form->label('User.name');
echo $this->Form->label('User.name', 'Your username');

Output:

<label for="UserName">Name</label>
<label for="UserName">Your username</label>

$options can either be an array of HTML attributes, or a string that will be used as a class name:

echo $this->Form->label('User.name', null, array('id' => 'user-label'));
echo $this->Form->label('User.name', 'Your username', 'highlight');

Output:

<label for="UserName" id="user-label">Name</label>
<label for="UserName" class="highlight">Your username</label>

FormHelper::text(string $name, array $options)¶

The rest of the methods available in the FormHelper are for creating specific form elements. Many of these methods also make use of a special $options parameter. In this case, however, $options is used primarily to specify HTML tag attributes (such as the value or DOM id of an element in the form):

echo $this->Form->text('username', array('class' => 'users'));

Will output:

<input name="data[User][username]" type="text" class="users"
    id="UserUsername" />

FormHelper::password(string $fieldName, array $options)¶

Creates a password field.

echo $this->Form->password('password');

Will output:

<input name="data[User][password]" value="" id="UserPassword"
    type="password" />

FormHelper::hidden(string $fieldName, array $options)¶

Creates a hidden form input. Example:

echo $this->Form->hidden('id');

Will output:

<input name="data[User][id]" id="UserId" type="hidden" />

If the form is edited (that is, the array $this->request->data will contain the information saved for the User model), the value corresponding to id field will automatically be added to the HTML generated. Example for data[User][id] = 10:

<input name="data[User][id]" id="UserId" type="hidden" value="10" />

Changed in version 2.0: Hidden fields no longer remove the class attribute. This means that if there are validation errors on hidden fields, the error-field class name will be applied.

FormHelper::textarea(string $fieldName, array $options)¶

Creates a textarea input field.

echo $this->Form->textarea('notes');

Will output:

<textarea name="data[User][notes]" id="UserNotes"></textarea>

If the form is edited (that is, the array $this->request->data will contain the information saved for the User model), the value corresponding to notes field will automatically be added to the HTML generated. Example:

<textarea name="data[User][notes]" id="UserNotes">
This text is to be edited.
</textarea>

Note

The textarea input type allows for the $options attribute of 'escape' which determines whether or not the contents of the textarea should be escaped. Defaults to true.

echo $this->Form->textarea('notes', array('escape' => false);
// OR....
echo $this->Form->input(
    'notes',
    array('type' => 'textarea', 'escape' => false)
);

Options

In addition to the Common options, textarea() supports a few specific options:

• $options['rows'], $options['cols'] These two keys specify the number of rows and columns:

  echo $this->Form->textarea(
      'textarea',
      array('rows' => '5', 'cols' => '5')
  );
  

  Output:

  <textarea name="data[Form][textarea]" cols="5" rows="5" id="FormTextarea">
  </textarea>
  

FormHelper::checkbox(string $fieldName, array $options)¶

Creates a checkbox form element. This method also generates an associated hidden form input to force the submission of data for the specified field.

echo $this->Form->checkbox('done');

Will output:

<input type="hidden" name="data[User][done]" value="0" id="UserDone_" />
<input type="checkbox" name="data[User][done]" value="1" id="UserDone" />

It is possible to specify the value of the checkbox by using the $options array:

echo $this->Form->checkbox('done', array('value' => 555));

Will output:

<input type="hidden" name="data[User][done]" value="0" id="UserDone_" />
<input type="checkbox" name="data[User][done]" value="555" id="UserDone" />

If you don’t want the Form helper to create a hidden input:

echo $this->Form->checkbox('done', array('hiddenField' => false));

Will output:

<input type="checkbox" name="data[User][done]" value="1" id="UserDone" />

FormHelper::radio(string $fieldName, array $options, array $attributes)¶

Creates a set of radio button inputs.

Options

• $attributes['value'] to set which value should be selected default.

• $attributes['separator'] to specify HTML in between radio buttons (e.g. <br />).

• $attributes['between'] specify some content to be inserted between the legend and first element.

• $attributes['disabled'] Setting this to true or 'disabled' will disable all of the generated radio buttons.

• $attributes['legend'] Radio elements are wrapped with a legend and fieldset by default. Set $attributes['legend'] to false to remove them.

  $options = array('M' => 'Male', 'F' => 'Female');
  $attributes = array('legend' => false);
  echo $this->Form->radio('gender', $options, $attributes);
  

  Will output:

  <input name="data[User][gender]" id="UserGender_" value=""
      type="hidden" />
  <input name="data[User][gender]" id="UserGenderM" value="M"
      type="radio" />
  <label for="UserGenderM">Male</label>
  <input name="data[User][gender]" id="UserGenderF" value="F"
      type="radio" />
  <label for="UserGenderF">Female</label>
  

If for some reason you don’t want the hidden input, setting $attributes['value'] to a selected value or boolean false will do just that.

• $attributes['fieldset'] If legend attribute is not set to false, then this attribute can be used to set the class of the fieldset element.

Changed in version 2.1: The $attributes['disabled'] option was added in 2.1.

Changed in version 2.8.5: The $attributes['fieldset'] option was added in 2.8.5.

FormHelper::select(string $fieldName, array $options, array $attributes)¶

Creates a select element, populated with the items in $options, with the option specified by $attributes['value'] shown as selected by default. Set the ‘empty’ key in the $attributes variable to false to turn off the default empty option:

$options = array('M' => 'Male', 'F' => 'Female');
echo $this->Form->select('gender', $options);

Will output:

<select name="data[User][gender]" id="UserGender">
<option value=""></option>
<option value="M">Male</option>
<option value="F">Female</option>
</select>

The select input type allows for a special $option attribute called 'escape' which accepts a bool and determines whether to HTML entity encode the contents of the select options. Defaults to true:

$options = array('M' => 'Male', 'F' => 'Female');
echo $this->Form->select('gender', $options, array('escape' => false));

• $attributes['options'] This key allows you to manually specify options for a select input, or for a radio group. Unless the ‘type’ is specified as ‘radio’, the FormHelper will assume that the target output is a select input:

  echo $this->Form->select('field', array(1,2,3,4,5));
  

  Output:

  <select name="data[User][field]" id="UserField">
      <option value="0">1</option>
      <option value="1">2</option>
      <option value="2">3</option>
      <option value="3">4</option>
      <option value="4">5</option>
  </select>
  

  Options can also be supplied as key-value pairs:

  echo $this->Form->select('field', array(
      'Value 1' => 'Label 1',
      'Value 2' => 'Label 2',
      'Value 3' => 'Label 3'
  ));
  

  Output:

  <select name="data[User][field]" id="UserField">
      <option value=""></option>
      <option value="Value 1">Label 1</option>
      <option value="Value 2">Label 2</option>
      <option value="Value 3">Label 3</option>
  </select>
  

  If you would like to generate a select with optgroups, just pass data in hierarchical format. This works on multiple checkboxes and radio buttons too, but instead of optgroups wraps elements in fieldsets:

  $options = array(
     'Group 1' => array(
        'Value 1' => 'Label 1',
        'Value 2' => 'Label 2'
     ),
     'Group 2' => array(
        'Value 3' => 'Label 3'
     )
  );
  echo $this->Form->select('field', $options);
  

  Output:

  <select name="data[User][field]" id="UserField">
      <optgroup label="Group 1">
          <option value="Value 1">Label 1</option>
          <option value="Value 2">Label 2</option>
      </optgroup>
      <optgroup label="Group 2">
          <option value="Value 3">Label 3</option>
      </optgroup>
  </select>
  

• $attributes['multiple'] If ‘multiple’ has been set to true for an input that outputs a select, the select will allow multiple selections:

  echo $this->Form->select(
      'Model.field',
      $options,
      array('multiple' => true)
  );
  

  Alternatively set ‘multiple’ to ‘checkbox’ to output a list of related check boxes:

  $options = array(
      'Value 1' => 'Label 1',
      'Value 2' => 'Label 2'
  );
  echo $this->Form->select('Model.field', $options, array(
      'multiple' => 'checkbox'
  ));
  

  Output:

  <div class="input select">
     <label for="ModelField">Field</label>
     <input name="data[Model][field]" value="" id="ModelField"
      type="hidden">
     <div class="checkbox">
        <input name="data[Model][field][]" value="Value 1"
          id="ModelField1" type="checkbox">
        <label for="ModelField1">Label 1</label>
     </div>
     <div class="checkbox">
        <input name="data[Model][field][]" value="Value 2"
          id="ModelField2" type="checkbox">
        <label for="ModelField2">Label 2</label>
     </div>
  </div>
  

• $attributes['disabled'] When creating checkboxes, this option can be set to disable all or some checkboxes. To disable all checkboxes set disabled to true:

  $options = array(
      'Value 1' => 'Label 1',
      'Value 2' => 'Label 2'
  );
  echo $this->Form->select('Model.field', $options, array(
      'multiple' => 'checkbox',
      'disabled' => array('Value 1')
  ));
  

  Output:

  <div class="input select">
     <label for="ModelField">Field</label>
     <input name="data[Model][field]" value="" id="ModelField"
      type="hidden">
     <div class="checkbox">
        <input name="data[Model][field][]" disabled="disabled"
          value="Value 1" id="ModelField1" type="checkbox">
        <label for="ModelField1">Label 1</label>
     </div>
     <div class="checkbox">
        <input name="data[Model][field][]" value="Value 2"
          id="ModelField2" type="checkbox">
        <label for="ModelField2">Label 2</label>
     </div>
  </div>
  

• $attributes['showParents'] When creating selects with optgroups this will ensure an element will be added for the parent of each option group:

  $options = array(
      'First' => array('Label 1', 'Label 2'),
      'Second' => array('Second', 'Third'),
  );
  echo $this->Form->select('Model.field', $options, array(
      'showParents' => true
  ));
  

  Output:

  <select name="data[Model][field]" id="ModelField">
      <optgroup label="First">
          <option value="0">Label 1</option>
          <option value="1">Label 2</option>
      </optgroup>
      <optgroup label="Second">
          <option value="0">Second</option>
          <option value="1">Third</option>
      </optgroup>
  </select>
  

Changed in version 2.3: Support for arrays in $attributes['disabled'] was added in 2.3.

FormHelper::file(string $fieldName, array $options)¶

To add a file upload field to a form, you must first make sure that the form enctype is set to “multipart/form-data”, so start off with a create function such as the following:

echo $this->Form->create('Document', array(
    'enctype' => 'multipart/form-data'
));
// OR
echo $this->Form->create('Document', array('type' => 'file'));

Next add either of the two lines to your form view file:

echo $this->Form->input('Document.submittedfile', array(
    'between' => '<br />',
    'type' => 'file'
));

// OR

echo $this->Form->file('Document.submittedfile');

Due to the limitations of HTML itself, it is not possible to put default values into input fields of type ‘file’. Each time the form is displayed, the value inside will be empty.

Upon submission, file fields provide an expanded data array to the script receiving the form data.

For the example above, the values in the submitted data array would be organized as follows, if the CakePHP was installed on a Windows server. ‘tmp_name’ will have a different path in a Unix environment:

$this->request->data['Document']['submittedfile'] = array(
    'name' => 'conference_schedule.pdf',
    'type' => 'application/pdf',
    'tmp_name' => 'C:/WINDOWS/TEMP/php1EE.tmp',
    'error' => 0,
    'size' => 41737,
);

This array is generated by PHP itself, so for more detail on the way PHP handles data passed via file fields read the PHP manual section on file uploads.

public function isUploadedFile($params) {
    $val = array_shift($params);
    if ((isset($val['error']) && $val['error'] == 0) ||
        (!empty( $val['tmp_name']) && $val['tmp_name'] != 'none')
    ) {
        return is_uploaded_file($val['tmp_name']);
    }
    return false;
}

echo $this->Form->create('User', array('type' => 'file'));
echo $this->Form->file('avatar');

<form enctype="multipart/form-data" method="post" action="/users/add">
<input name="data[User][avatar]" value="" id="UserAvatar" type="file">

Creating buttons and submit elements¶

FormHelper::submit(string $caption, array $options)¶

Creates a submit button with caption $caption. If the supplied $caption is a URL to an image (it contains a ‘.’ character), the submit button will be rendered as an image.

It is enclosed between div tags by default; you can avoid this by declaring $options['div'] = false:

echo $this->Form->submit();

Will output:

<div class="submit"><input value="Submit" type="submit"></div>

You can also pass a relative or absolute URL to an image for the caption parameter instead of caption text.

echo $this->Form->submit('ok.png');

Will output:

<div class="submit"><input type="image" src="/img/ok.png"></div>

FormHelper::button(string $title, array $options = array())¶

Creates an HTML button with the specified title and a default type of “button”. Setting $options['type'] will output one of the three possible button types:

1. submit: Same as the $this->Form->submit method - (the default).

2. reset: Creates a form reset button.

3. button: Creates a standard push button.

echo $this->Form->button('A Button');
echo $this->Form->button('Another Button', array('type' => 'button'));
echo $this->Form->button('Reset the Form', array('type' => 'reset'));
echo $this->Form->button('Submit Form', array('type' => 'submit'));

Will output:

<button type="submit">A Button</button>
<button type="button">Another Button</button>
<button type="reset">Reset the Form</button>
<button type="submit">Submit Form</button>

The button input type supports the escape option, which accepts a bool and determines whether to HTML entity encode the $title of the button. Defaults to false:

echo $this->Form->button('Submit Form', array(
    'type' => 'submit',
    'escape' => true
));

FormHelper::postButton(string $title, mixed $url, array $options = array ())¶

Create a <button> tag with a surrounding <form> that submits via POST.

This method creates a <form> element. So do not use this method in some opened form. Instead use FormHelper::submit() or FormHelper::button() to create buttons inside opened forms.

FormHelper::postLink(string $title, mixed $url = null, array $options = array ())¶

Creates an HTML link, but access the URL using method POST. Requires JavaScript to be enabled in browser.

This method creates a <form> element. If you want to use this method inside of an existing form, you must use the inline or block options so that the new form can be rendered outside of the existing form.

If all you are looking for is a button to submit your form, then you should use FormHelper::submit() instead.

Changed in version 2.3: The method option was added.

Changed in version 2.5: The inline and block options were added. They allow buffering the generated form tag, instead of returning with the link. This helps avoiding nested form tags. Setting 'inline' => false will add the form tag to the postLink content block, if you want to use a custom block you can specify it using the block option instead.

Changed in version 2.6: The argument $confirmMessage was deprecated. Use confirm key in $options instead.

Creating date and time inputs¶

FormHelper::dateTime($fieldName, $dateFormat = 'DMY', $timeFormat = '12', $attributes = array())¶

Creates a set of select inputs for date and time. Valid values for $dateformat are ‘DMY’, ‘MDY’, ‘YMD’ or ‘NONE’. Valid values for $timeFormat are ‘12’, ‘24’, and null.

You can specify not to display empty values by setting “array(‘empty’ => false)” in the attributes parameter. It will also pre-select the fields with the current datetime.

FormHelper::year(string $fieldName, int $minYear, int $maxYear, array $attributes)¶

Creates a select element populated with the years from $minYear to $maxYear. HTML attributes may be supplied in $attributes. If $attributes['empty'] is false, the select will not include an empty option:

echo $this->Form->year('purchased', 2000, date('Y'));

Will output:

<select name="data[User][purchased][year]" id="UserPurchasedYear">
<option value=""></option>
<option value="2009">2009</option>
<option value="2008">2008</option>
<option value="2007">2007</option>
<option value="2006">2006</option>
<option value="2005">2005</option>
<option value="2004">2004</option>
<option value="2003">2003</option>
<option value="2002">2002</option>
<option value="2001">2001</option>
<option value="2000">2000</option>
</select>

FormHelper::month(string $fieldName, array $attributes)¶

Creates a select element populated with month names:

echo $this->Form->month('mob');

Will output:

<select name="data[User][mob][month]" id="UserMobMonth">
<option value=""></option>
<option value="01">January</option>
<option value="02">February</option>
<option value="03">March</option>
<option value="04">April</option>
<option value="05">May</option>
<option value="06">June</option>
<option value="07">July</option>
<option value="08">August</option>
<option value="09">September</option>
<option value="10">October</option>
<option value="11">November</option>
<option value="12">December</option>
</select>

You can pass in your own array of months to be used by setting the ‘monthNames’ attribute, or have months displayed as numbers by passing false. (Note: the default months are internationalized and can be translated using localization.):

echo $this->Form->month('mob', array('monthNames' => false));

FormHelper::day(string $fieldName, array $attributes)¶

Creates a select element populated with the (numerical) days of the month.

To create an empty option with prompt text of your choosing (e.g. the first option is ‘Day’), you can supply the text as the final parameter as follows:

echo $this->Form->day('created');

Will output:

<select name="data[User][created][day]" id="UserCreatedDay">
<option value=""></option>
<option value="01">1</option>
<option value="02">2</option>
<option value="03">3</option>
...
<option value="31">31</option>
</select>

FormHelper::hour(string $fieldName, boolean $format24Hours, array $attributes)¶

Creates a select element populated with the hours of the day.

FormHelper::minute(string $fieldName, array $attributes)¶

Creates a select element populated with the minutes of the hour.

FormHelper::meridian(string $fieldName, array $attributes)¶

Creates a select element populated with ‘am’ and ‘pm’.

Displaying and checking errors¶

FormHelper::error(string $fieldName, mixed $text, array $options)¶

Shows a validation error message, specified by $text, for the given field, in the event that a validation error has occurred.

Options:

• ‘escape’ bool Whether or not to HTML escape the contents of the error.

• ‘wrap’ mixed Whether or not the error message should be wrapped in a div. If a string, will be used as the HTML tag to use.

• ‘class’ string The class name for the error message

FormHelper::isFieldError(string $fieldName)¶

Returns true if the supplied $fieldName has an active validation error.

if ($this->Form->isFieldError('gender')) {
    echo $this->Form->error('gender');
}

Note

When using FormHelper::input(), errors are rendered by default.

FormHelper::tagIsInvalid()¶

Returns false if given form field described by the current entity has no errors. Otherwise it returns the validation message.

Setting Defaults for all fields¶

You can declare a set of default options for input() using FormHelper::inputDefaults(). Changing the default options allows you to consolidate repeated options into a single method call:

$this->Form->inputDefaults(array(
        'label' => false,
        'div' => false,
        'class' => 'fancy'
    )
);

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

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

Working with SecurityComponent¶

SecurityComponent offers several features that make your forms safer and more secure. By simply including the SecurityComponent in your controller, you’ll automatically benefit from CSRF and form tampering features.

As mentioned previously when using SecurityComponent, you should always close your forms using FormHelper::end(). This will ensure that the special _Token inputs are generated.

FormHelper::unlockField($name)¶

Unlocks a field making it exempt from the SecurityComponent field hashing. This also allows the fields to be manipulated by JavaScript. The $name parameter should be the entity name for the input:

$this->Form->unlockField('User.id');

FormHelper::secure(array $fields = array())¶

Generates a hidden field with a security hash based on the fields used in the form.

2.0 updates¶

$selected parameter removed

The $selected parameter was removed from several methods in FormHelper. All methods now support a $attributes['value'] key now which should be used in place of $selected. This change simplifies the FormHelper methods, reducing the number of arguments, and reduces the duplication that $selected created. The effected methods are:

• FormHelper::select()

• FormHelper::dateTime()

• FormHelper::year()

• FormHelper::month()

• FormHelper::day()

• FormHelper::hour()

• FormHelper::minute()

• FormHelper::meridian()

Default URLs on forms is the current action

The default URL for all forms, is now the current URL including passed, named, and querystring parameters. You can override this default by supplying $options['url'] in the second parameter of $this->Form->create()

FormHelper::hidden()

Hidden fields no longer remove the class attribute. This means that if there are validation errors on hidden fields, the error-field class name will be applied.