Make possible to use the Wrappers API to define attributes for the components

[rafaelfranca]

(This is a alternative solution to #622)

Motivation

To integrate Simple Form with Bootstrap 3 we need to make possible to define classes to input only in some wrappers.

We added input_class some time ago but that broke some components like checkboxes (see heartcombo/simple_form-bootstrap#28).

Instead of changing a global class to be applicated in every input we allow users to choose in which wrappers they want to define a class.

How to use

Now users can define attributes for the components in the component definition of the Wrappers API.

config.wrappers tag: 'div', class: 'control-group', error_class: 'error' do |b|
    b.use :label, class: 'form-label'
    b.use :input, class: 'form-input'
end

The class: 'form-label' option will be used every time a label component is rendered.

Implementation

To make this possible I had to change who the Wrappers API is defined and how components are rendered.

Wrapper API storage change

Before the work on this branch, the API components were stored in a mix of Simple Form classes and symbols.

This added some conditionals in our rendering code and made harder to store state in our components. This create a lot of code in Simple Form that rely in the fact that Ruby hashes are mutables and we have a global state. The implementation in #622 had this problem were the changes in a global hash make the hint and errors classes to getting duplicated.

I choose to avoid completely this problem storing the attributes in a class and making it implement the same protocol as SimpleForm::Wrappers::Many and SimpleForm::Wrapper::Single. This also make possible to remove some conditionals to deal with Symbols in the components tree.

Input rendering

Before this work, when rendering the input, there was no way to pass information about the context where it is being rendered. I changed the implementation to always pass the wrapper options for the component rendering method itself.

To understand better lets look how a custom input was implemented before:

class CustomInput < SimpleForm::Inputs::Base
  def input
    @builder.text_field(attribute_name, input_html_options)
  end
end

So when rendering a wrapper Simple Form will call the method input of that class. As you can see we don't have a clean way to get information about the wrapper that is being rendered inside that method.

Now, Simple Form will pass an argument wrapper_options that hold the options defined in the Wrappers API. So, for our previous example, wrapper_options will contain class: 'form-input'.

So, our custom input will look like:

class CustomInput < SimpleForm::Inputs::Base
  def input(wrapper_options)
    @builder.text_field(attribute_name, input_html_options)
  end
end

Now we can use a new helper merge_wrapper_options to merge the options present in the form.input call and the options defined in the wrapper.

Finally, our custom input will look like:

class CustomInput < SimpleForm::Inputs::Base
  def input(wrapper_options)
    @builder.text_field(attribute_name, merge_wrapper_options(input_html_options, wrapper_options))
  end
end

Deprecations

The custom input/custom components methods now have to accept one argument with the wrapper options. The inputs/components defined using the old API will work but with a deprecation message.

These examples are deprecated:

class CustomInput < SimpleForm::Inputs::Base
  def input
  end

  def label
  end

  def hint
  end

  def label_input
  end

  def error
  end

  def placeholder
  end
end

To fix the deprecation message use:

class CustomInput < SimpleForm::Inputs::Base
  def input(wrapper_options)
  end

  def label(wrapper_options)
  end

  def hint(wrapper_options)
  end

  def label_input(wrapper_options)
  end

  def error(wrapper_options)
  end

  def placeholder(wrapper_options)
  end
end

Next steps

• Add proper documentation
• Test this new feature writing the wrappers for Bootstrap 3

Closes #622

[rafaelfranca]

This argument=values was the guideline in Simple Form for a while but I prefer to change it now since it is not consistent anymore

[lucasmazza]

❤️

[georgeguimaraes]

I'd like spaces here too

[josevalim]

❤️ 💚 💙 💛 💜

[lucasmazza]

It took me a while to figure out that the context object that will be passed to the components was an instance of this class - dunno if matching names or something like that could make this more straightforward.

[josevalim]

I wonder if it would be best to simply pass the options?

[rafaelfranca]

I thought that too. I was more thinking about the future if we need to pass more things, but I think we will not need it in the near feature.

[josevalim]

There are some docs here that need to be updated: https://github.com/plataformatec/simple_form/blob/rm-wrapper-classes/lib/simple_form/wrappers/many.rb#L3-L4

I saw them when checking if we could rename Many to Node but I think Many is a better name?

[lucasmazza]

dunno if we need a module just for this method. Pushing it to SimpleForm::Inputs::Base is an option?

[rafaelfranca]

It is, but I don't see problem to extract to a module.

I'm removing because helpers are related to the HTML attributes and this one is not related to any attribute at all.

[rafaelfranca]

@josevalim Simple and Many are both Nodes, so I think we can't change that. Actually the name Leaf is what I'd choose to change, but I could not came with another name.

[AndreLZGava]

Hello, can anyone help me I'm still learning rails and was trying to create a input to accept datepicker-bootstrap, I found this tutorial https://github.com/plataformatec/simple_form/wiki/Custom-inputs-examples, I createad as it was declared and worked for a form but when I load another don't, in my terminal I found the reason, that must be this issue and this deprecated, can you help me about this broblem?