Skip to content

Commit

Permalink
Rewriting README
Browse files Browse the repository at this point in the history
  • Loading branch information
Nicholas Firth-McCoy committed Aug 31, 2011
1 parent a057b87 commit c8f9f8d
Showing 1 changed file with 96 additions and 40 deletions.
136 changes: 96 additions & 40 deletions README.md
View file
@@ -1,12 +1,19 @@
better_form Readme
==================

A Rails 3 gem to build DRY forms with Javascript validation.
A better Rails 3 FormBuilder.

* Javascript validates form fields as they are completed, using your `ActiveModel` validators
* Well-placed validation output
* Automatic label generation
* Form field descriptions
Features:

* Uses partials to put you in control of templating your form fields
* Free Javascript validation using the same validations you specify in your models
* Out of the box support for common cases; fully customizeable if that's how you roll

Why should I use `better_form` over `formtastic` or `simple_form`?

* No DSL; just use the default Rails form helpers
* No fixed ideas about what options or output you want for your fields
* Less features, less code, less complexity; you get DRY fields with DRY validators and nothing more

Links
=====
Expand All @@ -18,44 +25,113 @@ Links
Installation and Usage
======================

Add `better_form` to your Gemfile:
Add `better_form` to your Gemfile and run `bundle install`.

Generate the required initializer and boilerplate form field partial:

rails generate better_form

Use the `better_form_for` method to create a better form, and add fields using the default Rails form helpers.

Customizing your form fields
============================

Modify the generated form field partial in `app/views/better_form/_field.html.erb`. Or, create your own from scratch using whatever templating engine you prefer - it's just a regular partial.

A few ideas to get you in the mood:

# Epic error messages
<%= field[:field] %>
<%= error_messages.each do |message| %>
<h1 class="fail">OH NOES! <%= message %></h1>
<% end %>

# Floated field descriptions
<div class="form_field">
<%= field[:field] %>
<div class="description float-right"><%= field[:description] -%></div>
</div>

# All the bells and whistles
<div class="better_form_field <%= 'invalid' if error_messages %>">
<div class="field">
<% if field[:prefix] %>
<span class="field_prefix"><%= field[:prefix] %></span>
<% end %>
<%= field[:field] %>
<% if field[:suffix] %>
<span class="field_suffix"><%= field[:suffix] %></span>
<% end %>
<% if field[:description] %>
<br>
<span class="field_description"><%= field[:description] %></span>
<% end %>
</div>
<%= if error_messages %>
<span class="error_header">Oops!</span>
<div class="field_errors">
<%= error_messages.each do |message| %>
<p class="error_message">
<%= image_tag('warning_small') %>
<%= message %>
</p>
<% end %>
</div>
</div>
</div>

Have a look at `app/views/better_form/_field.html.erb` to get started.

Built-in options
================

gem 'better_form'
Validations
-----------

And run the usual `bundle install`.
Fields can automatically have validation data generated for them using the validations defined in your models:

Use the `better_form_for` method to create a better form:
class User < ActiveRecord::Base
validates :name, :presence => true
end

= better_form_for @user do |f|
<%= f.text_field :name %>

Create fields using the usual Rails methods:
<label for='user_name'>What shall we call you?</label>
<input type='text' id='user_name' name='user[name]' data-validates-presence="Name is required" />

= f.text_field :name
= f.email_field :email
= f.password_field :password
Setting a custom error message will be reflected in the validation that is generated:

validates :name, :presence => { :message => 'Please enter your full name' }

<input type='text' id='user_name' name='user[name]' data-validates-presence="Please enter your full name" />

Validations are enabled by default. They can be enabled or disabled for a form, or for particular fields:

# Don't generate validations for this form, unless instructed to for specific fields
<%= better_form_for @user, :validate => false do |f| %>
<%= f.text_field :name %>
<%= f.text_field :password, :validate => true %>

Labels
------

Fields will automatically have labels generated for them, with the label text defaulting to the attribute that the field is for:
Fields can automatically have label text generated for them, with the label text defaulting to the attribute that the field is for:

= f.text_field :name
<%= f.text_field :name %>

<label for='user_name'>Name</label>
<input type='text' id='user_name' name='user[name]' />

To specify your own label text, pass a string as the `:label` option:

= f.text_field :name, :label => "What shall we call you?"
<%= f.text_field :name, :label => "What shall we call you?" %>

<label for='user_name'>What shall we call you?</label>
<input type='text' id='user_name' name='user[name]' />

To skip label generation for a specific field, pass `false` as the `:label` option:

= f.text_field :name, :label => false

<input type='text' id='user_name' name='user[name]' />
<%= f.text_field :name, :label => false %>

You can set the default for the entire form in the same way. Field-level `:label` options will override the default value. For example:

Expand All @@ -72,23 +148,3 @@ You can set the default for the entire form in the same way. Field-level `:label

<label for='user_password'>Pick a strong password</label>
<input type='password' id='user_password' name='user[password]' />

Validations
-----------

Fields will automatically have validation data generated for them using the validations defined in your models:

class User < ActiveRecord::Base
validates :name, :presence => true
end

= f.text_field :name

<label for='user_name'>What shall we call you?</label>
<input type='text' id='user_name' name='user[name]' data-validates-presence="Name is required" />

Setting a custom error message will be reflected in the validation that is generated:

validates :name, :presence => { :message => 'Please enter your full name' }

<input type='text' id='user_name' name='user[name]' data-validates-presence="Please enter your full name" />

0 comments on commit c8f9f8d

Please sign in to comment.