A free and open-source book on Zend Framework for beginners


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:

Table 7.13. View helpers designed for using with forms
Method name Description
Generic helpers
Form Renders the entire form and all its elements.
FormElement Renders a generic form element.
FormElementErrors Renders validation errors for a form element.
FormRow Renders the label, the field and validation errors.
Table 7.14. HTML 4 field helpers
Method name Description
FormButton Renders the <button> form field.
FormCheckbox Renders the <input type="checkbox"> field.
FormFile Renders the <input type="file"> form field.
FormHidden Renders the <input type="hidden"> form field.
FormInput Renders an <input> form field.
FormImage Renders the <input type="image"> form field.
FormLabel Renders the <label> tag.
FormPassword Renders the <input type="password"> form field.
FormRadio Renders the <input type="radio"> form field.
FormReset Renders the <input type="reset"> form field.
FormSelect Renders the <select> dropdown field.
FormSubmit Renders the <input type="submit"> form field.
FormText Renders the <input type="text"> form field.
FormTextarea Renders the <textarea> multi-line text field.
Table 7.15. HTML 5 field helpers
Method name Description
FormColor Renders the <input type="color"> HTML5 form field.
FormDate Renders the <input type="date"> HTML5 form field.
FormDateTime Renders the <input type="date"> HTML5 form field.
FormDateTimeLocal Renders the <input type="datetime-local"> HTML5 form field.
FormEmail Renders the <input type="email"> HTML5 form field.
FormMonth Renders the <input type="month"> HTML5 form field.
FormNumber Renders the <input type="number"> HTML5 form field.
FormRange Renders the <input type="range"> HTML5 form field.
FormTel Renders the <input type="tel"> HTML5 form field.
FormTime Renders the <input type="time"> HTML5 form field.
FormUrl Renders the <input type="url"> HTML5 form field.
FormWeek Renders the <input type="week"> HTML5 form field.
Table 7.16. Other helpers
Method name Description
FormCaptcha Renders the CAPTCHA security field.
FormDateSelect Renders the date select field.
FormDateTimeSelect Renders the datetime select field.
FormMonthSelect Renders the month select field.
FormMultiCheckbox Renders the multi checkbox field.
FormCollection Renders the collection of elements.

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.

Table 7.17. Methods provided by the FormElement view helper
Method name Description
render($element) PHP magic method which renders the given form field.
__invoke($element) PHP magic method which renders the given form field (the effect is the same as render()).

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

<?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.

Table 7.18. Methods provided by the FormRow view helper
Method name Description
render($element) Renders the form row.
__invoke($element, $labelPosition, $renderErrors, $partial) Renders the form row (convenience wrapper).
setInputErrorClass($inputErrorClass) Sets input error CSS class.
setLabelAttributes($labelAttributes) Sets label attributes.
setLabelPosition($labelPosition) Sets label position (before or after the field).
setRenderErrors($renderErrors) Set if the errors are rendered by this helper.
setPartial($partial) Set a partial view script to use for rendering the row.

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.

Table 7.19. Methods provided by the Form view helper
Method name Description
render($form) Renders the entire form and all its elements.
__invoke($form) PHP magic method which renders the entire form and all its elements (the effect is the same as render()).
openTag($form) Renders the opening <form> tag.
closeTag() Renders the closing </form> tag.

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);

Top