<%= cocooned_add_item_link 'Add an item', form, :items %>
<% end %> <%= form.submit "Save" %> <% end %> ``` By default, new items will be inserted just before the immediate parent of the 'Add an item' link. You can have a look at the documentation of `cocooned_add_item_link` for more information about how to change that but we'll keep it simple for now. ### 4. Add a way to remove an item from the collection Change your sub form as follow: ```diff <% # `app/views/lists/_item_fields.html.erb` %> <%= cocooned_item do %> <%= f.label :description %> <%= f.text_field :description %> <%= f.check_box :done %> + <%= cocooned_remove_item_link 'Remove', f %> <% end %> ``` You're done! ### Gotchas #### Strong Parameters Gotcha To destroy nested models, Rails uses a virtual attribute called `_destroy`. When `_destroy` is set, the nested model will be deleted. If a record has previously been persisted, Rails generates and uses an additional `id` field. When using Rails > 4.0 (or strong parameters), you need to explicitly add both `:id` and `:_destroy` to the list of permitted parameters in your controller. In our example: ```ruby def list_params params.require(:list).permit(:name, tasks_attributes: [:id, :description, :done, :_destroy]) end ``` #### Has One Gotcha If you have a `has_one` association, then you (probably) need to set `force_non_association_create: true` on `cocooned_add_item_link` or the associated object will be destroyed every time the edit form is rendered (which is probably not what you expect). See the [original merge request](https://github.com/nathanvda/cocoon/pull/247) for more details. #### Complex nested forms If you want to build complex forms with multiple levels of nesting, make sure you [initialize Cocooned event handlers correctly for dynamically added child items](https://github.com/notus-sh/cocooned/blob/main/npm/README.md#complex-nested-forms) or your form won't behave as you might expect. ## Plugins Cocooned comes with two built-in plugins: * **Limit**, to set a maximum limit of items the association can contain * **Reorderable**, that will automatically update a `position` field in each of your sub forms when you add, remove or move an item. ### The limit plugin The limit plugin requires you specify the maximum number of items allowed in the association. To do so, pass a `:limit` option to the `cocooned_container` helper: ```erb <%= cocooned_container limit: 12 do %> <% # […] %> <% end %> ``` ### The reorderable plugin **Important:** To use the reorderable plugin, your model must have a `position` numeric attribute you use to order collections (as in [acts_as_list](https://rubygems.org/gems/acts_as_list)). The reorderable plugin can be activated in two ways through the `cocooned_container` helper: - With a boolean: `cocooned_container reorderable: true` Will use plugin's defaults (and start counting positions at 1) - With a configuration hash: `cocooned_container reorderable: { startAt: 0 }` Will use given `:startAt` as base position To be able to move items up and down in your form and for positions to be saved, you need to change your sub form as follow: ```diff <% # `app/views/lists/_item_fields.html.erb` %> <%= cocooned_item do %> <%= f.label :description %> <%= f.text_field :description %> <%= f.check_box :done %> + <%= f.hidden_field :position %> + <%= cocooned_move_item_up_link 'Up', f %> + <%= cocooned_move_item_down_link 'Down', f %> <%= cocooned_remove_item_link 'Remove', f %> <% end %> ``` Remember to add `:position` as a permitted parameter in your controller. ## Links or buttons? Each helper provided by Cocooned with a name ending with `_link` has its `_button` equivalent, to generate a `` instead of a ``: - `cocooned_add_item_link` <=> `cocooned_add_item_button` ([Documentation](https://github.com/notus-sh/cocooned/blob/main/lib/cocooned/helpers/tags/add.rb)) - `cocooned_remove_item_link` <=> `cocooned_remove_item_button` ([Documentation](https://github.com/notus-sh/cocooned/blob/main/lib/cocooned/helpers/tags/remove.rb)) - `cocooned_move_item_up_link` <=> `cocooned_move_item_up_button` ([Documentation](https://github.com/notus-sh/cocooned/blob/main/lib/cocooned/helpers/tags/up.rb)) - `cocooned_move_item_down_link` <=> `cocooned_move_item_down_button` ([Documentation](https://github.com/notus-sh/cocooned/blob/main/lib/cocooned/helpers/tags/down.rb)) While all `_link` helpers accept and will politely forward any option supported by ActionView's `link_to`, `_button` helpers will do the same with options supported by ActionView's `button_tag`. ## Internationalisation The label of any action trigger can be given explicitly as helper's first argument or as a block, just as you can do with ActionView's `link_to` or `button_to`. Additionally, Cocooned helpers will lookup I18n translations for a default label based on the action name (`add`, `remove`, `up`, `down`) and the association name. For `add` triggers, the association name used is the same as passed as argument. Other triggers extract the association name from form's `#object_name`. You can declare default labels in your translation files with following keys: - `cocooned.{association}.{action}` (Ex: `cocooned.items.add`) - `cocooned.defaults.{action}` If no translation is found, the default label will be the humanized action name. ## Javascript For more documentation about the JavaScript bundled in the companion package, please refer to [its own documentation](https://github.com/notus-sh/cocooned/blob/main/npm/README.md). ## Styling forms Cocooned now uses exclusively data-attribute to hook JavaScript methods on but usual classes are still here and will stay so you can style your forms: - `.cocooned-container` on a container - `.cocooned-item` on an item - `.cocooned-add` on an add trigger (link or button) - `.cocooned-remove` on a remove trigger (link or button) - `.cocooned-move-up` on a move up trigger (link or button) - `.cocooned-move-down` on a move down trigger (link or button) ## Migration from a previous version These migrations steps only highlight major changes. When upgrading from a previous version, always refer to [the CHANGELOG](https://github.com/notus-sh/cocooned/blob/main/CHANGELOG.md) for new features and breaking changes. ### From Cocooned ~1.0 #### Forms markup Cocooned 2.0 introduced the `cocooned_container` and `cocooned_item` helpers to respectively wrap the container where items will be added and each of the items. If you used Cocooned ~1.0, you should modify your main forms as follow: ```diff -