Custom Form Builders

Now you can set a custom form builder that inherits from SimpleForm::FormBuilder:

class CustomBuilder < SimpleForm::FormBuilder
  def input(attribute_name, options={}, &block)
    options[:input_html].merge! :class => 'custom'
    super
  end
end

And use it straight in the simple_form_for helper, like the example below:

<%= simple_form_for(@user, :builder => CustomBuilder) do |f| %>
  <%= f.input :name %>
<% end %>

Custom Inputs

SimpleForm has many different inputs available in its source code. But, sometimes, depending on the business logic the application requires, we need to add new inputs to make our work easier. Before this version, you had to explicitly define your new input inside SimpleForm namespace for it to work. Furthermore, customizing existing SimpleForm inputs could only be achieved through monkey patching.

Inspired by a similar feature in the Formtastic gem, from now on you will be able to create new input types inside app/inputs folder in your application. The only restriction to create such inputs is that the class name must end with Input. See some examples:

# app/inputs/currency_input.rb
class CurrencyInput < SimpleForm::Inputs::StringInput
  def input
    "$ #{super}".html_safe
  end
end

And the usage:

f.input :money, :as => :currency

You can also redefine existing SimpleForm inputs by creating a new class with the same name. For instance, if you want to wrap date/time/datetime inputs in a div, you can do:

# app/inputs/date_time_input.rb
class DateTimeInput < SimpleForm::Inputs::DateTimeInput
  def input
    "
#{super}
".html_safe
  end
end

HTML 5

SimpleForm allows you to add many HTML 5 features to your applications, like placeholders, inline browser validations and more. The problem is: most browsers are still experimenting some HTML 5 features, and people started having lots of troubles with the automatic browser validation.

For this reason, SimpleForm now has an option to easily disable such form validations. You have to add this line to your SimpleForm initializer:

config.browser_validations = false

But, if HTML 5 is still not for you, you can disable all the HTML 5 stuff, by adding the configuration below to your initializer:

config.html5 = false

Notice that this option does not disable the `placeholder` component, because we believe this option is very well supported currently in mostly browsers. If you don't want to use it as well, just remove it from the `components` option in your initializer.

More Helpers

In this version we also add two new form helpers to SimpleForm: input_field and full_error.

The full_error helper shows errors in an attribute prepending its human name. This can be used when you want to show errors on hidden fields, for instance. You can see how it works in this example:

f.full_error :token #=> Token is invalid

The input_field helper renders only the input tag with all the facilities of SimpleForm's input helper. It means no wrapper, error or hint will be rendered. A good example of using this helper is inside an input block:

<%= f.input :max_time, :as => :integer do %>
  <%= f.input_field :max_time, :as => :integer, :type => :range %>
  <%= content_tag :span, '1', :id => 'max_time_value' %>
<% end %>

It will render:

  Max time *
  
  1

Wrapping up

This version allows you to do more customizations in SimpleForm based on your applications needs. We encourage you to take a look at the CHANGELOG and also review the README to see what else is available and some more examples.

And please, check out SimpleForm contributors, we want to thank everyone who is helping us to improve SimpleForm.

Right now, we are working on Rails 3.1 compatibility for the next version. If you feel like helping us or just want to see a new feature, feel free to send us a pull request. And last, but not least, we look forward to know how SimpleForm is changing your life. Is it being helpful? How does it improve your applications? Don't be shy, comments are welcome.

The post SimpleForm 1.4 is out first appeared on Plataformatec Blog.

HTML 5

One of the most useful features coming in HTML 5, in my opinion, is the placeholder option. This option allows us to configure a text to be shown inside the input when it is empty. This is really nice to help the user while filling out forms. SimpleForm now gives us the possibility to pass in a placeholder option in the same way we are used to do with use hints:

<%= simple_form_for @user do |f| %>
  <%= f.input :username, :label => 'Your username please' %>
  <%= f.input :password, :hint => 'No special characters.' %>
  <%= f.input :email, :placeholder => 'user@domain.com' %>
  <%= f.button :submit %>
<% end %>

As you can see here, the placeholder is given as String, but it can also be fetched from I18n, as labels/hints does.

Another addition is the automatic lookup of min/max values from numericality validations, for number inputs. For instance:

class User
  validates_numericality_of :age, :greater_than_or_equal_to => 18,
    :less_than_or_equal_to => 99, :only_integer => true
end

<%= simple_form_for @user do |f| %>
  <%= f.input :age %>
<% end %>

Would generate an input with type number, and the min/max attributes configured with 18 and 99, respectively.

Besides that SimpleForm also adds:

• the :required html attribute for required inputs (it is retrieved automatically from your presence validations);
• the :search and :tel input types, with :tel mapping automatically for attributes matching /phone/.

Collections

From now on, radio and check box collections will wrap the input element inside the label, making it pretty straightforward to associate both elements. Besides that, SimpleForm now comes with two new configurations:

• collection_wrapper_tag wraps the entire collection in the configured tag;
• item_wrapper_tag wraps each item in the collection using the configured tag.

An example:

<%= simple_form_for @user do |f| %>
  <%= f.association :roles, :as => :check_boxes, 
    :collection_wrapper_tag => :ul, :item_wrapper_tag => :li %>
<% end %>

This should be kind of self explanatory =).

New input options

It’s now possible to give the :disabled option straight to the input, which will also add the disabled css class to both input and wrapper elements:

<%= simple_form_for @user do |f| %>
  <%= f.input :email, :disabled => true %>
<% end %>

And also the :components option, which will only render the given components in the given order:

<%= simple_form_for @user do |f| %>
  # Generates the label after the input, and ignores errors/hints/placeholders
  <%= f.input :email, :components => [:input, :label] %>
<% end %>

New configuration options

If you are not using any label / hint / placeholder with I18n, you can now completely disable the translation lookup of these components by setting the config.translate to false in your SimpleForm initializer. This should improve performance a bit in these cases.

Another nice improvement is the ability to add custom input mappings to SimpleForm. If you ever needed to map a specific attribute to a default input, now you can:

  config.input_mappings = { /_count$/ => :integer }

This configuration expects a hash containing a regexp to match as key, and the input type that will be used when the field name matches the regexp as value. In this example we match all attributes ending with _count, such as comments_count, to be rendered as integer input by SimpleForm.

New docs and mailing list

SimpleForm now has its own google group where you can ask questions, search for already answered questions and also help others. Besides that, you can also navigate and search the entire RDoc.

Wrapping up

As you can see, there are plenty of new and cool stuff in this release. We encourage you to take a look at the CHANGELOG and also review the README to see what else is available and some more examples.

And please, check out SimpleForm contributors, we want to thank everyone who is helping us to improve SimpleForm.

What about you? Do you want any cool feature in SimpleForm? Help us improve it by forking and sending us a pull request, we will be really glad to apply it. We hope to see your name in the contributors page soon!

Finally, in your opinion, what is the coolest feature SimpleForm has? And what idea you have you might want to be added to SimpleForm? Feel free to comment

The post SimpleForm 1.3: more HTML 5 goodness and new stuff first appeared on Plataformatec Blog.