Form View Helpers¶
Introduction¶
Zend Framework comes with an initial set of helper classes related to Forms: e.g., rendering a text input, selection box, or form labels. You can use helper, or plugin, classes to perform these behaviors for you.
See the section on view helpers for more information.
Standard Helpers¶
Form¶
The Form
view helper is used to render a <form>
HTML element and its attributes.
Basic usage:
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\Form;
use Zend\Form\Element;
// Within your view...
$form = new Form();
// ...add elements and input filter to form...
// Set attributes
$form->setAttribute('action', $this->url('contact/process'));
$form->setAttribute('method', 'post');
// Prepare the form elements
$form->prepare();
// Render the opening tag
echo $this->form()->openTag($form);
// <form action="/contact/process" method="post">
// ...render the form elements...
// Render the closing tag
echo $this->form()->closeTag();
// </form>
|
The following public methods are in addition to those inherited from Zend\Form\View\Helper\AbstractHelper.
-
openTag
(FormInterface $form = null) Renders the
<form>
open tag for the$form
instance.Return type: string
-
closeTag
() Renders a
</form>
closing tag.Return type: string
FormButton¶
The FormButton
view helper is used to render a <button>
HTML element and its attributes.
Basic usage:
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 | use Zend\Form\Element;
$element = new Element\Button('my-button');
$element->setLabel("Reset");
// Within your view...
/**
* Example #1: Render entire button in one shot...
*/
echo $this->formButton($element);
// <button name="my-button" type="button">Reset</button>
/**
* Example #2: Render button in 3 steps
*/
// Render the opening tag
echo $this->formButton()->openTag($element);
// <button name="my-button" type="button">
echo '<span class="inner">' . $element->getLabel() . '</span>';
// Render the closing tag
echo $this->formButton()->closeTag();
// </button>
/**
* Example #3: Override the element label
*/
echo $this->formButton()->render($element, 'My Content');
// <button name="my-button" type="button">My Content</button>
|
-
openTag
($element = null) Renders the
<button>
open tag for the$element
instance.Return type: string
-
closeTag
() Renders a
</button>
closing tag.Return type: string
-
render
(ElementInterface $element[, $buttonContent = null]) Renders a button’s opening tag, inner content, and closing tag.
Parameters: - $element – The button element.
- $buttonContent – (optional) The inner content to render. If
null
, will default to the$element
‘s label.
Return type: string
FormCheckbox¶
The FormCheckbox
view helper can be used to render a <input type="checkbox">
HTML
form input. It is meant to work with the Zend\Form\Element\Checkbox
element, which provides a default input specification for validating the checkbox values.
FormCheckbox
extends from Zend\Form\View\Helper\FormInput.
Basic usage:
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 | use Zend\Form\Element;
$element = new Element\Checkbox('my-checkbox');
// Within your view...
/**
* Example #1: Default options
*/
echo $this->formCheckbox($element);
// <input type="hidden" name="my-checkbox" value="0">
// <input type="checkbox" name="my-checkbox" value="1">
/**
* Example #2: Disable hidden element
*/
$element->setUseHiddenElement(false);
echo $this->formCheckbox($element);
// <input type="checkbox" name="my-checkbox" value="1">
/**
* Example #3: Change checked/unchecked values
*/
$element->setUseHiddenElement(true)
->setUncheckedValue('no')
->setCheckedValue('yes');
echo $this->formCheckbox($element);
// <input type="hidden" name="my-checkbox" value="no">
// <input type="checkbox" name="my-checkbox" value="yes">
|
FormElement¶
The FormElement
view helper proxies the rendering to specific form view helpers
depending on the type of the Zend\\Form\\Element
that is passed in. For instance,
if the passed in element had a type of “text”, the FormElement
helper will retrieve
and use the FormText
helper to render the element.
Basic usage:
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 33 34 35 36 | use Zend\Form\Form;
use Zend\Form\Element;
// Within your view...
/**
* Example #1: Render different types of form elements
*/
$textElement = new Element\Text('my-text');
$checkboxElement = new Element\Checkbox('my-checkbox');
echo $this->formElement($textElement);
// <input type="text" name="my-text" value="">
echo $this->formElement($checkboxElement);
// <input type="hidden" name="my-checkbox" value="0">
// <input type="checkbox" name="my-checkbox" value="1">
/**
* Example #2: Loop through form elements and render them
*/
$form = new Form();
// ...add elements and input filter to form...
$form->prepare();
// Render the opening tag
echo $this->form()->openTag($form);
// ...loop through and render the form elements...
foreach ($form as $element) {
echo $this->formElement($element); // <-- Magic!
echo $this->formElementErrors($element);
}
// Render the closing tag
echo $this->form()->closeTag();
|
FormElementErrors¶
The FormElementErrors
view helper is used to render the validation
error messages of an element.
Basic usage:
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 33 34 35 36 37 38 39 40 41 42 43 44 45 | use Zend\Form\Form;
use Zend\Form\Element;
use Zend\InputFilter\InputFilter;
use Zend\InputFilter\Input;
// Create a form
$form = new Form();
$element = new Element\Text('my-text');
$form->add($element);
// Create a input
$input = new Input('my-text');
$input->setRequired(true);
$inputFilter = new InputFilter();
$inputFilter->add($input);
$form->setInputFilter($inputFilter);
// Force a failure
$form->setData(array()); // Empty data
$form->isValid(); // Not valid
// Within your view...
/**
* Example #1: Default options
*/
echo $this->formElementErrors($element);
// <ul><li>Value is required and can't be empty</li></ul>
/**
* Example #2: Add attributes to open format
*/
echo $this->formElementErrors($element, array('class' => 'help-inline'));
// <ul class="help-inline"><li>Value is required and can't be empty</li></ul>
/**
* Example #3: Custom format
*/
echo $this->formElementErrors()
->setMessageOpenFormat('<div class="help-inline">')
->setMessageSeparatorString('</div><div class="help-inline">')
->setMessageCloseString('</div>')
->render($element);
// <div class="help-inline">Value is required and can't be empty</div>
|
The following public methods are in addition to those inherited from Zend\Form\View\Helper\AbstractHelper.
-
setMessageOpenFormat
(string $messageOpenFormat) Set the formatted string used to open message representation.
Parameters: $messageOpenFormat – The formatted string to use to open the messages. Uses '<ul%s><li>'
by default. Attributes are inserted here.
-
getMessageOpenFormat
() Returns the formatted string used to open message representation.
Return type: string
-
setMessageSeparatorString
(string $messageSeparatorString) Sets the string used to separate messages.
Parameters: $messageSeparatorString – The string to use to separate the messages. Uses '</li><li>'
by default.
-
getMessageSeparatorString
() Returns the string used to separate messages.
Return type: string
-
setMessageCloseString
(string $messageCloseString) Sets the string used to close message representation.
Parameters: $messageCloseString – The string to use to close the messages. Uses '</li></ul>'
by default.
-
getMessageCloseString
() Returns the string used to close message representation.
Return type: string
-
setAttributes
(array $attributes) Set the attributes that will go on the message open format.
Parameters: $attributes – Key value pairs of attributes.
-
getAttributes
() Returns the attributes that will go on the message open format.
Return type: array
-
render
(ElementInterface $element[, array $attributes = array()]) Renders validation errors for the provided
$element
.Parameters: - $element – The element.
- $attributes – Additional attributes that will go on the message open format. These are merged with those set via
setAttributes()
.
Return type: string
FormImage¶
The FormImage
view helper can be used to render a <input type="image">
HTML form input. It is meant to work with the Zend\Form\Element\Image
element.
FormImage
extends from Zend\Form\View\Helper\FormInput.
Basic usage:
1 2 3 4 5 6 7 8 9 | use Zend\Form\Element;
$element = new Element\Image('my-image');
$element->setAttribute('src', '/img/my-pic.png');
// Within your view...
echo $this->formImage($element);
// <input type="image" name="my-image" src="/img/my-pic.png">
|
FormInput¶
The FormInput
view helper is used to render a <input>
HTML form input tag.
It acts as a base class for all of the specifically typed form input helpers
(FormText, FormCheckbox, FormSubmit, etc.), and is not suggested for direct use.
It contains a general map of valid tag attributes and types for attribute filtering.
Each subclass of FormInput
implements it’s own specific map of valid tag attributes.
The following public methods are in addition to those inherited from Zend\Form\View\Helper\AbstractHelper.
-
render
(ElementInterface $element) Renders the
<input>
tag for the$element
.Return type: string
FormLabel¶
The FormLabel
view helper is used to render a <label>
HTML element and its attributes.
If you have a Zend\\I18n\\Translator\\Translator
attached, FormLabel
will translate
the label contents during it’s rendering.
Basic usage:
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 | use Zend\Form\Element;
$element = new Element\Text('my-text');
$element->setLabel('Label')
->setAttribute('id', 'text-id')
->setLabelAttributes(array('class' => 'control-label'));
// Within your view...
/**
* Example #1: Render label in one shot
*/
echo $this->formLabel($element);
// <label class="control-label" for="text-id">Label</label>
echo $this->formLabel($element, $this->formText($element));
// <label class="control-label" for="text-id">Label<input type="text" name="my-text"></label>
echo $this->formLabel($element, $this->formText($element), 'append');
// <label class="control-label" for="text-id"><input type="text" name="my-text">Label</label>
/**
* Example #2: Render label in separate steps
*/
// Render the opening tag
echo $this->formLabel()->openTag($element);
// <label class="control-label" for="text-id">
// Render the closing tag
echo $this->formLabel()->closeTag();
// </label>
|
Attaching a translator and setting a text domain:
1 2 3 4 5 6 7 8 | // Setting a translator
$this->formLabel()->setTranslator($translator);
// Setting a text domain
$this->formLabel()->setTranslatorTextDomain('my-text-domain');
// Setting both
$this->formLabel()->setTranslator($translator, 'my-text-domain');
|
Note
Note: If you have a translator in the Service Manager under the key, ‘translator’, the view helper plugin
manager will automatically attach the translator to the FormLabel view helper. See
Zend\\View\\HelperPluginManager::injectTranslator()
for more information.
The following public methods are in addition to those inherited from Zend\Form\View\Helper\AbstractHelper.
-
__invoke
(ElementInterface $element = null, string $labelContent = null, string $position = null) Render a form label, optionally with content.
Always generates a “for” statement, as we cannot assume the form input will be provided in the
$labelContent
.Parameters: - $element – A form element.
- $labelContent – If null, will attempt to use the element’s label value.
- $position – Append or prepend the element’s label value to the
$labelContent
. One ofFormLabel::APPEND
orFormLabel::PREPEND
(default)
Return type: string
-
openTag
(array|ElementInterface $attributesOrElement = null) Renders the
<label>
open tag and attributes.Parameters: $attributesOrElement – An array of key value attributes or a ElementInterface
instance.Return type: string
-
closeTag
() Renders a
</label>
closing tag.Return type: string
AbstractHelper¶
The AbstractHelper
is used as a base abstract class for Form view helpers, providing methods
for validating form HTML attributes, as well as controlling the doctype and character encoding.
AbstractHelper
also extends from Zend\I18n\View\Helper\AbstractTranslatorHelper
which
provides an implementation for the Zend\I18n\Translator\TranslatorAwareInterface
that allows setting a translator and text domain.
The following public methods are in addition to the inherited methods of Zend\I18n\View\Helper\AbstractTranslatorHelper.
-
setDoctype
(string $doctype) Sets a doctype to use in the helper.
-
getDoctype
() Returns the doctype used in the helper.
Return type: string
-
setEncoding
(string $encoding) Set the translation text domain to use in helper when translating.
-
getEncoding
() Returns the character encoding used in the helper.
Return type: string
-
getId
() Returns the element id. If no ID attribute present, attempts to use the name attribute. If name attribute is also not present, returns null.
Return type: string or null
HTML5 Helpers¶
FormColor¶
The FormColor
view helper can be used to render a <input type="color">
HTML5 form input.
It is meant to work with the Zend\Form\Element\Color
element, which provides a default input specification for validating HTML5 color values.
FormColor
extends from Zend\Form\View\Helper\FormInput.
Basic usage:
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
$element = new Element\Color('my-color');
// Within your view...
echo $this->formColor($element);
// <input type="color" name="my-color" value="">
|
FormDate¶
The FormDate
view helper can be used to render a <input type="date">
HTML5 form input. It is meant to work with the Zend\Form\Element\Date
element, which provides a default input specification for validating HTML5 date values.
FormDate
extends from Zend\Form\View\Helper\FormDateTime.
Basic usage:
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
$element = new Element\Date('my-date');
// Within your view...
echo $this->formDate($element);
// <input type="date" name="my-date" value="">
|
FormDateTime¶
The FormDateTime
view helper can be used to render a <input type="datetime">
HTML5 form input. It is meant to work with the Zend\Form\Element\DateTime
element, which provides a default input specification for validating HTML5 datetime values.
FormDateTime
extends from Zend\Form\View\Helper\FormInput.
Basic usage:
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
$element = new Element\DateTime('my-datetime');
// Within your view...
echo $this->formDateTime($element);
// <input type="datetime" name="my-datetime" value="">
|
FormDateTimeLocal¶
The FormDateTimeLocal
view helper can be used to render a <input type="datetime-local">
HTML5 form input. It is meant to work with the Zend\Form\Element\DateTimeLocal
element, which provides a default input specification for validating HTML5 datetime values.
FormDateTimeLocal
extends from Zend\Form\View\Helper\FormDateTime.
Basic usage:
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
$element = new Element\DateTimeLocal('my-datetime');
// Within your view...
echo $this->formDateTimeLocal($element);
// <input type="datetime-local" name="my-datetime" value="">
|
FormEmail¶
The FormEmail
view helper can be used to render a <input type="email">
HTML5 form input. It is meant to work with the Zend\Form\Element\Email
element, which provides a default input specification with an email validator.
FormEmail
extends from Zend\Form\View\Helper\FormInput.
Basic usage:
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
$element = new Element\Email('my-email');
// Within your view...
echo $this->formEmail($element);
// <input type="email" name="my-email" value="">
|
FormMonth¶
The FormMonth
view helper can be used to render a <input type="month">
HTML5 form input. It is meant to work with the Zend\Form\Element\Month
element, which provides a default input specification for validating HTML5 date values.
FormMonth
extends from Zend\Form\View\Helper\FormDateTime.
Basic usage:
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
$element = new Element\Month('my-month');
// Within your view...
echo $this->formMonth($element);
// <input type="month" name="my-month" value="">
|
FormTime¶
The FormTime
view helper can be used to render a <input type="time">
HTML5 form input. It is meant to work with the Zend\Form\Element\Time
element, which provides a default input specification for validating HTML5 time values.
FormTime
extends from Zend\Form\View\Helper\FormDateTime.
Basic usage:
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
$element = new Element\Time('my-time');
// Within your view...
echo $this->formTime($element);
// <input type="time" name="my-time" value="">
|
FormWeek¶
The FormWeek
view helper can be used to render a <input type="week">
HTML5 form input. It is meant to work with the Zend\Form\Element\Week
element, which provides a default input specification for validating HTML5 week values.
FormWeek
extends from Zend\Form\View\Helper\FormDateTime.
Basic usage:
1 2 3 4 5 6 7 8 | use Zend\Form\Element;
$element = new Element\Week('my-week');
// Within your view...
echo $this->formWeek($element);
// <input type="week" name="my-week" value="">
|