Class FormHelper
Form helper library.
Automatic generation of HTML FORMs from given data.
- AppHelper
-
FormHelper
Copyright: Copyright 2005-2012, Cake Software Foundation, Inc. (http://cakefoundation.org)
License: The MIT License
Location: view/helpers/form.php
Properties summary
-
$__optionspublicarrayOptions used by DateTime fields -
$fieldspublicarrayList of fields created, used with secure forms. -
$fieldsetpublicarrayHolds the fields array('field_name' => array('type'=> 'string', 'length'=> 100), primaryKey and validates array('field_name')
-
$helperspublicarrayOther helpers used by FormHelper -
$requestTypepublicstringDefines the type of form being created. Set by FormHelper::create().
Method Summary
-
__generateOptions() public
Generates option lists for common menus -
__name() public
Gets the input field name for the current tag -
__secure() public
Determine which fields of a form should be used for hash -
__selectOptions() public
Returns an array of formatted OPTION/OPTGROUP elements -
_initInputField() public
Sets field defaults and adds field to form security input hash -
button() public
Creates a button tag. -
checkbox() public
Creates a checkbox input widget. -
create() public
Returns an HTML FORM element. -
dateTime() public
Returns a set of SELECT elements for a full datetime setup: day, month and year, and then time. -
day() public
Returns a SELECT element for days. -
end() public
Closes an HTML form, cleans up values set by FormHelper::create(), and writes hidden input fields where appropriate.
-
error() public
Returns a formatted error message for given FORM field, NULL if no errors. -
file() public
Creates file input widget. -
hidden() public
Creates a hidden input field. -
hour() public
Returns a SELECT element for hours. -
input() public
Generates a form input element complete with label and wrapper div -
inputs() public
Generate a set of inputs for
$fields. If $fields is null the current model will be used. -
isFieldError() public
Returns true if there is an error for the given field, otherwise false -
label() public
Returns a formatted LABEL element for HTML FORMs. -
meridian() public
Returns a SELECT element for AM or PM. -
minute() public
Returns a SELECT element for minutes. -
month() public
Returns a SELECT element for months. -
password() public
Creates a password input widget. -
radio() public
Creates a set of radio widgets. -
secure() public
Generates a hidden field with a security hash based on the fields used in the form. -
select() public
Returns a formatted SELECT element. -
submit() public
Creates a submit button element. -
text() public
Creates a text input widget. -
textarea() public
Creates a textarea widget. -
year() public
Returns a SELECT element for years
Method Detail
__generateOptions() public ¶
__generateOptions( $name , $options = array() )
Generates option lists for common menus
__name() public ¶
__name( array $options = array() , string $field = null , $key = 'name' )
Gets the input field name for the current tag
Parameters
- array $options optional array()
- string $field optional null
- $key
- $key optional 'name'
Returns
__secure() public ¶
__secure( mixed $field = null , mixed $value = null )
Determine which fields of a form should be used for hash
Parameters
- mixed $field optional null
- Reference to field to be secured
- mixed $value optional null
- Field value, if value should not be tampered with
__selectOptions() public ¶
__selectOptions( $elements = array() , $selected = null , $parents = array() , $showParents = null , $attributes = array() )
Returns an array of formatted OPTION/OPTGROUP elements
Returns
_initInputField() public ¶
_initInputField( string $field , array $options = array() )
Sets field defaults and adds field to form security input hash
Options - secure - boolean whether or not the the field should be added to the security fields.
Parameters
- string $field
- array $options optional array()
Returns
button() public ¶
button( string $title , array $options = array() )
Creates a button tag.
Parameters
- string $title
- The button's caption
- array $options optional array()
- Array of options.
Returns
A HTML button tag.
checkbox() public ¶
checkbox( string $fieldName , array $options = array() )
Creates a checkbox input widget.
Options:
- 'value' - the value of the checkbox
- checked' - boolean indicate that this checkbox is checked.
Parameters
- string $fieldName
- Name of a field, like this "Modelname.fieldname"
- array $options optional array()
- Array of HTML attributes.
Returns
An HTML text input element
create() public ¶
create( string $model = null , array $options = array() )
Returns an HTML FORM element.
Options:
- 'type' Form method defaults to POST
- 'action' The Action the form submits to. Can be a string or array,
- 'url' The url the form submits to. Can be a string or a url array,
- 'default' Allows for the creation of Ajax forms.
- 'onsubmit' Used in conjunction with 'default' to create ajax forms.
Parameters
- string $model optional null
- The model object which the form is being defined for
- array $options optional array()
- An array of html attributes and options.
Returns
An formatted opening FORM tag.
dateTime() public ¶
dateTime( string $fieldName , string $dateFormat = 'DMY' , string $timeFormat = '12' , string $selected = null , string $attributes = array() , boolean $showEmpty = true )
Returns a set of SELECT elements for a full datetime setup: day, month and year, and then time.
Attributes:
- 'monthNames' If set and false numbers will be used for month select instead of text.
- 'minYear' The lowest year to use in the year select
- 'maxYear' The maximum year to use in the year select
- 'interval' The interval for the minutes select. Defaults to 1
- 'separator' The contents of the string between select elements. Defaults to '-'
Parameters
- string $fieldName
- Prefix name for the SELECT element
- string $dateFormat optional 'DMY'
- DMY, MDY, YMD or NONE.
- string $timeFormat optional '12'
- 12, 24, NONE
- string $selected optional null
- Option which is selected.
- string $attributes optional array()
- array of Attributes
- boolean $showEmpty optional true
- Whether or not to show an empty default value.
Returns
The HTML formatted OPTION element
day() public ¶
day( string $fieldName , string $selected = null , array $attributes = array() , mixed $showEmpty = true )
Returns a SELECT element for days.
Parameters
- string $fieldName
- Prefix name for the SELECT element
- string $selected optional null
- Option which is selected.
- array $attributes optional array()
- HTML attributes for the select element
- mixed $showEmpty optional true
- Show/hide the empty select option
Returns
end() public ¶
end( mixed $options = null )
Closes an HTML form, cleans up values set by FormHelper::create(), and writes hidden input fields where appropriate.
If $options is set a form submit button will be created.
Parameters
- mixed $options optional null
as a string will use $options as the value of button, array usage: array('label' => 'save'); value="save" array('label' => 'save', 'name' => 'Whatever'); value="save" name="Whatever" array('name' => 'Whatever'); value="Submit" name="Whatever" array('label' => 'save', 'name' => 'Whatever', 'div' => 'good')
<
div class="good"> value="save" name="Whatever" array('label' => 'save', 'name' => 'Whatever', 'div' => array('class' => 'good'));
<
div class="good"> value="save" name="Whatever"
Returns
a closing FORM tag optional submit button.
error() public ¶
error( string $field , mixed $text = null , array $options = array() )
Returns a formatted error message for given FORM field, NULL if no errors.
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 classname for the error message
Parameters
- string $field
- A field name, like "Modelname.fieldname"
- mixed $text optional null
- Error message or array of $options
- array $options optional array()
Rendering options for
wrapper tag
Returns
If there are errors this method returns an error message, otherwise null.
file() public ¶
file( string $fieldName , array $options = array() )
Creates file input widget.
Parameters
- string $fieldName
- Name of a field, in the form "Modelname.fieldname"
- array $options optional array()
- Array of HTML attributes.
Returns
hidden() public ¶
hidden( string $fieldName , array $options = array() )
Creates a hidden input field.
Parameters
- string $fieldName
- Name of a field, in the form"Modelname.fieldname"
- array $options optional array()
- Array of HTML attributes.
Returns
hour() public ¶
hour( string $fieldName , boolean $format24Hours = false , string $selected = null , array $attributes = array() , mixed $showEmpty = true )
Returns a SELECT element for hours.
Parameters
- string $fieldName
- Prefix name for the SELECT element
- boolean $format24Hours optional false
- True for 24 hours format
- string $selected optional null
- Option which is selected.
- array $attributes optional array()
- List of HTML attributes
- mixed $showEmpty optional true
- True to show an empty element, or a string to provide default empty element text
Returns
input() public ¶
input( string $fieldName , array $options = array() )
Generates a form input element complete with label and wrapper div
Options - See each field type method for more information. Any options that are part of $attributes or $options for the different type methods can be included in $options for input().
- 'type' - Force the type of widget you want. e.g.
type => 'select' - 'label' - control the label
- 'div' - control the wrapping div element
- 'options' - for widgets that take options e.g. radio, select
- 'error' - control the error message that is produced
Parameters
- string $fieldName
- This should be "Modelname.fieldname"
- array $options optional array()
- Each type of input takes different options.
Returns
Completed form widget
inputs() public ¶
inputs( mixed $fields = null , array $blacklist = null )
Generate a set of inputs for $fields. If $fields is null 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.
$form->inputs(array('legend' => 'My legend')); Would generate an input set with
a custom legend. You can customize individual inputs through $fields as well.
{{{ $form->inputs(array( 'name' => array('label' => 'custom label') )); }}}
Parameters
- mixed $fields optional null
- An array of fields to generate inputs for, or null.
- array $blacklist optional null
- a simple array of fields to skip.
Returns
Completed form inputs.
isFieldError() public ¶
isFieldError( string $field )
Returns true if there is an error for the given field, otherwise false
Parameters
- string $field
- This should be "Modelname.fieldname"
Returns
If there are errors this method returns true, else false.
label() public ¶
label( string $fieldName = null , string $text = null , array $attributes = array() )
Returns a formatted LABEL element for HTML FORMs.
Parameters
- string $fieldName optional null
- This should be "Modelname.fieldname"
- string $text optional null
- Text that will appear in the label field.
- array $attributes optional array()
- Array of HTML attributes.
Returns
The formatted LABEL element
meridian() public ¶
meridian( string $fieldName , string $selected = null , string $attributes = array() , boolean $showEmpty = true )
Returns a SELECT element for AM or PM.
Parameters
- string $fieldName
- Prefix name for the SELECT element
- string $selected optional null
- Option which is selected.
- string $attributes optional array()
- Array of Attributes
- boolean $showEmpty optional true
- Show/Hide an empty option
Returns
minute() public ¶
minute( string $fieldName , string $selected = null , string $attributes = array() , boolean $showEmpty = true )
Returns a SELECT element for minutes.
Parameters
- string $fieldName
- Prefix name for the SELECT element
- string $selected optional null
- Option which is selected.
- string $attributes optional array()
- Array of Attributes
- boolean $showEmpty optional true
- True to show an empty element, or a string to provide default empty element text
Returns
month() public ¶
month( string $fieldName , string $selected = null , array $attributes = array() , boolean $showEmpty = true )
Returns a SELECT element for months.
Attributes:
- 'monthNames' is set and false 2 digit numbers will be used instead of text.
Parameters
- string $fieldName
- Prefix name for the SELECT element
- string $selected optional null
- Option which is selected.
- array $attributes optional array()
- Attributes for the select element
- boolean $showEmpty optional true
- Show/hide the empty select option
Returns
password() public ¶
password( string $fieldName , array $options = array() )
Creates a password input widget.
Parameters
- string $fieldName
- Name of a field, like in the form "Modelname.fieldname"
- array $options optional array()
- Array of HTML attributes.
Returns
radio() public ¶
radio( string $fieldName , array $options = array() , array $attributes = array() )
Creates a set of radio widgets.
Attributes:
- 'separator' - define the string in between the radio buttons
- 'legend' - control whether or not the widget set has a fieldset & legend
- 'value' - indicate a value that is should be checked
- 'label' - boolean to indicate whether or not labels for widgets show be displayed
Parameters
- string $fieldName
- Name of a field, like this "Modelname.fieldname"
- array $options optional array()
- Radio button options array.
- array $attributes optional array()
- Array of HTML attributes.
Returns
secure() public ¶
secure( array $fields = array() )
Generates a hidden field with a security hash based on the fields used in the form.
Parameters
- array $fields optional array()
- The list of fields to use when generating the hash
Returns
A hidden input field with a security hash
select() public ¶
select( string $fieldName , array $options = array() , mixed $selected = null , array $attributes = array() , mixed $showEmpty = '' )
Returns a formatted SELECT element.
Attributes:
- 'showParents' - If included in the array and set to true, an additional option element will be added for the parent of each option group.
- 'multiple' - show a multiple select box. If set to 'checkbox' multiple checkboxes will be created instead.
Parameters
- string $fieldName
- Name attribute of the SELECT
- array $options optional array()
Array of the OPTION elements (as 'value'=>'Text' pairs) to be used in the SELECT element
- mixed $selected optional null
The option selected by default. If null, the default value from POST data will be used when available.
- array $attributes optional array()
- The HTML attributes of the select element.
- mixed $showEmpty optional ''
If true, the empty select option is shown. If a string, that string is displayed as the empty element.
Returns
Formatted SELECT element
submit() public ¶
submit( string $caption = null , array $options = array() )
Creates a submit button element.
Options
div- Include a wrapping div? Defaults to true. Accepts sub options similar to FormHelper::input().- Other attributes will be assigned to the input element.
Parameters
- string $caption optional null
The label appearing on the button OR if string contains :// or the extension .jpg, .jpe, .jpeg, .gif, .png use an image if the extension exists, AND the first character is /, image is relative to webroot, OR if the first character is not /, image is relative to webroot/img.
- array $options optional array()
- Array of options. See above.
Returns
A HTML submit button
text() public ¶
text( string $fieldName , array $options = array() )
Creates a text input widget.
Parameters
- string $fieldName
- Name of a field, in the form "Modelname.fieldname"
- array $options optional array()
- Array of HTML attributes.
Returns
An HTML text input element
textarea() public ¶
textarea( string $fieldName , array $options = array() )
Creates a textarea widget.
Parameters
- string $fieldName
- Name of a field, in the form "Modelname.fieldname"
- array $options optional array()
- Array of HTML attributes.
Returns
An HTML text input element
year() public ¶
year( string $fieldName , integer $minYear = null , integer $maxYear = null , string $selected = null , array $attributes = array() , boolean $showEmpty = true )
Returns a SELECT element for years
Parameters
- string $fieldName
- Prefix name for the SELECT element
- integer $minYear optional null
- First year in sequence
- integer $maxYear optional null
- Last year in sequence
- string $selected optional null
- Option which is selected.
- array $attributes optional array()
- Attribute array for the select elements.
- boolean $showEmpty optional true
- Show/hide the empty select option
Returns
Properties detail
$__options ¶
Options used by DateTime fields
array( 'day' => array(), 'minute' => array(), 'hour' => array(), 'month' => array(), 'year' => array(), 'meridian' => array() )
$fieldset ¶
Holds the fields array('field_name' => array('type'=> 'string', 'length'=> 100), primaryKey and validates array('field_name')
array('fields' => array(), 'key' => 'id', 'validates' => array())
$requestType ¶
Defines the type of form being created. Set by FormHelper::create().
null