7.13. Standard Form View Helpers

Standard form view helpers provided by ZF3 are shown in tables 7.13 - 7.16 below. These classes live in the Zend\Form\View\Helper namespace. As you can see from the table, the view helpers can be divided into the following categories:

• Generic form view helpers. These classes are designed to render the whole form (Form helper) or its single element (FormElement helper) and possible validation errors (FormElementErrors helper).

• View helpers for rendering HTML fields of certain types. These allow you to generate HTML markup for concrete form fields (e.g. FormButton, FormRadio, etc.) and a text label (FormLabel).

• View helpers for rendering form fields introduced in HTML5. These are analogous to the view helpers from the previous category, but intended for rendering HTML5 fields (e.g. FormDate, FormUrl, etc.)

• Other view helpers. In this category, we can put the view helper classes designed for rendering ZF3-specific fields, like FormMultiCheckbox, FormCaptcha, etc.

In the next sections, we will provide an overview of several frequently used form view helpers and their usage examples.

7.13.1. Rendering a Form Element

You can render a form field with the FormElement view helper. It is designed to be as flexible as possible and recognize as many field types as possible. So, with this view helper you are able to produce HTML markup for text fields, buttons, dropdown lists and so on.

The methods provided by this view helper are listed in table 7.17.

As you can see, there are two methods doing the same thing:

• The render() method produces the HTML markup for the form field. It accepts the single argument -- the instance of the element to render. You can retrieve the form element with the form model's get() method (see example below).
• The __invoke() method is a convenience wrapper which results in less code to write.

<?php 
// We assume that the form model is stored in $form variable.
// Render the E-mail field with the render() method.
echo $this->formElement()->render($form->get('email')); ?>

// The same, but with __invoke
echo $this->formElement($form->get('email')); 

When executed, the code above will generate the HTML code as follows:

<input type="text" name="email" id="email" value="">

Typically, there is no need to call view helpers for concrete HTML (or HTML5) fields (e.g. FormText, FormSubmit, etc.) Instead, you can use the generic FormElement view helper which determines the field type automatically and produces the needed HTML code.

7.13.2. Rendering an Element's Validation Errors

The FormElementErrors view helper class allows you to produce HTML markup for field validation errors (if present). If there are no validation errors for certain element, this view helper does not produce any output.

An example of using the FormElementErrors view helper is presented below:

<?php 
// We assume that the form model is stored in $form variable.
// Render validation errors for the E-mail field.
echo $this->formElementErrors($form->get('email')); 

If there were any validation errors, this code will generate the unordered list of errors using the <ul> HTML tag, and the list will contain as many items as there are errors for certain field. An example of such list for the E-mail field of our feedback form is presented below:

<ul>
  <li>&#039;hostname&#039; is not a valid hostname for the email address</li>
  <li>The input does not match the expected structure for a DNS hostname</li>
  <li>The input appears to be a local network name but local network names are not allowed</li>
</ul> 

7.13.3. Rendering an Element's Label

The FormLabel helper allows you to render the text label for an element:

<?php 
// We assume that the form model is stored in $form variable.
// Render text label for the E-mail field.
echo $this->formLabel($form->get('email')); 

When executed, the code above will generate the HTML code as follows:

<label for="email">Your E-mail</label>

7.13.4. Rendering a Form Row

The FormRow view helper is designed to simplify the rendering of a form field, it's label, and validation errors. With this class, you are able to render these in a single step. This helper is flexibly configurable, so you can apply a different decoration to the form row. The methods of this view helper class are listed in table 7.18.

An example of using the FormRow view helper is presented below:

<?php 
// We assume that the form model is stored in $form variable.
// Render the E-mail field, its label and (possible) validation errors.
echo $this->formRow($form->get('email')); 

When executed, the code above will generate the HTML code as follows:

<label for="email">Your E-mail</label>
<input type="text" name="email" id="email">
<ul>
  <li>&#039;hostname&#039; is not a valid hostname for the email address</li>
  <li>The input does not match the expected structure for a DNS hostname</li>
  <li>The input appears to be a local network name but local network names 
      are not allowed</li>
</ul> 

7.13.5. Rendering the Entire Form

The Form view helper allows you to render the opening <form> tag and its attributes; and the closing </form> tag. But its major purpose is to render the entire form and all of its fields with a single line of code. Public methods of the Form[Zend\Form\View\Helper\Form] view helper class are summarized in table 7.19.

You can render the whole form with the help of the Form's render() method as follows:

// We assume that the form model is stored in $form variable

// Render the whole form
echo $this->form()->render($form);

The same effect can be achieved with the __invoke magic method (see example below):

// The same, but with `__invoke`
echo $this->form($form);