CakePHP 3.5 Cookbook Documentation

Common

Options for Date & Time Controls

Options for Time-Related Controls

HTML attributes.

Creates, by default, three select pickers populated with values for: year (4 digits), month (full English name) and day

(numeric), respectively.

You can further control the generated select elements by providing additional options.

For example:

// 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

'empty' => [

'year' =>

false

'month' => 'Choose month...'

'day' =>

false

'year' => [

'class' => 'cool-years' ,

'title' => 'Registration Year'

]

]);

Output:

select

class = "cool-years" name = "registered[year]" title = "Registration Year" >

option

value = "2022" >2022</

option

value = "2021" >2021</

option

...

option

value = "2018" >2018</

option

select

name = "registered[month]" >

option

value = "" selected = "selected" >Choose month...</

option

value = "01" >1</

option

...

option

value = "12" >12</

option

select

Creating Time Controls

Cake\View\Helper\FormHelper::time(

$fieldName , $options = [])

• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select elements.

• $options - An optional array including any of the

Common Options For Specific Controls

Common

Options for Date & Time Controls

Options for Time-Related Controls

HTML attributes.

Creates, by default, two select elements (hour and minute) populated with values for 24 hours and 60 minutes, respectively. Additionally, HTML attributes may be supplied in $options for each specific component. If

More About Views 309

CakePHP Cookbook Documentation, Release 3.5

$options['empty'] is false, the select picker will not include an empty default option.

For example, to create a time range with minutes selectable in 15 minute increments, and to apply classes to the select boxes, you could do the following:

echo

$this -> Form -> time ( 'released' , [

'interval' => 15 ,

'hour' => [

'class' => 'foo-class' ,

'minute' => [

'class' => 'bar-class' ,

]);

Which would create the following two select pickers:

select

name = "released[hour]" class = "foo-class" >

option

value = "" selected = "selected" ></

option

value = "00" >0</

option

value = "01" >1</

option

option

value = "22" >22</

option

value = "23" >23</

option

select

name = "released[minute]" class = "bar-class" >

option

value = "" selected = "selected" ></

option

value = "00" >00</

option

value = "15" >15</

option

value = "30" >30</

option

value = "45" >45</

option

select

Creating Year Controls

Cake\View\Helper\FormHelper::year( string $fieldName , array $options = [])

• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.

• $options - An optional array including any of the

Common Options For Specific Controls

Common

Options for Date & Time Controls

Options for Date-Related Controls

HTML attributes.

Creates a select element populated with the years from minYear to maxYear (when these options are provided) or else with values starting from -5 years to +5 years counted from today. Additionally, HTML attributes may be supplied in $options. If $options['empty'] is false, the select picker will not include an empty item in the list.

For example, to create a year range from 2000 to the current year you would do the following:

echo

$this -> Form -> year ( 'purchased' , [

'minYear' => 2000 ,

'maxYear' => date ( 'Y' )

]);

If it was 2009, you would get the following:

310 Chapter 11. Views

CakePHP Cookbook Documentation, Release 3.5

select

name = "purchased[year]" >

option

value = "" ></

option

value = "2009" >2009</

option

value = "2008" >2008</

option

value = "2007" >2007</

option

value = "2006" >2006</

option

value = "2005" >2005</

option

value = "2004" >2004</

option

value = "2003" >2003</

option

value = "2002" >2002</

option

value = "2001" >2001</

option

value = "2000" >2000</

option

select

Creating Month Controls

Cake\View\Helper\FormHelper::month( string $fieldName , array $attributes)

• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.

• $attributes - An optional array including any of the

Common Options For Specific Controls

Common

Options for Date & Time Controls

Options for Date-Related Controls

HTML attributes.

Creates a select element populated with month names.

For example:

echo

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

Will output:

select

name = "mob[month]" >

option

value = "" ></

option

value = "01" >January</

option

value = "02" >February</

option

value = "03" >March</

option

value = "04" >April</

option

value = "05" >May</

option

value = "06" >June</

option

value = "07" >July</

option

value = "08" >August</

option

value = "09" >September</

option

value = "10" >October</

option

value = "11" >November</

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.

E.g.

echo

$this -> Form -> month ( 'mob' , [ 'monthNames' =>

false

]);

Note: The default months can be localized with CakePHP

Internationalization & Localization

features.

More About Views 311

CakePHP Cookbook Documentation, Release 3.5

Creating Day Controls

Cake\View\Helper\FormHelper::day( string $fieldName , array $attributes)

• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.

• $attributes - An optional array including any of the

Common Options For Specific Controls

Common

Options for Date & Time Controls

Options for Date-Related Controls

HTML attributes.

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

To create an empty option element with a prompt text of your choosing (e.g. the first option is ‘Day’), you can supply the text in the 'empty' parameter.

For example:

echo

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

Will output:

select

name = "created[day]" >

option

value = "" selected = "selected" >Day</

option

value = "01" >1</

option

value = "02" >2</

option

value = "03" >3</

option

...

option

value = "31" >31</

option

select

Creating Hour Controls

Cake\View\Helper\FormHelper::hour( string $fieldName , array $attributes)

• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.

• $attributes - An optional array including any of the

Common Options For Specific Controls

Common

Options for Date & Time Controls

Options for Time-Related Controls

HTML attributes.

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

You can create either 12 or 24 hour pickers using the 'format' option:

echo

$this -> Form -> hour ( 'created' , [

'format' => 12

]);

echo

$this -> Form -> hour ( 'created' , [

'format' => 24

]);

Creating Minute Controls

Cake\View\Helper\FormHelper::minute( string $fieldName , array $attributes)

• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.

312 Chapter 11. Views

CakePHP Cookbook Documentation, Release 3.5

• $attributes - An optional array including any of the

Common Options For Specific Controls

Common

Options for Date & Time Controls

Options for Time-Related Controls

, errors are rendered by default, so you don’t

HTML attributes.

Creates a select element populated with values for the minutes of the hour. You can create a select picker that only contains specific values by using the 'interval' option.

For example, if you wanted 10 minutes increments you would do the following:

// In your view template file

echo

$this -> Form -> minute ( 'arrival' , [

'interval' => 10

]);

This would output:

select

name = "arrival[minute]" >

option

value = "" selected = "selected" ></

option

value = "00" >00</

option

value = "10" >10</

option

value = "20" >20</

option

value = "30" >30</

option

value = "40" >40</

option

value = "50" >50</

option

select

Creating Meridian Controls

Cake\View\Helper\FormHelper::meridian( string $fieldName , array $attributes)

• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.

• $attributes - An optional array including any of the

Common Options For Specific Controls

as well as any valid HTML attributes.

Creates a select element populated with ‘am’ and ‘pm’. This is useful when the hour format is set to 12 instead of

, as it allows to specify the period of the day to which the hour belongs.

Creating Labels

Cake\View\Helper\FormHelper::label( string $fieldName , string $text, array $options)

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

• $text - An optional string providing the label caption text.

• $options - Optional. String or an array containing any of the

Common Options For Specific Controls

as well as any valid HTML attributes.

Creates a label element. The argument $fieldName is used for generating the HTML for attribute of the element; if $text is undefined, $fieldName will also be used to inflect the label’s text attribute.

E.g.

echo

$this -> Form -> label ( 'User.name' );

echo

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

Output:

More About Views 313

CakePHP Cookbook Documentation, Release 3.5

label

for = "user-name" >Name</

label

for = "user-name" >Your username</

label

When you set $options to a string it will be used as a class name:

echo

$this -> Form -> label ( 'User.name' ,

null

, [ 'id' => 'user-label' ]);

echo

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

Output:

label

for = "user-name" id = "user-label" >Name</

label

for = "user-name" class = "highlight" >Your username</

label

Displaying and Checking Errors

FormHelper exposes a couple of methods that allow us to easily check for field errors and when necessary display customized error messages.

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' );

( $this -> Form -> isFieldError ( 'ticket' )) {

echo

$this -> Form -> error ( 'ticket' , 'Completely custom error message!' );

}

314 Chapter 11. Views

CakePHP Cookbook Documentation, Release 3.5

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

Note: When using

View\Helper\FormHelper::control()

need to use isFieldError() or call error() manually.

Tip: If you use a certain model field to generate multiple form fields via control(), and you want the same validation error message displayed for each one, you will probably be better off defining a custom error message inside the respective

validator rules

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:

( $this -> Form -> isFieldError ( 'gender' )) {

echo

$this -> Form -> error ( 'gender' );

}

Creating Buttons and Submit Elements

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

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

More About Views 315

CakePHP Cookbook Documentation, Release 3.5

• '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

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:

316 Chapter 11. Views

CakePHP Cookbook Documentation, Release 3.5

button

type = "submit" >A Button</

button

type = "button" >Another Button</

button

type = "reset" >Reset the Form</

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

]);

Closing the Form

Cake\View\Helper\FormHelper::end(

$secureAttributes = [])

• $secureAttributes - Optional. Allows you to provide secure attributes which will be passed as HTML attributes into the hidden input elements generated for the SecurityComponent.

The end() method closes and completes a form.

Often, end() will only output a closing form tag, but using end() is a good practice as it enables FormHelper to insert the hidden form elements that

Cake\Controller\Component\SecurityComponent requires:

= $this -> Form -> create (); ?>

= $this -> Form -> end (); ?>

If you need to add additional attributes to the generated hidden inputs you can use the $secureAttributes argument.

E.g.

echo

$this -> Form -> end ([ 'data-type' => 'hidden' ]);

Will output:

div

style = "display:none;" >

input

type = "hidden" name = "_Token[fields]" data-type = "hidden" value = "2981c38990f3f6ba935e6561dc77277966fabd6d%3AAddresses.id" >

input

type = "hidden" name = "_Token[unlocked]" data-type = "hidden" value = "address%7Cfirst_name" >

div

Note: If you are using Cake\Controller\Component\SecurityComponent in your application you should always end your forms with end().

More About Views 317

CakePHP Cookbook Documentation, Release 3.5

Creating Standalone Buttons and POST Links

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

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()

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.

318 Chapter 11. Views

CakePHP Cookbook Documentation, Release 3.5

• $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