PadrinoFields

Forms made easy for the Padrino Framework

Takes the pain out of building forms. Generates inputs, labels and field hints with a minimal and flexible DSL. Currently only supports DataMapper and ActiveRecord, but plugging more ORMs in will be trivial due to modular design (see below).

Installation

Install the gem:

gem install padrino-fields

Add it to your Gemfile:

gem "padrino-fields"

Initialize it in your app.rb

register PadrinoFields

set :default_builder, 'PadrinoFieldsBuilder'

Usage

The heart of PadrinoFields is the :input method

- form_for @user do |f|
  = f.input :username
  = f.input :password
  = f.submit

This will generate a form with labels for username and password - supplying the appropriate inputs, labels and error messages on missing/invalid fields. PadrinoFields looks at your database columns to generate default inputs.

Field Customization

Override the default input type like so:

= f.input :description, :as => :text
= f.input :joined_on,   :as => :string
= f.accept_terms,       :as => :boolean

Add custom label text, field hints and more:

= f.input :username, :caption => 'You will login with this name'
= f.input :password, :hint => 'Letters and numbers only'

Disable labels, hints or errors:

= f.input :username, :caption => false
= f.input :password, :hint => false
= f.input :email,    :disabled => true

Pass html attribute straight to the input:

= f.input :username,    :input_html => { :class => 'special' }
= f.input :password,    :input_html => { :maxlength => 20 }
= f.input :remember_me, :input_html => { :value => '1' }

Options / Collections

Options can be arrays or ranges, and when a :options is given the :select input will be rendered by default, so we don't need to pass the :as => :select option.

= f.input :user, :options => User.all.map(&:name)

Use ranges as options for your select tags

= f.input :year, :options => (1950..Time.now.year)

Options may also be rendered as :radios and :checkboxes

= f.input :user, :options => User.all.map(&:name), :as => :radios

You can produce optgroups using :grouped_options

# Using a Hash
options = {
  "Friends" => ["Yoda","Obiwan"],
  "Enemies" => ["Palpatine","Darth Vader"]
}

# Using an Array
options = [
  ["Friends",["Yoda","Obiwan"],
  ["Enemies", ["Palpatine","Darth Vader"]]
]

= f.input :user, :grouped_options => options

Available Inputs

Mapping	Input	Column Type
:boolean	check box	boolean
:string	text field	string
:email	email field	string with name matching "email"
:url	url field	string with name matching "url"
:tel	tel field	string with name matching "phone"
:password	password field	string with name matching "password"
:search	search	string with name matching "search"
:text	text area	text
:file	file field	string, responding to file methods
:number	number field	integer, float, decimal
:date	date field	date, datetime, timestamps
:select	select	-
:radios	radio buttons	-
:checkboxes	check boxes	-

Validations

By default all inputs are optional. PadrinoFields looks at your model validations to see if a field's presence is required and will mark it by prepending a * to the label.

# app/models/person.rb
class Person
  validates_presence_of :name

# app/views/people/_form.haml
= f.input :name

=> <label><abbr>*<abbr>Name</label><input ...

You can also do it manually with the :required option

= f.input :email, :required => true

Note that if you use ActiveRecord, you will need to include gem 'validation_reflection' in your Gemfile in order for this feature to work.

Settings

You can override a few default settings by creating a lib file as follows:

PadrinoFields::Settings.configure do |config|
  
  config.container = :p
  # Tag which wraps the inputs and labels
  
  config.label_required_marker = "<abbr>*</abbr>"
  # Visual indicator of a required field
  
  config.label_required_marker_position = :prepend
  # Placement of marker, either :append or :prepend (default)
  
end

ORM Support

So far only Datamapper and ActiveRecord are supported, but since the code is decoupled it should be relatively easy to support others:

1. Clone padrino-fields/orms/datamapper.rb and extend your ORM in a similar fashion
2. Clone test/fixtures/datamapper and substitute the models with your ORM
3. Clone test/test_datamapper.rb to write tests
4. Open lib/padrino-fields/form_builder.rb

Require your orm file and include its module as follows:

require File.expand_path(File.dirname(__FILE__) + '/orms/mycoolorm') if defined?(MyCoolOrm)

module Padrino
  module Helpers
    module FormBuilder
      class PadrinoFields < AbstractFormBuilder #:nodoc:
    
        include PadrinoFields::MyCoolOrm if defined?(MyCoolOrm)

Todo

• Add country select
• Generators for config and views
• I18n integration
• More documentation

Bug reports

If you discover any bugs, feel free to create an issue on GitHub. Please add as much information as possible to help us fix the problem. You can be an even bigger help by forking and sending a pull request. Be sure to include tests with your code!

http://github.com/activestylus/padrino-field/issues

Credit

This gem borrows heavily from the following projects:

• Formtastic
• SimpleForm

Many thanks to Justin French and Jose Valim for the inspiration. Extra shouts to Nathan Esquenazi and Davide d'Agostino for lending a hand on the google group

License

MIT License. Copyright 2011 Steven Garcia