Collection Element

Sometimes, you may want to add input (or a set of inputs) multiple times, either because you don’t want to duplicate code, or because you does not know in advance how many elements you need (in the case of elements dynamically added to a form using JavaScript, for instance). For more information about Collection, please refer to ZendCollection tutorial.

Zend\Form\Element\Collection is meant to be paired with the Zend\Form\View\Helper\FormCollection.

Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
use Zend\Form\Element;
use Zend\Form\Form;

$colors = new Element\Collection('collection');
$colors->setLabel('Colors');
$colors->setCount(2);
$colors->setTargetElement(new Element\Color());
$colors->setShouldCreateTemplate(true);

$form = new Form('my-form');
$form->add($colors);

Using the array notation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 use Zend\Form\Element;
 use Zend\Form\Form;

     $form = new Form('my-form');
     $form->add(array(
             'type' => 'Zend\Form\Element\Collection',
             'options' => array(
                     'label' => 'Colors',
                     'count' => 2,
                     'should_create_template' => true,
                     'target_element' => new Element\Color()
             )
     ));

Public Methods

The following methods are in addition to the inherited methods of Zend\Form\Element .

setOptions(array $options)

Set options for an element of type Collection. Accepted options, in addition to the inherited options of Zend\Form\Element <zend.form.element.methods.set-options>` , are: "target_element", "count", "allow_add", "allow_remove", "should_create_template" and "template_placeholder". Those option keys respectively call call setTargetElement, setCount, setAllowAdd, setAllowRemove, setShouldCreateTemplate and setTemplatePlaceholder.

setCount($count)

Defines how many times the target element will be initially rendered by the Zend/Form/View/Helper/FormCollection view helper.

getCount()

Return the number of times the target element will be initially rendered by the Zend/Form/View/Helper/FormCollection view helper.

Return type:integer
setTargetElement($elementOrFieldset)

This function either takes an Zend/Form/ElementInterface, Zend/Form/FieldsetInterface instance or an array to pass to the form factory. When the Collection element will be validated, the input filter will be retrieved from this target element and be used to validate each element in the collection.

getTargetElement()

Return the target element used by the collection.

Return type:ElementInterface | null
setAllowAdd($allowAdd)

If allowAdd is set to true (which is the default), new elements added dynamically in the form (using JavaScript, for instance) will also be validated and retrieved.

allowAdd()

Return if new elements can be dynamically added in the collection.

Return type:boolean
setAllowRemove($allowRemove)

If allowRemove is set to true (which is the default), new elements added dynamically in the form (using JavaScript, for instance) will be allowed to be removed.

allowRemove()

Return if new elements can be dynamically removed from the collection.

Return type:boolean
setShouldCreateTemplate($shouldCreateTemplate)

If shouldCreateTemplate is set to true (defaults to false), a <span> element will be generated by the Zend/Form/View/Helper/FormCollection view helper. This non-semantic span element contains a single data-template HTML5 attribute whose value is the whole HTML to copy to create a new element in the form. The template is indexed using the templatePlaceholder value.

shouldCreateTemplate()

Return if a template should be created.

Return type:boolean
setTemplatePlaceholder($templatePlaceholder)

Set the template placeholder (defaults to __index__) used to index element in the template.

getTemplatePlaceholder()

Returns the template placeholder used to index element in the template.

Return type:string

Project Versions

Table Of Contents

This Page

Note: You need to stay logged into your GitHub account to contribute to the documentation.

Edit this document

Edit this document

The source code of this file is hosted on GitHub. Everyone can update and fix errors in this document with few clicks - no downloads needed.

  1. Login with your GitHub account.
  2. Go to Collection Element on GitHub.
  3. Edit file contents using GitHub's text editor in your web browser
  4. Fill in the Commit message text box at the end of the page telling why you did the changes. Press Propose file change button next to it when done.
  5. On Send a pull request page you don't need to fill in text anymore. Just press Send pull request button.
  6. Your changes are now queued for review under project's Pull requests tab on GitHub.