Form¶

Options for Form Creation¶

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. Valid values:

• 'type' - Allows you to choose the type of form to create. If no type is provided then it will be autodetected based on the form context. Valid values:

  • 'get' - Will set the form method to HTTP GET.

  • 'file' - Will set the form method to POST and the 'enctype' to “multipart/form-data”.

  • 'post' - Will set the method to POST.

  • 'put', 'delete', 'patch' - Will override the HTTP method with PUT, DELETE or PATCH respectively, when the form is submitted.

• 'method' - Valid values are the same as above. Allows you to explicitly override the form’s method.

• 'url' - Specify the URL the form will submit to. Can be a string or a URL array.

• 'encoding' - Sets the accept-charset encoding for the form. Defaults to Configure::read('App.encoding').

• 'enctype' - Allows you to set the form encoding explicitly.

• 'templates' - The templates you want to use for this form. Any templates provided will be merged on top of the already loaded templates. Can be either a filename (without extension) from /config or an array of templates to use.

• 'context' - Additional options for the form context class. (For example the EntityContext accepts a 'table' option that allows you to set the specific Table class the form should be based on.)

• 'idPrefix' - Prefix for generated ID attributes.

• 'templateVars' - Allows you to provide template variables for the formStart template.

• autoSetCustomValidity - Set to true to use custom required and notBlank validation messages in the control’s HTML5 validity message. Default is false.

Getting form values from the query string¶

A FormHelper’s values sources define where its rendered elements, such as input-tags, receive their values from.

By default FormHelper draws its values from the ‘context’. The default contexts, such as EntityContext, will fetch data from the current entity, or from $request->getData().

If however, you are building a form that needs to read from the query string, you can use valueSource() to change where FormHelper reads data input data from:

// Prioritize query string over context:
echo $this->Form->create($article, [
    'valueSources' => ['query', 'context']
]);

// Same effect:
echo $this->Form
    ->setValueSources(['query', 'context'])
    ->create($articles);

// Only read data from the query string
echo $this->Form->create($article);
$this->Form->setValueSources('query');

// Same effect:
echo $this->Form->create($article, ['valueSources' => 'query']);

The supported sources are context, data and query. You can use one or more sources. Any widgets generated by FormHelper will gather their values from the sources, in the order you setup.

The value sources will be reset to the default (['context']) when end() is called.

Changing the HTTP Method for a Form¶

By using the type option you can change the HTTP method a form will use:

echo $this->Form->create($article, ['type' => 'get']);

Output:

<form method="get" action="/articles/edit/5">

Specifying a 'file' value for type, changes the form submission method to ‘post’, and includes an enctype of “multipart/form-data” on the form tag. This is to be used if there are any file elements inside the form. The absence of the proper enctype attribute will cause the file uploads not to function.

E.g.

echo $this->Form->create($article, ['type' => 'file']);

Output:

<form enctype="multipart/form-data" method="post" action="/articles/add">

When using 'put', 'patch' or 'delete' as 'type' values, your form will be functionally equivalent to a ‘post’ form, but when submitted, the HTTP request method will be overridden with ‘PUT’, ‘PATCH’ or ‘DELETE’, respectively. This allows CakePHP to emulate proper REST support in web browsers.

Setting a URL for the Form¶

Using the 'url' option allows you to point the form to a specific action in your current controller or another controller in your application.

For example, if you’d like to point the form to the publish() action of the current controller, you would supply an $options array, like the following:

echo $this->Form->create($article, ['url' => ['action' => 'publish']]);

Output:

<form method="post" action="/articles/publish">

If the desired form action isn’t in the current controller, you can specify a complete URL for the form action. The supplied URL can be relative to your CakePHP application:

echo $this->Form->create(null, [
    'url' => [
        'controller' => 'Articles',
        'action' => 'publish'
    ]
]);

Output:

<form method="post" action="/articles/publish">

Or you can point to an external domain:

echo $this->Form->create(null, [
    'url' => 'http://www.google.com/search',
    'type' => 'get'
]);

Output:

<form method="get" action="http://www.google.com/search">

Use 'url' => false if you don’t want to output a URL as the form action.

Using Custom Validators¶

Often models will have multiple validation sets, and you will want FormHelper to mark fields required based on a the specific validation rules your controller action is going to apply. For example, your Users table has specific validation rules that only apply when an account is being registered:

echo $this->Form->create($user, [
    'context' => ['validator' => 'register']
]);

The above will use the rules defined in the register validator, which are defined by UsersTable::validationRegister(), for $user and all related associations. If you are creating a form for associated entities, you can define validation rules for each association by using an array:

echo $this->Form->create($user, [
    'context' => [
        'validator' => [
            'Users' => 'register',
            'Comments' => 'default'
        ]
    ]
]);

The above would use register for the user, and default for the user’s comments.

Creating context classes¶

While the built-in context classes are intended to cover the basic cases you’ll encounter you may need to build a new context class if you are using a different ORM. In these situations you need to implement the Cake\View\Form\ContextInterface . Once you have implemented this interface you can wire your new context into the FormHelper. It is often best to do this in a View.beforeRender event listener, or in an application view class:

$this->Form->addContextProvider('myprovider', function ($request, $data) {
    if ($data['entity'] instanceof MyOrmClass) {
        return new MyProvider($request, $data);
    }
});

Context factory functions are where you can add logic for checking the form options for the correct type of entity. If matching input data is found you can return an object. If there is no match return null.

Field Naming Conventions¶

When creating control widgets you should name your fields after the matching attributes in the form’s entity. For example, if you created a form for an $article entity, you would create fields named after the properties. E.g. title, body and published.

You can create controls for associated models, or arbitrary models by passing in association.fieldname as the first parameter:

echo $this->Form->control('association.fieldname');

Any dots in your field names will be converted into nested request data. For example, if you created a field with a name 0.comments.body you would get a name attribute that looks like 0[comments][body]. This convention makes it easy to save data with the ORM. Details for the various association types can be found in the Creating Inputs for Associated Data section.

When creating datetime related controls, FormHelper will append a field-suffix. You may notice additional fields named year, month, day, hour, minute, or meridian being added. These fields will be automatically converted into DateTime objects when entities are marshalled.

Options for Control¶

FormHelper::control() supports a large number of options via its $options argument. In addition to its own options, control() accepts options for the inferred/chosen generated control types (e.g. for checkbox or textarea), as well as HTML attributes. This subsection will cover the options specific to FormHelper::control().

• $options['type'] - A string that specifies the widget type to be generated. In addition to the field types found in the Creating Form Controls, you can also create 'file', 'password', and any other type supported by HTML5. By specifying a 'type' you will force the type of the generated control, overriding model introspection. Defaults to null.

  E.g.

  echo $this->Form->control('field', ['type' => 'file']);
  echo $this->Form->control('email', ['type' => 'email']);
  

  Output:

  <div class="input file">
      <label for="field">Field</label>
      <input type="file" name="field" value="" id="field" />
  </div>
  <div class="input email">
      <label for="email">Email</label>
      <input type="email" name="email" value="" id="email" />
  </div>
  

• $options['label'] - Either a string caption or an array of options for the label. You can set this key to the string you would like to be displayed within the label that usually accompanies the input HTML element. Defaults to null.

  E.g.

  echo $this->Form->control('name', [
      'label' => 'The User Alias'
  ]);
  

  Output:

  <div class="input">
      <label for="name">The User Alias</label>
      <input name="name" type="text" value="" id="name" />
  </div>
  

  Alternatively, set this key to false to disable the generation of the label element.

  E.g.

  echo $this->Form->control('name', ['label' => false]);
  

  Output:

  <div class="input">
      <input name="name" type="text" value="" id="name" />
  </div>
  

  Set this to an array to provide additional options for the label element. If you do this, you can use a 'text' key in the array to customize the label text.

  E.g.

  echo $this->Form->control('name', [
      'label' => [
          'class' => 'thingy',
          'text' => 'The User Alias'
      ]
  ]);
  

  Output:

  <div class="input">
      <label for="name" class="thingy">The User Alias</label>
      <input name="name" type="text" value="" id="name" />
  </div>
  

• $options['options'] - You can provide in here an array containing the elements to be generated for widgets such as radio or select, which require an array of items as an argument (see Creating Radio Buttons and Creating Select Pickers for more details). Defaults to null.

• $options['error'] - Using this key allows you to override the default model error messages and can be used, for example, to set i18n messages. To disable the error message output & field classes set the 'error' key to false. Defaults to null.

  E.g.

  echo $this->Form->control('name', ['error' => false]);
  

  To override the model error messages use an array with the keys matching the original validation error messages.

  E.g.

  $this->Form->control('name', [
      'error' => ['Not long enough' => __('This is not long enough')]
  ]);
  

  As seen above you can set the error message for each validation rule you have in your models. In addition you can provide i18n messages for your forms.

• $options['nestedInput'] - Used with checkboxes and radio buttons. Controls whether the input element is generated inside or outside the label element. When control() generates a checkbox or a radio button, you can set this to false to force the generation of the HTML input element outside of the label element.

  On the other hand you can set this to true for any control type to force the generated input element inside the label. If you change this for radio buttons then you need to also modify the default radioWrapper template. Depending on the generated control type it defaults to true or false.

• $options['templates'] - The templates you want to use for this input. Any specified templates will be merged on top of the already loaded templates. This option can be either a filename (without extension) in /config that contains the templates you want to load, or an array of templates to use.

• $options['labelOptions'] - Set this to false to disable labels around nestedWidgets or set it to an array of attributes to be provided to the label tag.

Common Options For Specific Controls¶

Many of the various control element methods support a common set of options which, depending on the form method used, must be provided inside the $options or in the $attributes array argument. All of these options are also supported by the control() method. To reduce repetition, the common options shared by all control methods are as follows:

• 'id' - Set this key to force the value of the DOM id for the control. This will override the 'idPrefix' that may be set.

• 'default' - Used to set a default value for the control field. The value is used if the data passed to the form does not contain a value for the field (or if no data is passed at all). An explicit default value will override any default values defined in the schema.

  Example usage:

  echo $this->Form->text('ingredient', ['default' => 'Sugar']);
  

  Example with select field (size “Medium” will be selected as default):

  $sizes = ['s' => 'Small', 'm' => 'Medium', 'l' => 'Large'];
  echo $this->Form->select('size', $sizes, ['default' => 'm']);
  

  Note

  You cannot use default to check a checkbox - instead you might set the value in $this->request->getData() in your controller, or set the control option 'checked' to true.

  Beware of using false to assign a default value. A false value is used to disable/exclude options of a control field, so 'default' => false would not set any value at all. Instead use 'default' => 0.

• 'value' - Used to set a specific value for the control field. This will override any value that may else be injected from the context, such as Form, Entity or request->getData() etc.

  Note

  If you want to set a field to not render its value fetched from context or valuesSource you will need to set 'value' to '' (instead of setting it to null).

In addition to the above options, you can mixin any HTML attribute you wish to use. Any non-special option name will be treated as an HTML attribute, and applied to the generated HTML control element.

Creating Text Inputs¶

Cake\View\Helper\FormHelper::text(string $name, array $options)¶

• $name - A field name in the form 'Modelname.fieldname'.

• $options - An optional array including any of the Common Options For Specific Controls as well as any valid HTML attributes.

Creates a simple input HTML element of text type.

E.g.

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

Will output:

<input name="username" type="text" class="users">

Creating Password Inputs¶

Cake\View\Helper\FormHelper::password(string $fieldName, array $options)¶

• $fieldName - A field name in the form 'Modelname.fieldname'.

• $options - An optional array including any of the Common Options For Specific Controls as well as any valid HTML attributes.

Creates a simple input element of password type.

E.g.

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

Will output:

<input name="password" value="" type="password">

Creating Hidden Inputs¶

Cake\View\Helper\FormHelper::hidden(string $fieldName, array $options)¶

• $fieldName - A field name in the form 'Modelname.fieldname'.

• $options - An optional array including any of the Common Options For Specific Controls as well as any valid HTML attributes.

Creates a hidden form input.

E.g.

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

Will output:

<input name="id" type="hidden" />

Creating Textareas¶

Cake\View\Helper\FormHelper::textarea(string $fieldName, array $options)¶

• $fieldName - A field name in the form 'Modelname.fieldname'.

• $options - An optional array including any of the Common Options For Specific Controls, of the specific textarea options (see below) as well as any valid HTML attributes.

Creates a textarea control field. The default widget template used is:

'textarea' => '<textarea name="{{name}}"{{attrs}}>{{value}}</textarea>'

For example:

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

Will output:

<textarea name="notes"></textarea>

If the form is being edited (i.e. the array $this->request->getData() contains the information previously saved for the User entity), the value corresponding to notes field will automatically be added to the HTML generated.

Example:

<textarea name="notes" id="notes">
    This text is to be edited.
</textarea>

Options for Textarea

In addition to the Common Options For Specific Controls, textarea() supports a couple of specific options:

• 'escape' - Determines whether or not the contents of the textarea should be escaped. Defaults to true.

  E.g.

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

• 'rows', 'cols' - You can use these two keys to set the HTML attributes which specify the number of rows and columns for the textarea field.

  E.g.

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

  Output:

  <textarea name="comment" cols="5" rows="5">
  </textarea>
  

Creating Select, Checkbox and Radio Controls¶

These controls share some commonalities and a few options and thus, they are all grouped in this subsection for easier reference.

$options = $examples->combine('id', 'name');

$options = $examples->map(function ($value, $key) {
    return [
        'value' => $value->id,
        'text' => $value->name,
        'data-created' => $value->created
    ];
});

'checkbox' => '<input type="checkbox" name="{{name}}" value="{{value}}"{{attrs}}>'

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

<input type="hidden" name="done" value="0">
<input type="checkbox" name="done" value="1">

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

<input type="hidden" name="done" value="0">
<input type="checkbox" name="done" value="555">

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

<input type="checkbox" name="done" value="1">

'radio' => '<input type="radio" name="{{name}}" value="{{value}}"{{attrs}}>'
'radioWrapper' => '{{label}}'

$this->Form->radio('gender', ['Masculine', 'Feminine', 'Neuter']);

<input name="gender" value="" type="hidden">
<label for="gender-0">
    <input name="gender" value="0" id="gender-0" type="radio">
    Masculine
</label>
<label for="gender-1">
    <input name="gender" value="1" id="gender-1" type="radio">
    Feminine
</label>
<label for="gender-2">
    <input name="gender" value="2" id="gender-2" type="radio">
    Neuter
</label>

echo $this->Form->radio(
    'favorite_color',
    [
        ['value' => 'r', 'text' => 'Red', 'style' => 'color:red;'],
        ['value' => 'u', 'text' => 'Blue', 'style' => 'color:blue;'],
        ['value' => 'g', 'text' => 'Green', 'style' => 'color:green;'],
    ]
);

<input type="hidden" name="favorite_color" value="">
<label for="favorite-color-r">
    <input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite-color-r">
    Red
</label>
<label for="favorite-color-u">
    <input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite-color-u">
    Blue
</label>
<label for="favorite-color-g">
    <input type="radio" name="favorite_color" value="g" style="color:green;" id="favorite-color-g">
    Green
</label>

echo $this->Form->radio(
    'favorite_color',
    [
        ['value' => 'r', 'text' => 'Red', 'label' => ['class' => 'red']],
        ['value' => 'u', 'text' => 'Blue', 'label' => ['class' => 'blue']],
    ]
);

<input type="hidden" name="favorite_color" value="">
<label for="favorite-color-r" class="red">
    <input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite-color-r">
    Red
</label>
<label for="favorite-color-u" class="blue">
    <input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite-color-u">
    Blue
</label>

'select' => '<select name="{{name}}"{{attrs}}>{{content}}</select>'
'option' => '<option value="{{value}}"{{attrs}}>{{text}}</option>'

'optgroup' => '<optgroup label="{{label}}"{{attrs}}>{{content}}</optgroup>'
'selectMultiple' => '<select name="{{name}}[]" multiple="multiple"{{attrs}}>{{content}}</select>'

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

<select name="field">
    <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>

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

<select name="field">
    <option value="Value 1">Label 1</option>
    <option value="Value 2">Label 2</option>
    <option value="Value 3">Label 3</option>
</select>

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

<select name="field">
    <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>

$options = [
    ['text' => 'Description 1', 'value' => 'value 1', 'attr_name' => 'attr_value 1'],
    ['text' => 'Description 2', 'value' => 'value 2', 'attr_name' => 'attr_value 2'],
    ['text' => 'Description 3', 'value' => 'value 3', 'other_attr_name' => 'other_attr_value'],
];
echo $this->Form->select('field', $options);

<select name="field">
    <option value="value 1" attr_name="attr_value 1">Description 1</option>
    <option value="value 2" attr_name="attr_value 2">Description 2</option>
    <option value="value 3" other_attr_name="other_attr_value">Description 3</option>
</select>

Creating File Inputs¶

Cake\View\Helper\FormHelper::file(string $fieldName, array $options)¶

• $fieldName - A field name in the form 'Modelname.fieldname'.

• $options - An optional array including any of the Common Options For Specific Controls as well as any valid HTML attributes.

Creates a file upload field in the form. The widget template used by default is:

'file' => '<input type="file" name="{{name}}"{{attrs}}>'

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() method such as the following:

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

Next add a line that looks like either of the following two lines to your form’s view template file:

echo $this->Form->control('submittedfile', [
    'type' => 'file'
]);

// OR
echo $this->Form->file('submittedfile');

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 CakePHP was installed on a Windows server (the key 'tmp_name' will contain a different path in a Unix environment):

$this->request->data['submittedfile']

// would contain the following array:
[
    'name' => 'conference_schedule.pdf',
    'type' => 'application/pdf',
    'tmp_name' => 'C:/WINDOWS/TEMP/php1EE.tmp',
    'error' => 0, // On Windows this can be a string.
    '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.

Creating Date & Time Related Controls¶

The date and time related methods share a number of common traits and options and hence are grouped together into this subsection.

{{year}}{{month}}{{day}}{{hour}}{{minute}}{{second}}{{meridian}}

<?= $this->form->dateTime('registered') ?>

<select name="registered[year]">
    <option value="" selected="selected"></option>
    <option value="2022">2022</option>
    ...
    <option value="2012">2012</option>
</select>
<select name="registered[month]">
    <option value="" selected="selected"></option>
    <option value="01">January</option>
    ...
    <option value="12">December</option>
</select>
<select name="registered[day]">
    <option value="" selected="selected"></option>
    <option value="01">1</option>
    ...
    <option value="31">31</option>
</select>
<select name="registered[hour]">
    <option value="" selected="selected"></option>
    <option value="00">0</option>
    ...
    <option value="23">23</option>
</select>
<select name="registered[minute]">
    <option value="" selected="selected"></option>
    <option value="00">00</option>
    ...
    <option value="59">59</option>
</select>

echo $this->Form->dateTime('released', [
    'year' => [
        'class' => 'year-classname',
    ],
    'month' => [
        'class' => 'month-class',
        'data-type' => 'month',
    ],
]);

<select name="released[year]" class="year-class">
    <option value="" selected="selected"></option>
    <option value="00">0</option>
    <option value="01">1</option>
    <!-- .. snipped for brevity .. -->
</select>
<select name="released[month]" class="month-class" data-type="month">
    <option value="" selected="selected"></option>
    <option value="01">January</option>
    <!-- .. snipped for brevity .. -->
</select>

// Assuming current year is 2017; this disables day picker, removes empty
// option on year picker, limits lowest year, adds HTML attributes on year,
// adds a string 'empty' option on month, changes month to numeric
<?php
    echo $this->Form->date('registered', [
        'minYear' => 2018,
        'monthNames' => false, // Months are displayed as numbers
        'empty' => [
            'year' => false, // The year select control has no option for empty value
            'month' => 'Choose month...', // The month select control does, though
        ],
        'day' => false, // Do not show day select control
        'year' => [
            'class' => 'cool-years',
            'title' => 'Registration Year'
        ]
    ]);
?>

<select class= "cool-years" name="registered[year]" title="Registration Year">
    <option value="2022">2022</option>
    <option value="2021">2021</option>
    ...
    <option value="2018">2018</option>
</select>
<select name="registered[month]">
    <option value="" selected="selected">Choose month...</option>
    <option value="01">1</option>
    ...
    <option value="12">12</option>
</select>

echo $this->Form->time('released', [
    'interval' => 15,
    'hour' => [
        'class' => 'foo-class',
    ],
    'minute' => [
        'class' => 'bar-class',
    ],
]);

<select name="released[hour]" class="foo-class">
    <option value="" selected="selected"></option>
    <option value="00">0</option>
    <option value="01">1</option>
    <!-- .. snipped for brevity .. -->
    <option value="22">22</option>
    <option value="23">23</option>
</select>
<select name="released[minute]" class="bar-class">
    <option value="" selected="selected"></option>
    <option value="00">00</option>
    <option value="15">15</option>
    <option value="30">30</option>
    <option value="45">45</option>
</select>

echo $this->Form->year('purchased', [
    'minYear' => 2000,
    'maxYear' => date('Y')
]);

<select name="purchased[year]">
    <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>

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

<select name="mob[month]">
    <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>

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

echo $this->Form->day('created', ['empty' => 'Day']);

<select name="created[day]">
    <option value="" selected="selected">Day</option>
    <option value="01">1</option>
    <option value="02">2</option>
    <option value="03">3</option>
    ...
    <option value="31">31</option>
</select>

echo $this->Form->hour('created', [
    'format' => 12
]);
echo $this->Form->hour('created', [
    'format' => 24
]);

// In your view template file
echo $this->Form->minute('arrival', [
    'interval' => 10
]);

<select name="arrival[minute]">
    <option value="" selected="selected"></option>
    <option value="00">00</option>
    <option value="10">10</option>
    <option value="20">20</option>
    <option value="30">30</option>
    <option value="40">40</option>
    <option value="50">50</option>
</select>

Displaying Errors¶

Cake\View\Helper\FormHelper::error(string $fieldName, mixed $text, array $options)¶

• $fieldName - A field name in the form 'Modelname.fieldname'.

• $text - Optional. A string or array providing the error message(s). If an array, then it should be a hash of key names => messages. Defaults to null.

• $options - An optional array that can only contain a boolean with the key 'escape', which will define whether to HTML escape the contents of the error message. Defaults to true.

Shows a validation error message, specified by $text, for the given field, in the event that a validation error has occurred. If $text is not provided then the default validation error message for that field will be used.

Uses the following template widgets:

'error' => '<div class="error-message">{{content}}</div>'
'errorList' => '<ul>{{content}}</ul>'
'errorItem' => '<li>{{text}}</li>'

The 'errorList' and 'errorItem' templates are used to format mutiple error messages per field.

Example:

// If in TicketsTable you have a 'notEmpty' validation rule:
public function validationDefault(Validator $validator)
{
    $validator
        ->requirePresence('ticket', 'create')
        ->notEmpty('ticket');
}

// And inside Templates/Tickets/add.ctp you have:
echo $this->Form->text('ticket');

if ($this->Form->isFieldError('ticket')) {
    echo $this->Form->error('ticket', 'Completely custom error message!');
}

If you would click the Submit button of your form without providing a value for the Ticket field, your form would output:

<input name="ticket" class="form-error" required="required" value="" type="text">
<div class="error-message">Completely custom error message!</div>

Checking for Errors¶

Cake\View\Helper\FormHelper::isFieldError(string $fieldName)¶

• $fieldName - A field name in the form 'Modelname.fieldname'.

Returns true if the supplied $fieldName has an active validation error, otherwise returns false.

Example:

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

Displaying validation messages in HTML5 validity messages¶

If the autoSetCustomValidity FormHelper option is set to true, error messages for the field’s required and notBlank validation rules will be used in lieu of the default browser HTML5 required messages. Enabling the option will add the onvalid and oninvalid event attributes to your fields, for example:

<input type="text" name="field" required onvalid="this.setCustomValidity('')" oninvalid="this.setCustomValidity('Custom notBlank message')" />

If you want to manually set those events with custom JavaScript, you can set the autoSetCustomValidity option to false and use the special customValidityMessage template variable instead. This template variable is added when a field is required:

// example template
[
    'input' => '<input type="{{type}}" name="{{name}}" data-error-message="{{customValidityMessage}}" {{attrs}}/>',
]

// would create an input like this
<input type="text" name="field" required data-error-message="Custom notBlank message" />

You could then use JavaScript to set the onvalid and oninvalid events as you like.

Creating Submit Elements¶

Cake\View\Helper\FormHelper::submit(string $caption, array $options)¶

• $caption - An optional string providing the button’s text caption or a path to an image. Defaults to 'Submit'.

• $options - An optional array including any of the Common Options For Specific Controls, or of the specific submit options (see below) as well as any valid HTML attributes.

Creates an input element of submit type, with $caption as value. If the supplied $caption is a URL pointing to an image (i.e. if the string contains ‘://’ or contains any of the extensions ‘.jpg, .jpe, .jpeg, .gif’), an image submit button will be generated, using the specified image if it exists. If the first character is ‘/’ then the image path is relative to webroot, else if the first character is not ‘/’ then the image path is relative to webroot/img.

By default it will use the following widget templates:

'inputSubmit' => '<input type="{{type}}"{{attrs}}/>'
'submitContainer' => '<div class="submit">{{content}}</div>'

Options for Submit

• 'type' - Set this option to 'reset' in order to generate reset buttons. It defaults to 'submit'.

• 'templateVars' - Set this array to provide additional template variables for the input element and its container.

• Any other provided attributes will be assigned to the input element.

The following:

echo $this->Form->submit('Click me');

Will output:

<div class="submit"><input value="Click me" type="submit"></div>

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

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

Will output:

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

Submit inputs are useful when you only need basic text or images. If you need more complex button content you should use button().

Creating Button Elements¶

Cake\View\Helper\FormHelper::button(string $title, array $options = [])¶

• $title - Mandatory string providing the button’s text caption.

• $options - An optional array including any of the Common Options For Specific Controls, or of the specific button options (see below) as well as any valid HTML attributes.

Creates an HTML button with the specified title and a default type of 'button'.

Options for Button

• $options['type'] - You can set this to one of the following three possible values:

  1. 'submit' - Similarly to the $this->Form->submit() method it will create a submit button. However this won’t generate a wrapping div as submit() does. This is the default type.

  2. 'reset' - Creates a form reset button.

  3. 'button' - Creates a standard push button.

• $options['escape'] - Boolean. If set to true it will HTML encode the value provided inside $title. Defaults to false.

For example:

echo $this->Form->button('A Button');
echo $this->Form->button('Another Button', ['type' => 'button']);
echo $this->Form->button('Reset the Form', ['type' => 'reset']);
echo $this->Form->button('Submit Form', ['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>

Example of use of the 'escape' option:

// Will render escaped HTML.
echo $this->Form->button('<em>Submit Form</em>', [
    'type' => 'submit',
    'escape' => true
]);

Creating POST Buttons¶

Cake\View\Helper\FormHelper::postButton(string $title, mixed $url, array $options = [])¶

• $title - Mandatory string providing the button’s text caption. By default not HTML encoded.

• $url - The URL of the form provided as a string or as array.

• $options - An optional array including any of the Common Options For Specific Controls, or of the specific options (see below) as well as any valid HTML attributes.

Creates a <button> tag with a surrounding <form> element that submits via POST, by default. Also, by default, it generates hidden input fields for the SecurityComponent.

Options for POST Button

• 'data' - Array with key/value to pass in hidden input.

• 'method' - Request method to use. E.g. set to 'delete' to simulate a HTTP/1.1 DELETE request. Defaults to 'post'.

• 'form' - Array with any option that FormHelper::create() can take.

• Also, the postButton() method will accept the options which are valid for the button() method.

For example:

// In Templates/Tickets/index.ctp
<?= $this->Form->postButton('Delete Record', ['controller' => 'Tickets', 'action' => 'delete', 5]) ?>

Will output HTML similar to:

<form method="post" accept-charset="utf-8" action="/Rtools/tickets/delete/5">
    <div style="display:none;">
        <input name="_method" value="POST" type="hidden">
    </div>
    <button type="submit">Delete Record</button>
    <div style="display:none;">
        <input name="_Token[fields]" value="186cfbfc6f519622e19d1e688633c4028229081f%3A" type="hidden">
        <input name="_Token[unlocked]" value="" type="hidden">
        <input name="_Token[debug]" value="%5B%22%5C%2FRtools%5C%2Ftickets%5C%2Fdelete%5C%2F1%22%2C%5B%5D%2C%5B%5D%5D" type="hidden">
    </div>
</form>

Since this method generates a form element, do not use this method in an already opened form. Instead use Cake\View\Helper\FormHelper::submit() or Cake\View\Helper\FormHelper::button() to create buttons inside opened forms.

Creating POST Links¶

Cake\View\Helper\FormHelper::postLink(string $title, mixed $url = null, array $options = [])¶

• $title - Mandatory string providing the text to be wrapped in <a> tags.

• $url - Optional. String or array which contains the URL of the form (Cake-relative or external URL starting with http://).

• $options - An optional array including any of the Common Options For Specific Controls, or of the specific options (see below) as well as any valid HTML attributes.

Creates an HTML link, but accesses the URL using the method you specify (defaults to POST). Requires JavaScript to be enabled in browser:

// In your template, e.g. to delete an article
<?= $this->Form->postLink(
    'Delete',
    ['action' => 'delete', $article->id],
    ['confirm' => 'Are you sure?'])
?>

Options for POST Link

• 'data' - Array with key/value to pass in hidden input.

• 'method' - Request method to use. E.g. set to 'delete' to simulate a HTTP/1.1 DELETE request. Defaults to 'post'.

• 'confirm' - The confirmation message to display on click. Defaults to null.

• 'block' - Set this option to true to append the form to view block 'postLink' or provide a custom block name. Defaults to null.

• Also, the postLink method will accept the options which are valid for the link() method.

This method creates a <form> element. If you want to use this method inside of an existing form, you must use the block option so that the new form is being set to a view block that can be rendered outside of the main form.

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

List of Templates¶

The list of default templates, their default format and the variables they expect can be found in the FormHelper API documentation.

// Add custom radio wrapping HTML
$this->Form->setTemplates([
    'radioContainer' => '<div class="form-radio">{{content}}</div>'
]);

// Create a radio set with our custom wrapping div.
echo $this->Form->control('email_notifications', [
    'options' => ['y', 'n'],
    'type' => 'radio'
]);