sf-collection

SfCollection is a small jQuery plugin to handle symfony collection in a proper way.

The library purpose is to integrate with all possible Symfony Form collection, while keeping the complexity down to the minimum.

Why not using library xxx

Of course you can! :) In my experience, all other libraries out there have a major issue: renumber of collection keys. This introduce two major issues:

• collection entries cannot be indexed by string;
• a "renumbered" entry will be mapped to a different object in the model, which may cause many side effect (e.g. when dealing with entities, some record can be deleted even if you never hit the delete button)

Usage

Basic example:

To minimal configuration of collection is pretty straightforward:

$('#collection_div').sfcollection({
	collectionName: 'aform[collection_name]'
});

where form[collection_name] is the full name of the collection as generated by Symfony (think of it as the prefix of nested input elements).

To attach an event listener, you can use the following syntax:

$('#collection_div').on("sfcollectionadd", function(event, data) {
	console.log("element added", event, data);
});

Options

All options can be set directly on the DOM element with data-option-name. This means that the default Symfony parameter data-prototype is automatically bound to the element, and that data-collection-name can be generated by the form template.

Options:

• collectionName (required): full form name of the collection;
• prototype (required when allow add): HTML template to be used for new elements;
• prototypeName (default: __name__): name of the entry, to be replaced in prototype;
• allowAdd (default: true): allow to add new entries to the collection;
• allowRemove (default: true): allow to remove existing entries.

Hooks:

• initAddButton (format: callback(collection, entry) -> jQueryNode): by default, the widget create Add button for the collection only, by using the template read from data-prototype-add. This hook allow to override this behaviour and use an arbitrary logic. NOTE: when the collection button is added, entry is null.
• initRemoveButton (format: callback(collection, entry) -> jQueryNode): by default, the widget create Remove button only for the entries, by using the template read from data-prototype-remove. This hook allow to override this behaviour and use an arbitrary logic. NOTE: when the collection button is added, entry is null and the button will remove all collection item.
• entryNameGenerator (format: callback(collection, entryNames) -> string): by default, entry names are generated sequentially, starting the maximum value generated by the server. Names are never renumbered, and a custom strategy can be provided by overriding this hook.
• entrySelector (default: > div): selector to be used during initialization to initialize entries.

Events

• create: triggered after plugin initialization;
• add: triggered after an entry is added (not called during inizialization);
• remove: triggered after an entry is remove (called multiple time when removing all element);

Easy integration with Twig

By integrating with Symfony Form, the configuration of every collection in your project will be a one line task.

The library comes with a form theme file (jquery.sf-collection.html.twig) which need to applied to all form.

method 1: global configuration (no bower or other PM)

Add the following to your config.yml file:

twig:
    form:
        resources:
            # default entry (or whatever you already have)
            - form_div_layout.html.twig
            # add this
            - ':Form:jquery.sf-collection.html.twig'

Then copy jquery.sf-collection.html.twig to app/Resources/views/Form

method 2: global configuration (with bower or other PM)

Add the following to your config.yml file:

twig:
    paths:
         # this must be set
        "%kernel.root_dir%/../web/vendor/sf-collection": SfCollection
    form:
        resources:
            # default entry (or whatever you already have)
            - form_div_layout.html.twig
            # add this
            - '@SfCollection/twig/jquery.collection.html.twig'

method 3: single form theme

If you don't want to set the theme globally, then you can append the theme only to the forms which requires it. Note that enabling it globally do not introduce noticeable overhead, so this is not the preferred method.

{% form_theme myForm
    'AcmeDemoBundle::your-other-theme.html.twig'
    ':Form:jquery.sf-collection.html.twig'
%}

TODO

I will integrate new or missing feature while I found them. Feel free to open new issues and pull requests.

Contributing

Want to contribute? You are awesome!

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Make your changes on the src folder, never on the dist folder.
4. Commit your changes: git commit -m 'Add some feature'
5. Push to the branch: git push origin my-new-feature
6. Submit a pull request :D

Credits

Althrough I rewrote the library from scratch, the library is inspired by the work of Alain Tiemblo .

License

This library is released under MIT Licence. See LICENCE file for more information.