<commit_before># symfony-collection
A jQuery plugin that manages adding, deleting and moving elements from a Symfony collection

This is not really difficult to manage your collections using the `data-prototype` Symfony provides. But
after using several times collections, it appeared useful to me to create a jQuery plugin to do this job.

This is even more true when you need your elements to be moved up and down or added at a specific position: as the
form will be proceeded using field names, we should swap field contents or field names instead of moving fields themselves to get the job done. That's
not really friendly in javascript, so this plugin also aims to deal with that.

![sample](http://ocarina.fr/medias/duplicate.png)

# Live demo

Demo of this plugin is available live at: http://symfony-collection.fuz.org

Demo source code is here: https://github.com/ninsuo/symfony-collection-demo

# Basic usage

Your collection type should contain `prototype`, `allow_add`, `allow_remove` options (depending on which buttons
you require of course). And a class that will be used as a selector to run the collection plugin.

```php
->add('myCollection', 'collection',
   array (
        // ...
        'allow_add' => true,
        'allow_remove' => true,
        'prototype' => true,
        'attr' => array(
                'class' => 'my-selector',
        ),
))
```

Then, render your form after applying the given custom theme:

```jinja
     {% form_theme myForm 'AcmeDemoBundle::jquery.collection.html.twig' %}
     {{ form(myForm) }}
```

Finally, put the following code at the bottom of your page.

```html
    <script src="{{ asset('js/jquery.js') }}"></script>
    <script src="{{ asset('bundles/acmedemo/js/jquery.collection.js') }}"></script>

    <script type="text/javascript">
        $('.my-selector').collection();
    </script>
```

**Notes**

If you don't want to use the form theme, you should set the `name_prefix` option manually (see below).

If you want to use the form theme, but already use one, you can use both with:

```jinja
     {%
        form_theme myForm
            'AcmeDemoBundle::jquery.collection.html.twig'
            'AcmeDemoBundle::my-own-form-theme.html.twig'
     %}
```

# Options

**Customize rendered links**

You can customize displayed links by setting `up`, `down`, `add`, `remove`and `duplicate` options.

Default values are:

```js
     $('.collection').collection({
         up: '<a href="#">&#x25B2;</a>',
         down: '<a href="#">&#x25BC;</a>',
         add: '<a href="#">[ + ]</a>',
         remove: '<a href="#">[ - ]</a>',
         duplicate: '<a href="#">[ # ]</a>'
     });
```

**Disable links**

You can disable some buttons by using `allow_up`, `allow_down`, `allow_add`, `allow_remove`
and `allow_duplicate` options. By default, all buttons except `duplicate` are enabled.

For example, if you do not want your elements to be moved up and down, use:

```js
     $('.collection').collection({
         allow_up: false,
         allow_down: false
     });<commit_msg>form theme pitfall at the beinning of the README<commit_after># symfony-collection
A jQuery plugin that manages adding, deleting and moving elements from a Symfony collection

This is not really difficult to manage your collections using the `data-prototype` Symfony provides. But
after using several times collections, it appeared useful to me to create a jQuery plugin to do this job.

This is even more true when you need your elements to be moved up and down or added at a specific position: as the
form will be proceeded using field names, we should swap field contents or field names instead of moving fields themselves to get the job done. That's
not really friendly in javascript, so this plugin also aims to deal with that.

![sample](http://ocarina.fr/medias/duplicate.png)

# Live demo

Demo of this plugin is available live at: http://symfony-collection.fuz.org

Demo source code is here: https://github.com/ninsuo/symfony-collection-demo

# Basic usage

Your collection type should contain `prototype`, `allow_add`, `allow_remove` options (depending on which buttons
you require of course). And a class that will be used as a selector to run the collection plugin.

```php
->add('myCollection', 'collection',
   array (
        // ...
        'allow_add' => true,
        'allow_remove' => true,
        'prototype' => true,
        'attr' => array(
                'class' => 'my-selector',
        ),
))
```

Then, render your form after applying the given custom theme:

```jinja
     {% form_theme myForm 'AcmeDemoBundle::jquery.collection.html.twig' %}
     {{ form(myForm) }}
```

Finally, put the following code at the bottom of your page.

```html
    <script src="{{ asset('js/jquery.js') }}"></script>
    <script src="{{ asset('bundles/acmedemo/js/jquery.collection.js') }}"></script>

    <script type="text/javascript">
        $('.my-selector').collection();
    </script>
```

**Notes**

If you don't want to use the form theme, you should set the `name_prefix` option manually (see below).

If you want to use the form theme, but already use one, you can use both with:

```jinja
     {%
        form_theme myForm
            'AcmeDemoBundle::jquery.collection.html.twig'
            'AcmeDemoBundle::my-own-form-theme.html.twig'
     %}
```

# Common pitfall with Form Themes

Most of the time, you will need to create a [form theme](https://symfony.com/doc/current/form/form_customization.html)
that will help you render your collection and its children in a fancy way.

You need to consider two things to avoid problems:

1) in your form type(s), overwrite the `getBlockPrefix()` method and return a good name (ex: `AddressType` for an address).

2) in your form theme, you will just need to use the same name (`{% block AddressType_XXX %}`). Replace `XXX` by `widget`,
`error` or `row` according to what you want to do (read the [Symfony doc](https://symfony.com/doc/current/form/form_customization.html)
for more details).

There are many examples using form themes in the Advanced menu of the [demo website](http://symfony-collection.fuz.org/),
don't hesitate to look at them.

# Options

**Customize rendered links**

You can customize displayed links by setting `up`, `down`, `add`, `remove`and `duplicate` options.

Default values are:

```js
     $('.collection').collection({
         up: '<a href="#">&#x25B2;</a>',
         down: '<a href="#">&#x25BC;</a>',
         add: '<a href="#">[ + ]</a>',
         remove: '<a href="#">[ - ]</a>',
         duplicate: '<a href="#">[ # ]</a>'
     });
```

**Disable links**

You can disable some buttons by using `allow_up`, `allow_down`, `allow_add`, `allow_remove`
and `allow_duplicate` options. By default, all buttons except `duplicate` are enabled.

For example, if you do not want your elements to be moved up and down, use:

```js
     $('.collection').collection({
         allow_up: false,
         allow_down: false
     });
{'fraction_non_alphanumeric': 0.12805403851681518, 'fraction_numerical': 0.0017246335153779822, 'mean_word_length': 3.4551856594110117, 'pattern_counts': {'":': 0, '<': 35, '<?xml version=': 0, '>': 47, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '585850', 'n_tokens_mistral': 2049, 'n_tokens_neox': 1965, 'n_words': 817}