Form Elements¶
Introduction¶
A set of specialized elements are provided for accomplishing application-centric tasks. These include several HTML5
input elements with matching server-side validators, the Csrf
element (to prevent Cross Site Request Forgery
attacks), and the Captcha
element (to display and validate CAPTCHAs).
A Factory
is provided to facilitate creation of elements, fieldsets, forms, and the related input filter. See
the Zend\Form Quick Start for more information.
Element Base Class¶
Zend\Form\Element
is a base class for all specialized elements and Zend\Form\Fieldset, but can also be used
for all generic text
, select
, radio
, etc. type form inputs which do not have a specialized element
available.
Basic Usage¶
At the bare minimum, each element or fieldset requires a name. You will also typically provide some attributes to hint to the view layer how it might render the item.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | use Zend\Form\Element;
use Zend\Form\Form;
$username = new Element('username');
$username
->setLabel('Username');
->setAttributes(array(
'type' => 'text',
'class' => 'username',
'size' => '30',
));
$password = new Element('password');
$password
->setLabel('Password');
->setAttributes(array(
'type' => 'password',
'size' => '30',
));
$form = new Form('my-form');
$form
->add($username)
->add($password);
|
Public Methods¶
-
setName
(string $name) Set the name for this element.
Returns
Zend\Form\Element
-
getName
() Return the name for this element.
Returns string
-
setLabel
(string $label) Set the label content for this element.
Returns
Zend\Form\Element
-
getLabel
() Return the label content for this element.
Returns string
-
setLabelAttributes
(array $labelAttributes) Set the attributes to use with the label.
Returns
Zend\Form\Element
-
getLabelAttributes
() Return the attributes to use with the label.
Returns array
-
setOptions
(array $options) Set options for an element. Accepted options are:
"label"
and"label_attributes"
, which callsetLabel
andsetLabelAttributes
, respectively.Returns
Zend\Form\Element
-
setAttribute
(string $key, mixed $value) Set a single element attribute.
Returns
Zend\Form\Element
-
getAttribute
(string $key) Retrieve a single element attribute.
Returns mixed
-
hasAttribute
(string $key) Check if a specific attribute exists for this element.
Returns boolean
-
setAttributes
(array|Traversable $arrayOrTraversable) Set many attributes at once. Implementation will decide if this will overwrite or merge.
Returns
Zend\Form\Element
-
getAttributes
() Retrieve all attributes at once.
Returns array|Traversable
-
clearAttributes
() Clear all attributes for this element.
Returns
Zend\Form\Element
-
setMessages
(array|Traversable $messages) Set a list of messages to report when validation fails.
Returns
Zend\Form\Element
-
getMessages
() Returns a list of validation failure messages, if any.
Returns array|Traversable
Captcha Element¶
Zend\Form\Element\Captcha
can be used with forms where authenticated users are not necessary, but you want to prevent
spam submissions. It is pairs with one of the Zend/Form/View/Helper/Captcha/*
view helpers that matches the
type of CAPTCHA adapter in use.
Basic Usage¶
A CAPTCHA adapter must be attached in order for validation to be included in the element’s input filter specification. See the section on Zend CAPTCHA Adapters for more information on what adapters are available.
1 2 3 4 5 6 7 8 9 10 11 | use Zend\Captcha;
use Zend\Form\Element;
use Zend\Form\Form;
$captcha = new Element\Captcha('captcha');
$captcha
->setCaptcha(new Captcha\Dumb())
->setLabel('Please verify you are human');
$form = new Form('my-form');
$form->add($captcha);
|
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element.
-
setCaptcha
(array|Zend\Captcha\AdapterInterface $captcha) Set the CAPTCHA adapter for this element. If
$captcha
is an array,Zend\Captcha\Factory::factory()
will be run to create the adapter from the array configuration.Returns
Zend\Form\Element\Captcha
-
getCaptcha
() Return the CAPTCHA adapter for this element.
Returns
Zend\Captcha\AdapterInterface
-
getInputSpecification
() Returns a input filter specification, which includes a
Zend\Filter\StringTrim
filter, and a CAPTCHA validator.Returns array
Checkbox Element¶
Zend\Form\Element\Checkbox
is meant to be paired with the Zend/Form/View/Helper/FormCheckbox
for HTML inputs with type checkbox. This element adds an InArray
validator to its input filter specification in order to validate on the server if the checkbox contains either the checked value or the unchecked value.
Basic Usage¶
This element automatically adds a "type"
attribute of value "checkbox"
.
1 2 3 4 5 6 7 8 9 10 11 | use Zend\Form\Element;
use Zend\Form\Form;
$checkbox = new Element\Checkbox('checkbox');
$checkbox->setLabel('A checkbox');
$checkbox->setUseHiddenElement(true);
$checkbox->setCheckedValue("good");
$checkbox->setUncheckedValue("bad");
$form = new Form('my-form');
$form->add($checkbox);
|
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element .
-
setOptions
(array $options) Set options for an element of type Checkbox. Accepted options, in addition to the inherited options of Zend\Form\Element <zend.form.element.methods.set-options>` , are:
"use_hidden_element"
,"checked_value"
and"unchecked_value"
, which callsetUseHiddenElement
,setCheckedValue
andsetUncheckedValue
, respectively.
-
setUseHiddenElement
(boolean $useHiddenElement) If set to true (which is default), the view helper will generate a hidden element that contains the unchecked value. Therefore, when using custom unchecked value, this option have to be set to true.
-
useHiddenElement
() Return if a hidden element is generated.
Return type: boolean
-
setCheckedValue
(string $checkedValue) Set the value to use when the checkbox is checked.
-
getCheckedValue
() Return the value used when the checkbox is checked.
Return type: string
-
setUncheckedValue
(string $uncheckedValue) Set the value to use when the checkbox is unchecked. For this to work, you must make sure that use_hidden_element is set to true.
-
getUncheckedValue
() Return the value used when the checkbox is unchecked.
Return type: string
-
getInputSpecification
() Returns a input filter specification, which includes a
Zend\Validator\InArray
to validate if the value is either checked value or unchecked value.Return type: array
Collection Element¶
Sometimes, you may want to add input (or a set of inputs) multiple times, either because you don’t want to duplicate code, or because you does not know in advance how many elements you need (in the case of elements dynamically added to a form using JavaScript, for instance).
Zend\Form\Element\Collection
is meant to be paired with the Zend\Form\View\Helper\FormCollection
.
Basic Usage¶
1 2 3 4 5 6 7 8 9 10 11 | use Zend\Form\Element;
use Zend\Form\Form;
$colors = new Element\Collection('collection');
$colors->setLabel('Colors');
$colors->setCount(2);
$colors->setTargetElement(new Element\Color());
$colors->setShouldCreateTemplate(true);
$form = new Form('my-form');
$form->add($colors);
|
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element .
-
setOptions
(array $options) Set options for an element of type Collection. Accepted options, in addition to the inherited options of Zend\Form\Element <zend.form.element.methods.set-options>` , are:
"target_element"
,"count"
,"allow_add"
,"should_create_template"
and"template_placeholder"
, which callsetTargetElement
,setCount
,setAllowAdd
,setShouldCreateTemplate
andsetTemplatePlaceholder
, respectively.
-
setCount
($count) Defines how many times the target element will be rendered by the
Zend/Form/View/Helper/FormCollection
view helper.
-
getCount
() Return the number of times the target element will be initially rendered by the
Zend/Form/View/Helper/FormCollection
view helper.
-
setTargetElement
($elementOrFieldset) This function either takes an
Zend/Form/ElementInterface
,Zend/Form/FieldsetInterface
instance or an array to pass to the form factory. When the Collection element will be validated, the input filter will be retrieved from this target element and be used to validate each element in the collection.
-
getTargetElement
() Return the target element used by the collection.
-
setAllowAdd
($allowAdd) If allowAdd is set to true (which is the default), new elements added dynamically in the form (using JavaScript, for instance) will also be validated and retrieved.
-
getAllowAdd
() Return if new elements can by dynamically added in the collection.
-
setShouldCreateTemplate
($shouldCreateTemplate) If shouldCreateTemplate is set to true (defaults to false), a <span> element will be generated by the
Zend/Form/View/Helper/FormCollection
view helper. This non-semantical span element contains a single data-template HTML5 attribute whose value is the whole HTML to copy to create a new element in the form. The template is indexed using thetemplatePlaceholder
value.
-
getAllowAdd
() Return if a template should be created.
-
setTemplatePlaceholder
($templatePlaceholder) Set the template placeholder (defaults to __index__) used to index element in the template.
-
getTemplatePlaceholder
() Returns the template placeholder used to index element in the template.
Color Element¶
Zend\Form\Element\Color
is meant to be paired with the Zend/Form/View/Helper/FormColor
for HTML5 inputs with
type color. This element adds filters and a Regex
validator to it’s input filter specification in order to
validate a HTML5 valid simple color value on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "color"
.
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
use Zend\Form\Form;
$color = new Element\Color('color');
$color->setLabel('Background color');
$form = new Form('my-form');
$form->add($color);
|
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element.
-
getInputSpecification
() Returns a input filter specification, which includes
Zend\Filter\StringTrim
andZend\Filter\StringToLower
filters, and aZend\Validator\Regex
to validate the RGB hex format.Returns array
Csrf Element¶
Zend\Form\Element\Csrf
pairs with the Zend/Form/View/Helper/FormHidden
to provide protection from CSRF attacks
on forms, ensuring the data is submitted by the user session that generated the form and not by a rogue script.
Protection is achieved by adding a hash element to a form and verifying it when the form is submitted.
Basic Usage¶
This element automatically adds a "type"
attribute of value "hidden"
.
1 2 3 4 5 6 7 | use Zend\Form\Element;
use Zend\Form\Form;
$csrf = new Element\Csrf('csrf');
$form = new Form('my-form');
$form->add($csrf);
|
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element.
-
getInputSpecification
() Returns a input filter specification, which includes a
Zend\Filter\StringTrim
filter and aZend\Validator\Csrf
to validate the CSRF value.Returns array
Date Element¶
Zend\Form\Element\Date
is meant to be paired with the Zend/Form/View/Helper/FormDate
for HTML5 inputs with type
date. This element adds filters and validators to it’s input filter specification in order to validate HTML5 date
input values on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "date"
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | use Zend\Form\Element;
use Zend\Form\Form;
$date = new Element\Date('appointment-date');
$date
->setLabel('Appointment Date')
->setAttributes(array(
'min' => '2012-01-01',
'max' => '2020-01-01',
'step' => '1', // days; default step interval is 1 day
));
$form = new Form('my-form');
$form->add($date);
|
Note
Note: the min
, max
, and step
attributes should be set prior to calling Zend\Form::prepare().
Otherwise, the default input specification for the element may not contain the correct validation rules.
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.
-
getInputSpecification
() Returns a input filter specification, which includes
Zend\Filter\StringTrim
and will add the appropriate validators based on the values from themin
,max
, andstep
attributes. See getInputSpecification in Zend\Form\Element\DateTime for more information.One difference from
Zend\Form\Element\DateTime
is that theZend\Validator\DateStep
validator will expect thestep
attribute to use an interval of days (default is 1 day).Returns array
DateTime Element¶
Zend\Form\Element\DateTime
is meant to be paired with the Zend/Form/View/Helper/FormDateTime
for HTML5 inputs
with type datetime. This element adds filters and validators to it’s input filter specification in order to
validate HTML5 datetime input values on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "datetime"
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | use Zend\Form\Element;
use Zend\Form\Form;
$dateTime = new Element\DateTime('appointment-date-time');
$dateTime
->setLabel('Appointment Date/Time')
->setAttributes(array(
'min' => '2010-01-01T00:00:00Z',
'max' => '2020-01-01T00:00:00Z',
'step' => '1', // minutes; default step interval is 1 min
));
$form = new Form('my-form');
$form->add($dateTime);
|
Note
Note: the min
, max
, and step
attributes should be set prior to calling Zend\Form::prepare().
Otherwise, the default input specification for the element may not contain the correct validation rules.
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element.
-
getInputSpecification
() Returns a input filter specification, which includes
Zend\Filter\StringTrim
and will add the appropriate validators based on the values from themin
,max
, andstep
attributes.If the
min
attribute is set, aZend\Validator\GreaterThan
validator will be added to ensure the date value is greater than the minimum value.If the
max
attribute is set, aZend\Validator\LessThanValidator
validator will be added to ensure the date value is less than the maximum value.If the
step
attribute is set to “any”, step validations will be skipped. Otherwise, a aZend\Validator\DateStep
validator will be added to ensure the date value is within a certain interval of minutes (default is 1 minute).Returns array
DateTimeLocal Element¶
Zend\Form\Element\DateTimeLocal
is meant to be paired with the Zend/Form/View/Helper/FormDateTimeLocal
for HTML5
inputs with type datetime-local. This element adds filters and validators to it’s input filter specification in
order to validate HTML5 a local datetime input values on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "datetime-local"
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | use Zend\Form\Element;
use Zend\Form\Form;
$dateTimeLocal = new Element\DateTimeLocal('appointment-date-time');
$dateTimeLocal
->setLabel('Appointment Date')
->setAttributes(array(
'min' => '2010-01-01T00:00:00',
'max' => '2020-01-01T00:00:00',
'step' => '1', // minutes; default step interval is 1 min
));
$form = new Form('my-form');
$form->add($dateTimeLocal);
|
Note
Note: the min
, max
, and step
attributes should be set prior to calling Zend\Form::prepare().
Otherwise, the default input specification for the element may not contain the correct validation rules.
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.
-
getInputSpecification
() Returns a input filter specification, which includes
Zend\Filter\StringTrim
and will add the appropriate validators based on the values from themin
,max
, andstep
attributes. See getInputSpecification in Zend\Form\Element\DateTime for more information.Returns array
Email Element¶
Zend\Form\Element\Email
is meant to be paired with the Zend/Form/View/Helper/FormEmail
for HTML5 inputs with
type email. This element adds filters and validators to it’s input filter specification in order to validate
HTML5 valid email address on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "email"
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | use Zend\Form\Element;
use Zend\Form\Form;
$form = new Form('my-form');
// Single email address
$email = new Element\Email('email');
$email->setLabel('Email Address')
$form->add($email);
// Comma separated list of emails
$emails = new Element\Email('emails');
$emails
->setLabel('Email Addresses')
->setAttribute('multiple', true);
$form->add($emails);
|
Note
Note: the multiple
attribute should be set prior to calling Zend\Form::prepare(). Otherwise, the default
input specification for the element may not contain the correct validation rules.
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element.
-
getInputSpecification
() Returns a input filter specification, which includes a
Zend\Filter\StringTrim
filter, and a validator based on themultiple
attribute.If the
multiple
attribute is unset or false, aZend\Validator\Regex
validator will be added to validate a single email address.If the
multiple
attribute is true, aZend\Validator\Explode
validator will be added to ensure the input string value is split by commas before validating each email address withZend\Validator\Regex
.Returns array
Month Element¶
Zend\Form\Element\Month
is meant to be paired with the Zend/Form/View/Helper/FormMonth
for HTML5 inputs with
type month. This element adds filters and validators to it’s input filter specification in order to validate
HTML5 month input values on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "month"
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | use Zend\Form\Element;
use Zend\Form\Form;
$month = new Element\Month('month');
$month
->setLabel('Month')
->setAttributes(array(
'min' => '2012-01',
'max' => '2020-01',
'step' => '1', // months; default step interval is 1 month
));
$form = new Form('my-form');
$form->add($month);
|
Note
Note: the min
, max
, and step
attributes should be set prior to calling Zend\Form::prepare().
Otherwise, the default input specification for the element may not contain the correct validation rules.
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.
-
getInputSpecification
() Returns a input filter specification, which includes
Zend\Filter\StringTrim
and will add the appropriate validators based on the values from themin
,max
, andstep
attributes. See getInputSpecification in Zend\Form\Element\DateTime for more information.One difference from
Zend\Form\Element\DateTime
is that theZend\Validator\DateStep
validator will expect thestep
attribute to use an interval of months (default is 1 month).Returns array
Number Element¶
Zend\Form\Element\Number
is meant to be paired with the Zend/Form/View/Helper/FormNumber
for HTML5 inputs with
type number. This element adds filters and validators to it’s input filter specification in order to validate
HTML5 number input values on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "number"
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | use Zend\Form\Element;
use Zend\Form\Form;
$number = new Element\Number('quantity');
$number
->setLabel('Quantity')
->setAttributes(array(
'min' => '0',
'max' => '10',
'step' => '1', // default step interval is 1
));
$form = new Form('my-form');
$form->add($number);
|
Note
Note: the min
, max
, and step
attributes should be set prior to calling Zend\Form::prepare().
Otherwise, the default input specification for the element may not contain the correct validation rules.
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element.
-
getInputSpecification
() Returns a input filter specification, which includes
Zend\Filter\StringTrim
and will add the appropriate validators based on the values from themin
,max
, andstep
attributes.If the
min
attribute is set, aZend\Validator\GreaterThan
validator will be added to ensure the number value is greater than the minimum value. Themin
value should be a valid floating point number.If the
max
attribute is set, aZend\Validator\LessThanValidator
validator will be added to ensure the number value is less than the maximum value. Themax
value should be a valid floating point number.If the
step
attribute is set to “any”, step validations will be skipped. Otherwise, a aZend\Validator\Step
validator will be added to ensure the number value is within a certain interval (default is 1). Thestep
value should be either “any” or a valid floating point number.Returns array
Range Element¶
Zend\Form\Element\Range
is meant to be paired with the Zend/Form/View/Helper/FormRange
for HTML5 inputs with
type range. This element adds filters and validators to it’s input filter specification in order to validate
HTML5 range values on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "range"
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | use Zend\Form\Element;
use Zend\Form\Form;
$range = new Element\Range('range');
$range
->setLabel('Minimum and Maximum Amount')
->setAttributes(array(
'min' => '0', // default minimum is 0
'max' => '100', // default maximum is 100
'step' => '1', // default interval is 1
));
$form = new Form('my-form');
$form->add($range);
|
Note
Note: the min
, max
, and step
attributes should be set prior to calling Zend\Form::prepare().
Otherwise, the default input specification for the element may not contain the correct validation rules.
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element\Number.
-
getInputSpecification()``
Returns a input filter specification, which includes
Zend\Filter\StringTrim
and will add the appropriate validators based on the values from themin
,max
, andstep
attributes. See getInputSpecification in Zend\Form\Element\Number for more information.The
Range
element differs fromZend\Form\Element\Number
in that theZend\Validator\GreaterThan
andZend\Validator\LessThan
validators will always be present. The default minimum is 1, and the default maximum is 100.Returns array
Time Element¶
Zend\Form\Element\Time
is meant to be paired with the Zend/Form/View/Helper/FormTime
for HTML5 inputs with type
time. This element adds filters and validators to it’s input filter specification in order to validate HTML5 time
input values on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "time"
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | use Zend\Form\Element;
use Zend\Form\Form;
$time = new Element\Month('time');
$time
->setLabel('Time')
->setAttributes(array(
'min' => '00:00:00',
'max' => '23:59:59',
'step' => '60', // seconds; default step interval is 60 seconds
));
$form = new Form('my-form');
$form->add($time);
|
Note
Note: the min
, max
, and step
attributes should be set prior to calling Zend\Form::prepare().
Otherwise, the default input specification for the element may not contain the correct validation rules.
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.
-
getInputSpecification
() Returns a input filter specification, which includes
Zend\Filter\StringTrim
and will add the appropriate validators based on the values from themin
,max
, andstep
attributes. See getInputSpecification in Zend\Form\Element\DateTime for more information.One difference from
Zend\Form\Element\DateTime
is that theZend\Validator\DateStep
validator will expect thestep
attribute to use an interval of seconds (default is 60 seconds).Returns array
Url Element¶
Zend\Form\Element\Url
is meant to be paired with the Zend/Form/View/Helper/FormUrl
for HTML5 inputs with type
url. This element adds filters and a Zend\Validator\Uri
validator to it’s input filter specification for
validating HTML5 URL input values on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "url"
.
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
use Zend\Form\Form;
$url = new Element\Url('webpage-url');
$url->setLabel('Webpage URL');
$form = new Form('my-form');
$form->add($url);
|
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element.
-
getInputSpecification
() Returns a input filter specification, which includes a
Zend\Filter\StringTrim
filter, and aZend\Validator\Uri
to validate the URI string.Returns array
Week Element¶
Zend\Form\Element\Week
is meant to be paired with the Zend/Form/View/Helper/FormWeek
for HTML5 inputs with type
week. This element adds filters and validators to it’s input filter specification in order to validate HTML5 week
input values on the server.
Basic Usage¶
This element automatically adds a "type"
attribute of value "week"
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | use Zend\Form\Element;
use Zend\Form\Form;
$week = new Element\Week('week');
$week
->setLabel('Week')
->setAttributes(array(
'min' => '2012-W01',
'max' => '2020-W01',
'step' => '1', // weeks; default step interval is 1 week
));
$form = new Form('my-form');
$form->add($week);
|
Note
Note: the min
, max
, and step
attributes should be set prior to calling Zend\Form::prepare().
Otherwise, the default input specification for the element may not contain the correct validation rules.
Public Methods¶
The following methods are in addition to the inherited methods of Zend\Form\Element\DateTime.
-
getInputSpecification
() Returns a input filter specification, which includes
Zend\Filter\StringTrim
and will add the appropriate validators based on the values from themin
,max
, andstep
attributes. See getInputSpecification in Zend\Form\Element\DateTime for more information.One difference from
Zend\Form\Element\DateTime
is that theZend\Validator\DateStep
validator will expect thestep
attribute to use an interval of weeks (default is 1 week).Returns array