Home Info Files

Zend Framework 2 Documentation (Manual)

File: /_sources/modules/zend.form.element.collection.txt

:orphan:

.. _zend.form.element.collection:

Collection
^^^^^^^^^^

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 do not know in advance how many elements you will need (in the case of elements
dynamically added to a form using JavaScript, for instance). For more information about Collection, please refer
to the :ref:`Form Collections tutorial <zend.form.collections>`.

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

.. _zend.form.element.collection.usage:

.. rubric:: Basic Usage

.. code-block:: php
   :linenos:

   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:

.. code-block:: php
   :linenos:
   
   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()
       )
   ));

.. _zend.form.element.collection.methods:

.. rubric:: Public Methods

The following methods are in addition to the inherited :ref:`methods of Zend\\Form\\Element <zend.form.element.methods>` .

.. function:: setOptions(array $options)
   :noindex:

   Set options for an element of type Collection. Accepted options, in addition to the inherited options of :ref:`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``.

.. function:: allowObjectBinding(object $object)
   :noindex:

   Checks if the object can be set in this fieldset.

   :rtype: bool

.. function:: setObject(array|Traversable $object)
   :noindex:

   Set the object used by the hydrator. In this case the "object" is a collection of objects.

.. function:: populateValues(array|Traversable $data)
   :noindex:

   Populate values

.. function:: allowValueBinding()
   :noindex:

   Checks if this fieldset can bind data

   :rtype: bool

.. function:: setCount($count)
   :noindex:

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

.. function:: getCount()
   :noindex:

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

   :rtype: integer

.. function:: setTargetElement($elementOrFieldset)
   :noindex:

   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.

.. function:: getTargetElement()
   :noindex:

   Return the target element used by the collection.

   :rtype: ElementInterface | null

.. function:: setAllowAdd($allowAdd)
   :noindex:

   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.

.. function:: allowAdd()
   :noindex:

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

   :rtype: boolean

.. function:: setAllowRemove($allowRemove)
   :noindex:

   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.

.. function:: allowRemove()
   :noindex:

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

   :rtype: boolean

.. function:: setShouldCreateTemplate($shouldCreateTemplate)
   :noindex:

   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.

.. function:: shouldCreateTemplate()
   :noindex:

   Return if a template should be created.

   :rtype: boolean

.. function:: setTemplatePlaceholder($templatePlaceholder)
   :noindex:

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

.. function:: getTemplatePlaceholder()
   :noindex:

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

   :rtype: string

.. function:: getTemplateElement()
   :noindex:

   Get a template element used for rendering purposes only

   :rtype: null|ElementInterface|FieldsetInterface

.. function:: prepareElement
   :noindex:

   Prepare the collection by adding a dummy template element if the user want one

.. function:: prepareFieldset()
   :noindex:

   If both count and targetElement are set, add them to the fieldset