README

SemanticFormBuilder
===================

Installation
============

To install, simply add a clone of the git repository to the vendor/plugins directory

  $ cd /path/to/rails/app
  $ git clone git://github.com/nesquena/semantic_form_builder.git vendor/plugins/semantic_form_builder

Overview
========

This plugin is a standardized form builder which works to create semantically correct forms, each field with the 
appropriate label and wrapped within a definition list item in order to represent a list of items using proper xhtml markup. 
Works with Rails 1.X as well as 2.X, including 2.2.2

  The tags allowed are as follows:

  * fieldset(name:string, &block) - wraps the rest of the form items in a definition list
  * text_field      (attribute:symbol, options_hash:hash)
  * password_field  (attribute:symbol, options_hash:hash)
  * file_field      (attribute:symbol, options_hash:hash)
  * text_area       (attribute:symbol, options_hash:hash)
  * check_box       (attribute:symbol, options_hash:hash)
  * radio_buttons   (attribute:symbol, options_hash:hash)
  * submit_button   (label:string)   - create a submit button in a definition item
  * image_submit_button (src:string) - create an image submit button in a definition item
  
These methods can be used within the context of a form builder or within any form as simple helper tags:

  * semantic_form_for         [ model-backed forms ]
  * semantic_remote_form_for  [ remote model-backed forms ]
  * semantic_fields_for       [ model-backed fields ]
  * semantic_fieldset_tag     [ non-model-backed forms ]

Example
=======

This form builder is rather easy to use as the example illustrates:

  - semantic_form_for :user, :url => users_path do |f|
    - f.fieldset 'Register' do
      = f.text_field      :login,                 :label => 'Login'
      = f.text_field      :email,                 :label => 'Email'
      = f.password_field  :password,              :label => 'Password'
      = f.password_field  :password_confirmation, :label => 'Password Confirmation'
      = f.submit_button   'Sign up'  

  which generates the following semantically valid markup:
  
  <form method="post" action="/users">
    <fieldset>
      <legend>Register</legend>
      <dl class = "semantic-form">
        <dt><label for="user_login">Login:</label></dt>
        <dd><input type="text" size="30" name="user[login]" id="user_login"/></dd>
  
        <dt><label for="user_email">Email:</label></dt>
        <dd><input type="text" size="30" name="user[email]" id="user_email"/></dd>
  
        <dt><label for="user_password">Password:</label></dt>
        <dd><input type="password" size="30" name="user[password]" id="user_password"/></dd>
  
        <dt><label for="user_password_confirmation">Password Confirmation:</label></dt>
        <dd><input type="password" size="30" name="user[password_confirmation]" id="user_password_confirmation"/></dd>
  
        <dt class="button"/>
        <dd class="button"><input type="submit" value="Sign up" name="commit"/></dd>
      </dl>
    </fieldset> 
  </form>

Other Examples
==============

Non-Model Backed Form
  
  - form_tag some_url do
    - semantic_fieldset_tag "Name" do |f|
      = f.text_field_tag     :username, :label => "Username"
      = f.password_field_tag :password, :label => "Password"
      = f.check_box_tag      :is_admin, :label => "Administrator?"
      = f.select_tag         :category, @option_values
      = f.submit_tag "Submit"
      
Remote Model Backed Form
  
  - semantic_remote_form_for :user, :url => register_url do |u|
      - u.fieldset do
        = u.text_field     "login"
        = u.password_field "password"
        = u.text_field     "email"
        = u.text_field     "mobile_number", :label => "Mobile No"
        = u.password_field "invite_code", :label => 'Invite'
        = u.submit_button
  
Copyright (c) 2008 Nathan Esquenazi, released under the MIT license