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.
orphan: |
---|
Element Base Class¶
Zend\Form\Element
is a base class for all specialized elements and Zend\Form\Fieldset
.
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 | use Zend\Form\Element;
use Zend\Form\Form;
$username = new Element\Text('username');
$username
->setLabel('Username')
->setAttributes(array(
'class' => 'username',
'size' => '30',
));
$password = new Element\Password('password');
$password
->setLabel('Password')
->setAttributes(array(
'size' => '30',
));
$form = new Form('my-form');
$form
->add($username)
->add($password);
|
Public Methods
-
setName
(string $name) Set the name for this element.
-
getName
() Return the name for this element.
Return type: string
-
setValue
(string $value) Set the value for this element.
-
getValue
() Return the value for this element.
Return type: string
-
setLabel
(string $label) Set the label content for this element.
-
getLabel
() Return the label content for this element.
Return type: string
-
setLabelAttributes
(array $labelAttributes) Set the attributes to use with the label.
-
getLabelAttributes
() Return the attributes to use with the label.
Return type: array
-
setLabelOptions
(array $labelOptions) Set label specific options.
-
getLabelOptions
() Return the label specific options.
Return type: array
-
setOptions
(array $options) Set options for an element. Accepted options are:
label
,label_attributes"
,label_options
, which callsetLabel
,setLabelAttributes
andsetLabelOptions
, respectively.
-
getOptions
() Get defined options for an element
Return type: array
-
getOption
(string $option) Return the specified option, if defined. If it’s not defined, returns null.
Return type: null|mixed
-
setAttribute
(string $key, mixed $value) Set a single element attribute.
-
getAttribute
(string $key) Retrieve a single element attribute.
Return type: mixed
-
removeAttribute
(string $key) Remove a single attribute
-
hasAttribute
(string $key) Check if a specific attribute exists for this element.
Return type: boolean
-
setAttributes
(array|Traversable $arrayOrTraversable) Set many attributes at once. Implementation will decide if this will overwrite or merge.
-
getAttributes
() Retrieve all attributes at once.
Return type: array|Traversable
-
removeAttributes
(array $keys) Remove many attributes at once
-
clearAttributes
() Clear all attributes for this element.
-
setMessages
(array|Traversable $messages) Set a list of messages to report when validation fails.
-
getMessages
() Returns a list of validation failure messages, if any.
Return type: array|Traversable
Standard Elements¶
orphan: |
---|
Button¶
Zend\Form\Element\Button
represents a button form input.
It can be used with the Zend\Form\View\Helper\FormButton
view helper.
Zend\Form\Element\Button
extends from ZendFormElement.
Basic Usage
This element automatically adds a type
attribute of value button
.
1 2 3 4 5 6 7 8 9 | use Zend\Form\Element;
use Zend\Form\Form;
$button = new Element\Button('my-button');
$button->setLabel('My Button')
->setValue('foo');
$form = new Form('my-form');
$form->add($button);
|
orphan: |
---|
Captcha¶
Zend\Form\Element\Captcha
can be used with forms where authenticated users are not necessary, but you want to prevent
spam submissions. It is paired 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);
|
Here is with the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 | use Zend\Captcha;
use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Captcha',
'name' => 'captcha',
'options' => array(
'label' => 'Please verify you are human',
'captcha' => new Captcha\Dumb(),
),
));
|
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.
-
getCaptcha
() Return the CAPTCHA adapter for this element.
Return type: Zend\Captcha\AdapterInterface
-
getInputSpecification
() Returns a input filter specification, which includes a
Zend\Filter\StringTrim
filter, and a CAPTCHA validator.Return type: array
orphan: |
---|
Checkbox¶
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);
|
Using the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Checkbox',
'name' => 'checkbox',
'options' => array(
'label' => 'A checkbox',
'use_hidden_element' => true,
'checked_value' => 'good',
'unchecked_value' => 'bad'
)
));
|
When creating a checkbox element, setting an attribute of checked will result in the checkbox always being checked regardless of any data object which might subsequently be bound to the form. The correct way to set the default value of a checkbox is to set the value attribute as for any other element. To have a checkbox checked by default make the value equal to the checked_value eg:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Checkbox',
'name' => 'checkbox',
'options' => array(
'label' => 'A checkbox',
'use_hidden_element' => true,
'checked_value' => 'yes',
'unchecked_value' => 'no'
),
'attributes' => array(
'value' => 'yes'
)
));
|
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 , 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
-
isChecked
() Checks if the checkbox is checked.
Return type: boolean
-
setChecked
(bool $value) Checks or unchecks the checkbox.
orphan: |
---|
Collection¶
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 do not know in advance how many elements you will need (in the case of elements dynamically added to a form using JavaScript, for instance). For more information about Collection, please refer to the Form Collections tutorial.
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);
|
Using the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 | use Zend\Form\Element;
use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Collection',
'options' => array(
'label' => 'Colors',
'count' => 2,
'should_create_template' => true,
'target_element' => new Element\Color()
)
));
|
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 , are:
"target_element"
,"count"
,"allow_add"
,"allow_remove"
,"should_create_template"
and"template_placeholder"
. Those option keys respectively call callsetTargetElement
,setCount
,setAllowAdd
,setAllowRemove
,setShouldCreateTemplate
andsetTemplatePlaceholder
.
-
allowObjectBinding
(object $object) Checks if the object can be set in this fieldset.
Return type: bool
-
setObject
(array|Traversable $object) Set the object used by the hydrator. In this case the “object” is a collection of objects.
-
populateValues
(array|Traversable $data) Populate values
-
allowValueBinding
() Checks if this fieldset can bind data
Return type: bool
-
setCount
($count) Defines how many times the target element will be initially 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.Return type: integer
-
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.
Return type: ElementInterface | null
-
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.
-
allowAdd
() Return if new elements can be dynamically added in the collection.
Return type: boolean
-
setAllowRemove
($allowRemove) If allowRemove is set to true (which is the default), new elements added dynamically in the form (using JavaScript, for instance) will be allowed to be removed.
-
allowRemove
() Return if new elements can be dynamically removed from the collection.
Return type: boolean
-
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-semantic 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.
-
shouldCreateTemplate
() Return if a template should be created.
Return type: boolean
-
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.
Return type: string
-
getTemplateElement
() Get a template element used for rendering purposes only
Return type: null|ElementInterface|FieldsetInterface
-
prepareElement
() Prepare the collection by adding a dummy template element if the user want one
-
prepareFieldset
() If both count and targetElement are set, add them to the fieldset
orphan: |
---|
Csrf¶
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);
|
You can change the options of the CSRF validator using the setCsrfValidatorOptions
function, or by using the "csrf_options"
key. Here is an example using the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Csrf',
'name' => 'csrf',
'options' => array(
'csrf_options' => array(
'timeout' => 600
)
)
));
|
Note
If you are using more than one form on a page, and each contains its own CSRF element, you will need to make sure that each form uniquely names its element; if you do not, it’s possible for the value of one to override the other within the server-side session storage, leading to the inability to validate one or more of the forms on your page. We suggest prefixing the element name with the form’s name or function: “login_csrf”, “registration_csrf”, etc.
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.Return type: array
-
setCsrfValidatorOptions
(array $options) Set the options that are used by the CSRF validator.
-
getCsrfValidatorOptions
() Get the options that are used by the CSRF validator.
Return type: array
-
setCsrfValidator
(ZendValidatorCsrf $validator) Override the default CSRF validator by setting another one.
-
getCsrfValidator
() Get the CSRF validator.
Return type: ZendValidatorCsrf
orphan: |
---|
File¶
Zend\Form\Element\File
represents a form file input and
provides a default input specification with a type of FileInput
(important for handling validators and filters correctly).
It can be used with the Zend\Form\View\Helper\FormFile
view helper.
Zend\Form\Element\File
extends from Zend\Form\Element.
Basic Usage
This element automatically adds a "type"
attribute of value "file"
.
It will also set the form’s enctype to multipart/form-data
during $form->prepare()
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | use Zend\Form\Element;
use Zend\Form\Form;
// Single file upload
$file = new Element\File('file');
$file->setLabel('Single file input');
// HTML5 multiple file upload
$multiFile = new Element\File('multi-file');
$multiFile->setLabel('Multi file input')
->setAttribute('multiple', true);
$form = new Form('my-file');
$form->add($file)
->add($multiFile);
|
orphan: |
---|
Image¶
Zend\Form\Element\Image
represents a image button form input.
It can be used with the Zend\Form\View\Helper\FormImage
view helper.
Zend\Form\Element\Image
extends from Zend\Form\Element.
Basic Usage
This element automatically adds a "type"
attribute of value "image"
.
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
use Zend\Form\Form;
$image = new Element\Image('my-image');
$image->setAttribute('src', 'http://my.image.url'); // Src attribute is required
$form = new Form('my-form');
$form->add($image);
|
orphan: |
---|
Month Select¶
Zend\Form\Element\MonthSelect
is meant to be paired with the Zend\Form\View\Helper\FormMonthSelect
.
This element creates two select elements, where the first one is populated with months and the second is
populated with years. By default, it sets 100 years in the past for the year element, starting with the current year.
Basic Usage
1 2 3 4 5 6 7 8 9 | use Zend\Form\Element;
use Zend\Form\Form;
$monthYear = new Element\MonthSelect('monthyear');
$monthYear->setLabel('Select a month and a year');
$monthYear->setMinYear(1986);
$form = new Form('dateselect');
$form->add($monthYear);
|
Using the array notation:
1 2 3 4 5 6 7 8 9 10 11 | use Zend\Form\Form;
$form = new Form('dateselect');
$form->add(array(
'type' => 'Zend\Form\Element\MonthSelect',
'name' => 'monthyear',
'options' => array(
'label' => 'Select a month and a year',
'min_year' => 1986,
)
));
|
Public Methods
The following methods are in addition to the inherited methods of Zend\Form\Element.
-
getMonthElement
() Returns the Select element that is used for the months part.
Return type: Zend\Form\Element\Select
-
getYearElement
() Returns the Select element that is used for the years part.
Return type: Zend\Form\Element\Select
-
setMonthAttributes
(array $monthAttributes) Set attributes on the Select element that is used for the months part.
-
getMonthAttributes
() Get attributes on the Select element that is used for the months part.
Return type: array
-
setYearAttributes
(array $yearAttributes) Set attributes on the Select element that is used for the years part.
-
getYearAttributes
() Get attributes on the Select element that is used for the years part.
Return type: array
-
setMinYear
(int $minYear) Set the minimum year.
-
getMinYear
() Get the minimum year.
-
setMaxYear
(int $maxYear) Set the maximum year.
-
getMaxYear
() Get the maximum year.
-
setValue
(mixed $value) Set the value for the MonthSelect element.
If the value is an instance of
\DateTime
, it will use the month and year values from that date. Otherwise, the value should be an associative array with themonth
key for the month value, and with theyear
key for the year value.
orphan: |
---|
MultiCheckbox¶
Zend\Form\Element\MultiCheckbox
is meant to be paired with the Zend\Form\View\Helper\FormMultiCheckbox
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 values from the multiple checkboxes.
Basic Usage
This element automatically adds a "type"
attribute of value "checkbox"
for every checkboxes.
1 2 3 4 5 6 7 8 9 10 11 12 13 | use Zend\Form\Element;
use Zend\Form\Form;
$multiCheckbox = new Element\MultiCheckbox('multi-checkbox');
$multiCheckbox->setLabel('What do you like ?');
$multiCheckbox->setValueOptions(array(
'0' => 'Apple',
'1' => 'Orange',
'2' => 'Lemon'
));
$form = new Form('my-form');
$form->add($multiCheckbox);
|
Using the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\MultiCheckbox',
'name' => 'multi-checkbox',
'options' => array(
'label' => 'What do you like ?',
'value_options' => array(
'0' => 'Apple',
'1' => 'Orange',
'2' => 'Lemon',
),
)
));
|
Advanced Usage
In order to set attributes or customize the option elements, an array can be used instead of a string. The following keys are supported:
"label"
- The string displayed for the option."value"
- The form value associated with the option."selected"
- Boolean that sets whether the option is marked as selected."disabled"
- Boolean that sets whether the option will be disabled"attributes"
- Array of html attributes that will be set on this option. Merged with the attributes set on the element."label_attributes"
- Array of html attributes that will be set on the label. Merged with the attributes set on the element’s label.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | $form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\MultiCheckbox',
'name' => 'multi-checkbox',
'options' => array(
'label' => 'What do you like ?',
'value_options' => array(
array(
'value' => '0',
'label' => 'Apple',
'selected' => false,
'disabled' => false,
'attributes' => array(
'id' => 'apple_option',
'data-fruit' => 'apple',
),
'label_attributes' => array(
'id' => 'apple_label',
),
),
array(
'value' => '1',
'label' => 'Orange',
'selected' => true,
),
array(
'value' => '2',
'label' => 'Lemon',
),
),
),
));
|
Public Methods
The following methods are in addition to the inherited methods of Zend\Form\Element\Checkbox .
-
setOptions
(array $options) Set options for an element of type Checkbox. Accepted options, in addition to the inherited options of Zend\Form\Element\Checkbox, are:
"value_options"
, which callsetValueOptions
.
-
setValueOptions
(array $options) Set the value options for every checkbox of the multi-checkbox. The array must contain a key => value for every checkbox.
-
getValueOptions
() Return the value options.
Return type: array
-
unsetValueOption
($key) Unset the value option from the multi-checkbox.
orphan: |
---|
Password¶
Zend\Form\Element\Password
represents a password form input.
It can be used with the Zend\Form\View\Helper\FormPassword
view helper.
Zend\Form\Element\Password
extends from Zend\Form\Element.
Basic Usage
This element automatically adds a "type"
attribute of value "password"
.
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
use Zend\Form\Form;
$password = new Element\Password('my-password');
$password->setLabel('Enter your password');
$form = new Form('my-form');
$form->add($password);
|
orphan: |
---|
Radio¶
Zend\Form\Element\Radio
is meant to be paired with the Zend\Form\View\Helper\FormRadio
for HTML inputs
with type radio. This element adds an InArray
validator to its input filter specification in order to validate
on the server if the value is contains within the radio value elements.
Basic Usage
This element automatically adds a "type"
attribute of value "radio"
for every radio.
1 2 3 4 5 6 7 8 9 10 11 12 | use Zend\Form\Element;
use Zend\Form\Form;
$radio = new Element\Radio('gender');
$radio->setLabel('What is your gender ?');
$radio->setValueOptions(array(
'0' => 'Female',
'1' => 'Male',
));
$form = new Form('my-form');
$form->add($radio);
|
Using the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Radio',
'name' => 'gender',
'options' => array(
'label' => 'What is your gender ?',
'value_options' => array(
'0' => 'Female',
'1' => 'Male',
),
),
));
|
Advanced Usage
See MultiCheckbox for examples of how to apply attributes and options to each radio button.
Public Methods
All the methods from the inherited methods of Zend\Form\Element\MultiCheckbox are also available for this element.
orphan: |
---|
Select¶
Zend\Form\Element\Select
is meant to be paired with the Zend\Form\View\Helper\FormSelect
for HTML inputs
with type select. This element adds an InArray
validator to its input filter specification in order to validate
on the server if the selected value belongs to the values. This element can be used as a multi-select element by adding
the “multiple” HTML attribute to the element.
Basic Usage
This element automatically adds a "type"
attribute of value "select"
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | use Zend\Form\Element;
use Zend\Form\Form;
$select = new Element\Select('language');
$select->setLabel('Which is your mother tongue?');
$select->setValueOptions(array(
'0' => 'French',
'1' => 'English',
'2' => 'Japanese',
'3' => 'Chinese',
));
$form = new Form('language');
$form->add($select);
|
Using the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Select',
'name' => 'language',
'options' => array(
'label' => 'Which is your mother tongue?',
'value_options' => array(
'0' => 'French',
'1' => 'English',
'2' => 'Japanese',
'3' => 'Chinese',
),
)
));
|
You can add an empty option (option with no value) using the "empty_option"
option:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Select',
'name' => 'language',
'options' => array(
'label' => 'Which is your mother tongue?',
'empty_option' => 'Please choose your language',
'value_options' => array(
'0' => 'French',
'1' => 'English',
'2' => 'Japanese',
'3' => 'Chinese',
),
)
));
|
Option groups are also supported. You just need to add an ‘options’ key to the value options.
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;
$select = new Element\Select('language');
$select->setLabel('Which is your mother tongue?');
$select->setValueOptions(array(
'european' => array(
'label' => 'European languages',
'options' => array(
'0' => 'French',
'1' => 'Italian',
),
),
'asian' => array(
'label' => 'Asian languages',
'options' => array(
'2' => 'Japanese',
'3' => 'Chinese',
),
),
));
$form = new Form('language');
$form->add($select);
|
Public Methods
The following methods are in addition to the inherited methods of Zend\Form\Element .
-
setOptions
(array $options) Set options for an element. Accepted options, in addition to the inherited options of Zend\Form\Element, are:
"value_options"
,"empty_option"
and"disable_inarray_validator"
, which callsetValueOptions
,setEmptyOption
andsetDisableInArrayValidator
, respectively.
-
setValueOptions
(array $options) Set the value options for the select element. The array must contain key => value pairs.
-
getValueOptions
() Return the value options.
Return type: array
-
unsetValueOption
($key) Unset the value option from the select element.
-
setEmptyOption
($emptyOption) Optionally set a label for an empty option (option with no value). It is set to “null” by default, which means that no empty option will be rendered.
-
getEmptyOption
() Get the label for the empty option (null if none).
Return type: string|null
orphan: |
---|
Submit¶
Zend\Form\Element\Submit
represents a submit button form input.
It can be used with the Zend\Form\View\Helper\FormSubmit
view helper.
Zend\Form\Element\Submit
extends from Zend\Form\Element.
Basic Usage
This element automatically adds a "type"
attribute of value "submit"
.
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
use Zend\Form\Form;
$submit = new Element\Submit('my-submit');
$submit->setValue('Submit Form');
$form = new Form('my-form');
$form->add($submit);
|
orphan: |
---|
Text¶
Zend\Form\Element\Text
represents a text form input.
It can be used with the Zend\Form\View\Helper\FormText
view helper.
Zend\Form\Element\Text
extends from Zend\Form\Element.
Basic Usage
This element automatically adds a "type"
attribute of value "text"
.
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
use Zend\Form\Form;
$text = new Element\Text('my-text');
$text->setLabel('Enter your name');
$form = new Form('my-form');
$form->add($text);
|
orphan: |
---|
Textarea¶
Zend\Form\Element\Textarea
represents a textarea form input.
It can be used with the Zend\Form\View\Helper\FormTextarea
view helper.
Zend\Form\Element\Textarea
extends from Zend\Form\Element.
Basic Usage
This element automatically adds a "type"
attribute of value "textarea"
.
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
use Zend\Form\Form;
$textarea = new Element\Textarea('my-textarea');
$textarea->setLabel('Enter a description');
$form = new Form('my-form');
$form->add($textarea);
|
HTML5 Elements¶
orphan: |
---|
Color¶
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);
|
Here is the same example using the array notation:
1 2 3 4 5 6 7 8 9 10 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Color',
'name' => 'color',
'options' => array(
'label' => 'Background 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.Return type: array
orphan: |
---|
Date¶
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 15 16 17 | 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
))
->setOptions(array(
'format' => 'Y-m-d'
));
$form = new Form('my-form');
$form->add($date);
|
Here is with the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Date',
'name' => 'appointment-date',
'options' => array(
'label' => 'Appointment Date',
'format' => 'Y-m-d'
),
'attributes' => array(
'min' => '2012-01-01',
'max' => '2020-01-01',
'step' => '1', // days; default step interval is 1 day
)
));
|
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 andformat
option. 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).Return type: array
orphan: |
---|
DateTime¶
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 15 16 17 | 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
))
->setOptions(array(
'format' => 'Y-m-d\TH:iP'
));
$form = new Form('my-form');
$form->add($dateTime);
|
Here is with the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\DateTime',
'name' => 'appointment-date-time',
'options' => array(
'label' => 'Appointment Date/Time',
'format' => 'Y-m-d\TH:iP'
),
'attributes' => array(
'min' => '2010-01-01T00:00:00Z',
'max' => '2020-01-01T00:00:00Z',
'step' => '1', // minutes; default step interval is 1 min
)
));
|
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 andformat
option.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, aZend\Validator\DateStep
validator will be added to ensure the date value is within a certain interval of minutes (default is 1 minute).The input filter specification also includes a
Zend\Validator\Date
validator to ensure the format of the value. If theformat
option is set, that format will be used. Otherwise the default format will be used.Return type: array
-
setOptions
(array $options) Set options for an element of type DateTime. The accepted option, in addition to the inherited options of Zend\Form\Element , is:
"format"
, which callssetFormat
.
-
setFormat
(string $format) Sets the format used to validate the value. Accepts a
\DateTime
compatible string.
-
getFormat
() Return the DateTime format used to validate the value.
Return type: String
orphan: |
---|
DateTimeLocal¶
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 15 16 17 | 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
))
->setOptions(array(
'format' => 'Y-m-d\TH:i'
));
$form = new Form('my-form');
$form->add($dateTimeLocal);
|
Here is with the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\DateTimeLocal',
'name' => 'appointment-date-time',
'options' => array(
'label' => 'Appointment Date',
'format' => 'Y-m-d\TH:i'
),
'attributes' => array(
'min' => '2010-01-01T00:00:00',
'max' => '2020-01-01T00:00:00',
'step' => '1', // minutes; default step interval is 1 min
)
));
|
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 andformat
option. See getInputSpecification in Zend\Form\Element\DateTime for more information.Return type: array
orphan: |
---|
Email¶
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);
|
Here is with the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Email',
'name' => 'email',
'options' => array(
'label' => 'Email Address'
),
));
$form->add(array(
'type' => 'Zend\Form\Element\Email',
'name' => 'emails',
'options' => array(
'label' => 'Email Addresses'
),
'attributes' => array(
'multiple' => true
)
));
|
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
.Return type: array
-
setValidator
(ValidatorInterface $validator) Sets the primary validator to use for this element
-
getValidator
() Get the primary validator
Return type: ValidatorInterface
-
setEmailValidator
(ValidatorInterface $validator) Sets the email validator to use for multiple or single email addresses.
-
getEmailValidator
() Get the email validator to use for multiple or single email addresses.
The default Regex validator in use is to match that of the browser validation, but you are free to set a different (more strict) email validator such as
Zend\Validator\Email
if you wish.
orphan: |
---|
Month¶
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);
|
Here is with the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Month',
'name' => 'month',
'options' => array(
'label' => 'Month'
),
'attributes' => array(
'min' => '2012-12',
'max' => '2020-01',
'step' => '1', // months; default step interval is 1 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).Return type: array
orphan: |
---|
Number¶
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);
|
Here is with the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Number',
'name' => 'quantity',
'options' => array(
'label' => 'Quantity'
),
'attributes' => array(
'min' => '0',
'max' => '10',
'step' => '1', // default step interval is 1
)
));
|
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\LessThan
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, 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.Return type: array
orphan: |
---|
Range¶
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);
|
Here is with the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Range',
'name' => 'range',
'options' => array(
'label' => 'Minimum and Maximum Amount'
),
'attributes' => array(
'min' => 0, // default minimum is 0
'max' => 100, // default maximum is 100
'step' => 1 // default interval is 1
)
));
|
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.Return type: array
orphan: |
---|
Time¶
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 15 16 17 | use Zend\Form\Element;
use Zend\Form\Form;
$time = new Element\Time('time');
$time
->setLabel('Time')
->setAttributes(array(
'min' => '00:00:00',
'max' => '23:59:59',
'step' => '60', // seconds; default step interval is 60 seconds
))
->setOptions(array(
'format' => 'H:i:s'
));
$form = new Form('my-form');
$form->add($time);
|
Here is the same example using the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Time',
'name' => 'time',
'options'=> array(
'label' => 'Time',
'format' => 'H:i:s'
),
'attributes' => array(
'min' => '00:00:00',
'max' => '23:59:59',
'step' => '60', // seconds; default step interval is 60 seconds
)
));
|
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.
Note
The default date format for the validator is H:i:s
. A valid time string is however not required to have a
seconds part. In fact some user agent UIs such as Google Chrome and Opera submits a value on the H:i
format (i.e.
without a second part). You might therefore want to set the date format accordingly.
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 andformat
option. 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).Return type: array
orphan: |
---|
Url¶
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);
|
Here is the same example using the array notation:
1 2 3 4 5 6 7 8 9 10 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Url',
'name' => 'webpage-url',
'options' => array(
'label' => 'Webpage 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.Return type: array
orphan: |
---|
Week¶
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);
|
Here is the same example using the array notation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | use Zend\Form\Form;
$form = new Form('my-form');
$form->add(array(
'type' => 'Zend\Form\Element\Week',
'name' => 'week',
'options' => array(
'label' => 'Week'
),
'attributes' => array(
'min' => '2012-W01',
'max' => '2020-W01',
'step' => '1', // weeks; default step interval is 1 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).Return type: array