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:

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:

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

FormCaptcha

TODO

Basic usage:

use Zend\Captcha;
use Zend\Form\Element;

$captcha = new Element\Captcha('captcha');
$captcha
    ->setCaptcha(new Captcha\Dumb())
    ->setLabel('Please verify you are human');

// Within your view...

echo $this->formCaptcha($captcha);

// TODO

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:

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">

FormCollection

TODO

Basic usage:

TODO

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:

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:

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

FormFile

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

FormFile extends from Zend\Form\View\Helper\FormInput.

Basic usage:

use Zend\Form\Element;

$element = new Element\File('my-file');

// Within your view...

echo $this->formFile($element);
// <input type="file" name="my-file">

For HTML5 multiple file uploads, the multiple attribute can be used. Browsers that do not support HTML5 will default to a single upload input.

use Zend\Form\Element;

$element = new Element\File('my-file');
$element->setAttribute('multiple', true);

// Within your view...

echo $this->formFile($element);
// <input type="file" name="my-file" multiple="multiple">

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:

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:

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:

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:

// 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

FormMultiCheckbox

The FormMultiCheckbox view helper can be used to render a group <input type="checkbox"> HTML form inputs. It is meant to work with the Zend\Form\Element\MultiCheckbox element, which provides a default input specification for validating a multi checkbox.

FormMultiCheckbox extends from Zend\Form\View\Helper\FormInput.

Basic usage:

use Zend\Form\Element;

$element = new Element\MultiCheckbox('my-multicheckbox');
$element->setValueOptions(array(
   '0' => 'Apple',
   '1' => 'Orange',
   '2' => 'Lemon',
));

// Within your view...

/**
 * Example #1: using the default label placement
 */
echo $this->formMultiCheckbox($element);
// <label><input type="checkbox" name="my-multicheckbox[]" value="0">Apple</label>
// <label><input type="checkbox" name="my-multicheckbox[]" value="1">Orange</label>
// <label><input type="checkbox" name="my-multicheckbox[]" value="2">Lemon</label>

/**
 * Example #2: using the prepend label placement
 */
echo $this->formMultiCheckbox($element, 'prepend');
// <label>Apple<input type="checkbox" name="my-multicheckbox[]" value="0"></label>
// <label>Orange<input type="checkbox" name="my-multicheckbox[]" value="1"></label>
// <label>Lemon<input type="checkbox" name="my-multicheckbox[]" value="2"></label>

FormPassword

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

FormPassword extends from Zend\Form\View\Helper\FormInput.

Basic usage:

use Zend\Form\Element;

$element = new Element\Password('my-password');

// Within your view...
echo $this->formPassword($element);

Output:

<input type="password" name="my-password" value="">

FormRadio

The FormRadio view helper can be used to render a group <input type="radio"> HTML form inputs. It is meant to work with the Zend\Form\Element\Radio element, which provides a default input specification for validating a radio.

FormRadio extends from Zend\Form\View\Helper\FormMultiCheckbox.

Basic usage:

use Zend\Form\Element;

$element = new Element\Radio('gender');
$element->setValueOptions(array(
   '0' => 'Male',
   '1' => 'Female',
));

// Within your view...

/**
 * Example #1: using the default label placement
 */
echo $this->formRadio($element);
// <label><input type="radio" name="gender[]" value="0">Male</label>
// <label><input type="radio" name="gender[]" value="1">Female</label>

/**
 * Example #2: using the prepend label placement
 */
echo $this->formRadio($element, 'prepend');
// <label>Male<input type="checkbox" name="gender[]" value="0"></label>
// <label>Female<input type="checkbox" name="gender[]" value="1"></label>

FormReset

The FormReset view helper can be used to render a <input type="reset"> HTML form input.

FormText extends from Zend\Form\View\Helper\FormInput.

Basic usage:

use Zend\Form\Element;

$element = new Element('my-reset');
$element->setAttribute('value', 'Reset');

// Within your view...
echo $this->formReset($element);

Output:

<input type="reset" name="my-reset" value="Reset">

FormRow

TODO

Basic usage:

TODO

FormSelect

The FormSelect view helper can be used to render a group <input type="select"> HTML form input. It is meant to work with the Zend\Form\Element\Select element, which provides a default input specification for validating a select.

FormSelect extends from Zend\Form\View\Helper\FormInput.

Basic usage:

use Zend\Form\Element;

$element = new Element\Select('language');
$element->setValueOptions(array(
   '0' => 'French',
   '1' => 'English',
   '2' => 'Japanese',
   '3' => 'Chinese'
));

// Within your view...

/**
 * Example
 */
echo $this->formSelect($element);

FormSubmit

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

FormSubmit extends from Zend\Form\View\Helper\FormInput.

Basic usage:

use Zend\Form\Element;

$element = new Element\Submit('my-submit');

// Within your view...
echo $this->formSubmit($element);

Output:

<input type="submit" name="my-submit" value="">

FormText

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

FormText extends from Zend\Form\View\Helper\FormInput.

Basic usage:

use Zend\Form\Element;

$element = new Element\Text('my-text');

// Within your view...
echo $this->formText($element);

Output:

<input type="text" name="my-text" value="">

FormTextarea

The FormTextarea view helper can be used to render a <textarea></textarea> HTML form input. It is meant to work with the Zend\Form\Element\Textarea element.

Basic usage:

use Zend\Form\Element;

$element = new Element\Textarea('my-textarea');

// Within your view...
echo $this->formTextarea($element);

Output:

<textarea name="my-textarea"></textarea>

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.

FormColor extends from Zend\Form\View\Helper\FormInput.

Basic usage:

use Zend\Form\Element;

$element = new Element\Color('my-color');

// Within your view...
echo $this->formColor($element);

Output:

<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:

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:

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:

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:

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:

use Zend\Form\Element;

$element = new Element\Month('my-month');

// Within your view...

echo $this->formMonth($element);
// <input type="month" name="my-month" value="">

FormNumber

TODO

Basic usage:

TODO

FormRange

TODO

Basic usage:

TODO

FormSearch

The FormSearch view helper can be used to render a <input type="search"> HTML5 form input.

FormSearch extends from Zend\Form\View\Helper\FormText.

Basic usage:

use Zend\Form\Element;

$element = new Element('my-search');

// Within your view...
echo $this->formSearch($element);

Output:

<input type="search" name="my-search" value="">

FormTel

The FormTel view helper can be used to render a <input type="tel"> HTML5 form input.

FormTel extends from Zend\Form\View\Helper\FormInput.

Basic usage:

use Zend\Form\Element;

$element = new Element('my-tel');

// Within your view...
echo $this->formTel($element);

Output:

<input type="tel" name="my-tel" 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:

use Zend\Form\Element;

$element = new Element\Time('my-time');

// Within your view...

echo $this->formTime($element);
// <input type="time" name="my-time" value="">

FormUrl

TODO

Basic usage:

TODO

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:

use Zend\Form\Element;

$element = new Element\Week('my-week');

// Within your view...

echo $this->formWeek($element);
// <input type="week" name="my-week" value="">

File Upload Progress Helpers

FormFileApcProgress

The FormFileApcProgress view helper can be used to render a <input type="hidden" ...> with a progress ID value used by the APC File Upload Progress feature. The APC php module is required for this view helper to work. Unlike other Form view helpers, the FormFileSessionProgress helper does not accept a Form Element as a parameter.

An id attribute with a value of "progress_key" will automatically be added.

Warning

The view helper must be rendered before the file input in the form, or upload progress will not work correctly.

Best used with the Zend\ProgressBar\Upload\ApcProgress handler.

See the apc.rfc1867 ini setting in the APC Configuration documentation for more information.

FormFileApcProgress extends from Zend\Form\View\Helper\FormInput.

Basic usage:

// Within your view...

echo $this->formFileApcProgress();
// <input type="hidden" id="progress_key" name="APC_UPLOAD_PROGRESS" value="12345abcde">

FormFileSessionProgress

The FormFileSessionProgress view helper can be used to render a <input type="hidden" ...> which can be used by the PHP 5.4 File Upload Session Progress feature. PHP 5.4 is required for this view helper to work. Unlike other Form view helpers, the FormFileSessionProgress helper does not accept a Form Element as a parameter.

An id attribute with a value of "progress_key" will automatically be added.

Warning

The view helper must be rendered before the file input in the form, or upload progress will not work correctly.

Best used with the Zend\ProgressBar\Upload\SessionProgress handler.

See the Session Upload Progress in the PHP documentation for more information.

FormFileSessionProgress extends from Zend\Form\View\Helper\FormInput.

Basic usage:

// Within your view...

echo $this->formFileSessionProgress();
// <input type="hidden" id="progress_key" name="PHP_SESSION_UPLOAD_PROGRESS" value="12345abcde">

FormFileUploadProgress

The FormFileUploadProgress view helper can be used to render a <input type="hidden" ...> which can be used by the PECL uploadprogress extension. Unlike other Form view helpers, the FormFileUploadProgress helper does not accept a Form Element as a parameter.

An id attribute with a value of "progress_key" will automatically be added.

Warning

The view helper must be rendered before the file input in the form, or upload progress will not work correctly.

Best used with the Zend\ProgressBar\Upload\UploadProgress handler.

See the PECL uploadprogress extension for more information.

FormFileUploadProgress extends from Zend\Form\View\Helper\FormInput.

Basic usage:

// Within your view...

echo $this->formFileSessionProgress();
// <input type="hidden" id="progress_key" name="UPLOAD_IDENTIFIER" value="12345abcde">