collection.md

Collection

The Collection plugin is meant to be the Javascript side of the Symfony2 Collection Type.

A Collection is a form field that holds a list of sub forms of the same type. Items can be added or removed from the list (optional). You can set a minimum and a maximum length for the collection.

Setting up your form:

The collection needs several options:

Required configuration:

• collection: (string) The name of the placeholder to replace in the prototype
• prototype: (string) The HTML code of the prototype of the collection.

Optional configuration:

• add: (string) The ID of the add button for the collection. Specifying this option allows the user to add a new element to the collection.
• delete: (string) The Class of the delete buttons for collection items. Specifying this option allows the user to remove existing element from the collection.
• min: (integer) The minimum number of element the collection should contain (prevent item from being deleted if the minimum number of items is not reached).
• max:_ (integer) The maximum number of element the collection should contain (prevent item from being added if the maximum number of items is reached).

The easiest way to specify these options is to set the correct data- attribute to the collection root element, as below:

<!-- The collection -->
<form>
    <div
        id="my-collection"
        data-collection="__name__"
        data-prototype="..."
        data-collection-add="my-collection-add"
        data-collection-delete="my-collection-delete"
        data-collection-max="3"
        data-collection-min="1"
    >
    </div>
    <button id="my-collection-add" type="button">Add</button>
</form>

<!-- The prototype that should be in the "data-prototype" attribute. -->
<div id="my-collection-__name__-group">
    <input type="text" id="my-collection-__name__" name="my_collection[__name__]"/>
    <button type="button" data-collection-delete="my-collection-__name__-group" class="my-collection-delete">X</button>
</div>

Initialize the collection:

Automatically on all collection fields:

$('[data-collection]').collection();

or on a specific field:

$('#my_collection_field').collection();

Usage

The Collection javascript object that holds all the logic and data of the collection is stored in the 'collection' data attribute of the element. You can access it like that:

$("#my-collection-field").collection();
var collection = $("#my-collection-field").data('collection');

Callbacks:

Callbacks are called before adding and removing items in the collection. They allow you to inject your custom logic and prevent item from being added/removed when you need it.

• onAdd: (function) A callback called in the Collection's context and taking as a parameter the item to add, that should return a boolean: whether the new item should be added.
• onRemove: (function) A callback called in the Collection's context and taking as a parameter the item to remove, that should return a boolean: whether the given item should be removed.

Callbacks have to be specified when setting up the collection, as below:

$('#my_collection_field').collection({
    onAdd: function (item) { return confirm('Are you sure you want to add an item?'); },
    onRemove: function (item) { return confirm('Are you sure you want to delete this item?'); },
});