How it works

Cocoon defines helper methods:

• link_to_add_association
• link_to_remove_association

link_to_add_association(*args, &block) public

Method definition types ... link_to_add_association(string, object, association, hash)

This method adds an html link to your form. When the link is clicked, the JQuery will dynamically render a new partial's html to the form.

This should be called within the form builder.

link_to_add_association takes four parameters:

• name: the text to show in the link
• f: the form builder
• association: the name of the association (plural) of which a new instance needs to be added (symbol or string).
• html_options: extra html-options (see link_to There are some special options, the first three allow to control the placement of the new link-data:
  • data-association-insertion-traversal : the jquery traversal method to allow node selection relative to the link. closest, next, children, etc. Default: absolute selection
  • data-association-insertion-node : the jquery selector of the node as string, or a function that takes the link_to_add_association node as the parameter and returns a node. Default: parent node
  • data-association-insertion-method : jquery method that inserts the new data. before, after, append, prepend, etc. Default: before
  • data-association-insertion-position : old method specifying where to insert new data.
    • this setting still works but data-association-insertion-method takes precedence. may be removed in a future version.
  • partial - explicitly declare the name of the partial that will be used
  • render_options - options passed through to the form-builder function (e.g. simple_fields_for, semantic_fields_for or fields_for). If it contains a :locals option containing a hash, that is handed to the partial.
  • wrap_object - a proc that will allow to wrap your object, especially useful if you are using decorators (e.g. draper). See example lower.
  • force_non_association_create: if true, it will not create the new object using the association (see lower)
  • form_name - the name of the form parameter in your nested partial. By default this is f.

Optionally, you can omit the name and supply a block that is captured to render the link body. Used if you want to do something more complicated.

:render_options

Inside the html_options you can add an option :render_options, and the containing hash will be handed down to the form builder for the inserted form.

When using Twitter Bootstrap and SimpleForm together, simple_fields_for needs the option wrapper: 'inline' which can be handed down as follows:

(Note: In certain newer versions of simple_form, the option to use is wrapper: 'bootstrap'.)

= link_to_add_association 'add something', f, :something,
    render_options: { wrapper: 'inline' }

To specify locals that needed to handed down to the partial:

= link_to_add_association 'add something', f, :something,
    render_options: {locals: { sherlock: 'Holmes' }}

:partial

To override the default partial name, e.g. because it shared between multiple views:

= link_to_add_association 'add something', f, :something,
    partial: 'shared/something_fields'