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>

The following public methods are in addition to those inherited from Zend\Form\View\Helper\FormInput.

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&#039;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&#039;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&#039;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

FormHidden

The FormHidden view helper can be used to render a <input type="hidden"> HTML form input. It is meant to work with the Zend\Form\Element\Hidden element.

FormHidden 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\Hidden('my-hidden');
$element->setValue('foo');

// Within your view...

echo $this->formHidden($element);
// <input type="hidden" name="my-hidden" value="foo">

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 of FormLabel::APPEND or FormLabel::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="">