File: README — Documentation for form

FormCutter

The default rails form builder is great but it is so tedious to change the HTML that goes around it. This gem wraps your HTML around the form elements. So all you have to do is this:

<%= f.text_field :name %>

And add your HTML form helper template in app/views/forms/text_field.html.erb like this:

<div class="forms">
  <%= label(object_name, method, label_name) %><em><%= required %></em><br/>
  <%= text_field(object_name, method, options) %>
  <% if hint.present? %><p><%= hint %></p><% end %>
</div>

Installation

Install the gem:

gem install form_cutter

Add it to your Gemfile:

gem "form_cutter"

Run the generator:

rails generate form_cutter:install

Usage

Use the form builders normally, except don’t add any markup (unless you want to).

<%= form_for @post do |f| %>
  <fieldset>
    <%= f.text_field :title %>
    <%= f.text_area :body %>
    <%= f.select :section, ['choices'] %>
    <%= f.radio_button :am_fm, ['radio'] %>
    <%= f.check_box :terms_and_conditions %>
    <%= f.date_select :dob %>
    <%= f.time_select :check_in_time %>
    <%= f.datetime_select :updated_at %>
  </fieldset>
  <div class="buttons">
    <%= f.submit 'Save' %>
  </div>
<% end %>

The form builders will now wrap all form helper methods with your HTML.

You’re done.

Customization

There will always be an exception to the rule. So there are 2 ways to change the form helper HTML wrapper.

Like a resource - by creating a directory inside forms/, app/views/forms/blog/.
Passing the :template option - either false or the ‘path/to/template’.

The :template option

The :template option is useful if you have a field or group of fields that don’t work with your normal templates. There’s always one. This option tells the renderer to look for a specific HTML erb file or to look in a specific folder, if a file by that name doesn’t exist. Below is the order in which files will be found and rendered.

It will render the first erb template that it finds. For instance in this case of <%= f.text_field :title, :template => 'custom' %> for the @blog model, it looks in this order:

forms/blog/custom.html.erb
forms/custom.html.erb
forms/custom/title.html.erb
forms/custom/text_field.html.erb
forms/custom/default.html.erb
forms/blog/title.html.erb
forms/blog/text_field.html.erb
forms/text_field.html.erb
forms/default.html.erb

One more thing

You can pass :report => true and you get an instant view page.

This will search in app/views/reports/ instead of app/views/forms/.

<%= f.text_field(:title, :report => true) %>

In an admin or business data entry setting, this is useful to quickly get a “photocopy” of the completed form.

<%= form_for(@post, :template => true) do |form| %>
  <%= render 'form' %>
<% end %>

The :template or :report optons can be passed to form_for or fields_for and it will be applied to all helper methods within.

Other options

You can pass any options to the helper methods. These will become availble in the helper templates.

<%= f.text_field(:title, :hint => 'This is a field hint', :anything => 'anything you want') %>

Will give you:

<%= hint %>
=> 'This is a field hint'

<%= options[:anything] %>
=> 'anything you want'

note: in the anything case, the option will be added to the HTML output.

<input type="text" anything="anything you want">

FormCutter has several configuration values. You can read and change them in the initializer created by FormCutter, so if you haven’t executed the command below yet, please do:

rails generate form_cutter:install

TODO

Please refer to TODO file.

Maintainers

Benjamin Lewis (github.com/23inhouse)

Bugs and Feedback

If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.

github.com/23inhouse/form_cutter/issues