twitter_bootstrap_formalwear 0.9.1

data/LICENSE.markdown

@@ -0,0 +1,22 @@
+The MIT License
+===============
+
+Copyright (C) 2011 by Stephen Touset
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,142 @@
+Twitter Bootstrap Formalwear
+============================
+
+Twitter Bootstrap Formalwear dresses up your Ruby on Rails forms with
+[Twitter Bootstrap] markup. It is a lightly-modified fork of
+[`twitter_bootstrap_form_for`](https://github.com/stouset/twitter_bootstrap_form_for).
+
+Unlike `twitter_bootstrap_form_for`, which overwrites existing [Rails FormHelper] methods,
+`twitter_bootstrap_formalwear` extends FormHelper with additional methods to generate
+labels, controls, control groups, and action blocks.
+
+Because existing methods remain intact, you maintain the option to generate
+non-Bootstrap markup in your form if necessary.
+
+
+## Dependencies ##
+
+Rails and Twitter Bootstrap (v2.0+), of course. A familiarity with Rails FormHelper
+usage and syntax will be helpful.
+
+
+## Installation ##
+
+Add the dependency to your `Gemfile`:
+
+    gem 'twitter_bootstrap_formalwear'
+
+Then run `bundle` from the project directory.
+
+
+## Usage/Syntax ##
+
+
+### Initializing a Form: ###
+
+To use `twitter_bootstrap_formalwear`, first create a form using the same syntax as `form_for` or `fields_for`:
+
+    <%= formalwear_form_for (@person, :html => { :class => 'form-horizontal' }) do |f| %>
+
+    <%= formalwear_fields_for (:person, @client do |f| %>
+
+
+### Generating Form Elements: ###
+
+`twitter_bootstrap_formalwear` extends `form_for` and `fields_for` with additional methods:
+
+- group
+- label
+- controls
+- actions
+
+These methods can be used generically to create container elements:
+
+    <%= f.group do %>
+        <!-- HTML goes here! -->
+    <% end %>
+
+    # =>
+    <div class="control-group">
+        <!-- HTML goes here! -->
+    </div>
+
+Or, more usefully, they can be prepended with a form element (of any type supported by the [Rails FormHelper]):
+
+    <%= f.text_field_group :first_name, :class => 'input-large' %>
+
+    # =>
+    <div class="control-group">
+        <label class="control-label" for="first_name">First name</label>
+        <div class="controls">
+            <input type="text" name="first_name" value="" class="input-large" />
+        </div>
+    </div>
+
+If you need fine-grained control, you can generate only a Bootstrap label:
+
+    <%= f.text_field_label :first_name %>
+
+    # =>
+    <label class="control-label" for="first_name">First name</label>
+
+...or a Bootstrap control:
+
+    <%= f.text_field_control :first_name, :class => 'input-large' %>
+
+    # =>
+    <div class="controls">
+        <input type="text" name="first_name" value="" class="input-large" />
+    </div>
+
+For you control freaks, the standard Rails FormHelper methods still work if needed:
+
+    <%= f.text_field :first_name, :class => 'input-large' %>
+
+    # =>
+    <input type="text" name="first_name" value="" class="input-large" />
+
+
+### More Usage Examples ###
+
+Form actions:
+
+    <%= f.actions do %>
+       <%= f.submit 'Sign up', :class => 'btn' %>
+    <% end %>
+    
+    # =>
+    <div class="form-actions">
+        <input class="btn" type="submit" value="Sign up">
+    </div>
+    
+Checkboxes (note that omitting the first argument will omit the label element):
+
+    <%= f.group do %>
+        <%= f.check_box :remember_me %> Remember Me?
+    <% end %>
+
+    # =>
+    <div class="control-group">
+        <div class="controls">
+            <input id="remember_me" name="remember_me" type="checkbox" value="1" /> Remember Me?
+        </div>
+    </div>
+
+Add-ons and form help text: may or may not work yet. Documentation coming soon.
+
+## Bugs / Known Issues ##
+
+You may have already noticed that the `label` method exists in `form_for`, even
+though I claim above that `twitter_bootstrap_formalwear` doesn't overwrite existing
+code. But since the new method dances so lightly (just adding `class="control-label"`),
+I think it's safe to simply overwrite the old method. Thoughts?
+
+I've been using this fork successfully on my own projects, but some less common
+use cases may be buggy.
+
+## Todo ##
+
+Tests!
+
+[Twitter Bootstrap]: http://twitter.github.com/bootstrap/
+[Rails FormHelper]: http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'TwitterBootstrapFormalwear'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/tasks/twitter_bootstrap_formalwear_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :twitter_bootstrap_formalwear do
+#   # Task goes here
+# end

data/lib/twitter_bootstrap_formalwear.rb

@@ -0,0 +1,10 @@
+require 'action_view'
+
+module TwitterBootstrapFormalwear
+  autoload :FormBuilder, 'twitter_bootstrap_formalwear/form_builder'
+  autoload :FormHelpers, 'twitter_bootstrap_formalwear/form_helpers'
+  autoload :Railtie,     'twitter_bootstrap_formalwear/railtie'
+  autoload :VERSION,     'twitter_bootstrap_formalwear/version'
+end
+
+TwitterBootstrapFormalwear::Railtie # trigger loading the Railtie

data/lib/twitter_bootstrap_formalwear/form_builder.rb

@@ -0,0 +1,256 @@
+require 'twitter_bootstrap_formalwear'
+require 'action_view/helpers'
+
+class TwitterBootstrapFormalwear::FormBuilder < ActionView::Helpers::FormBuilder
+  include TwitterBootstrapFormalwear::FormHelpers
+
+  attr_reader :template
+  attr_reader :object
+  attr_reader :object_name
+
+  INPUTS = [
+    :check_box,
+    :radio_button,
+    :select,
+    *ActionView::Helpers::FormBuilder.instance_methods.grep(%r{
+      _(area|field|select)$ # all area, field, and select methods
+    }mx).map(&:to_sym)
+  ]
+
+  INPUTS.delete(:hidden_field)
+
+  #TOGGLES = [
+  #  :check_box,
+  #  :radio_button,
+  #]
+
+  #
+  # Wraps the contents of the block passed in a fieldset with optional
+  # +legend+ text.
+  #
+  def fieldset(legend = nil, options = {})
+    template.content_tag(:fieldset, options) do
+      template.concat template.content_tag(:legend, legend) unless legend.nil?
+      yield
+    end
+  end
+
+  #
+  # Wraps action buttons into their own styled container.
+  #
+  def actions(&block)
+    template.content_tag(:div, :class => 'form-actions', &block)
+  end
+
+  #
+  # Generates a control-group div element for the given +attribute+,
+  # containing label and controls elements.
+  #
+  def group(attribute = '', text = '', options = {}, &block)
+    text, attribute = attribute, nil if attribute.kind_of? String
+
+    id      = _wrapper_id      attribute, 'control_group'
+    classes = _wrapper_classes attribute, 'control-group'
+
+    template.content_tag(:div, :id => id, :class => classes) do
+      if !attribute.blank?
+        template.concat self.label(attribute, text, options, &block)
+      end
+      template.concat self.controls(attribute, text, options, &block)
+    end
+  end
+
+  #
+  # Generates a label element for the given +attribute+. If +text+ is passed, uses
+  # that as the text for the label; otherwise humanizes the +attribute+ name.
+  #
+  def label(attribute, text = '', options = {}, &block)
+    text, attribute = attribute, nil if attribute.kind_of? String
+
+    options = options.merge(:class => 'control-label')
+
+    case
+      when attribute && text then super(attribute, text, options, &nil)
+      when attribute         then super(attribute, nil,  options, &nil)
+      when text              then template.label_tag(nil, text, options, &nil)
+    end
+  end
+
+  #
+  # Generates a controls div element for the given +attribute+.
+  #
+  def controls(attribute, text = '', options = {}, &block)
+    text, attribute = attribute, nil if attribute.kind_of? String
+
+    template.content_tag(:div, :class => 'controls') {
+      template.fields_for(
+        self.object_name,
+        self.object,
+        self.options.merge(:builder => TwitterBootstrapFormalwear::FormControls),
+        &block
+      )
+    }
+  end
+
+  #
+  # Renders a button with default classes to style it as a form button.
+  #
+  def button(value = nil, options = {})
+    super value, {
+      :type  => 'button',
+      :class => 'btn',
+    }.merge(options)
+  end
+
+  #
+  # Renders a submit tag with default classes to style it as a primary form
+  # button.
+  #
+  def submit(value = nil, options = {})
+    self.button value, {
+      :type  => 'submit',
+      :class => 'btn btn-primary',
+    }.merge(options)
+  end
+
+  INPUTS.each do |input|
+    define_method input.to_s + '_group' do |attribute, *args, &block|
+      options = args.extract_options!
+      text    = args.any? ? args.shift : ''
+
+      self.group(attribute, text, options) do |builder|
+        builder.send(input, attribute, *(args << options), &block)
+      end
+    end
+
+    define_method input.to_s + '_label' do |attribute, *args, &block|
+      options = args.extract_options!
+      text    = args.any? ? args.shift : ''
+
+      self.label(attribute, text, options) do |builder|
+        builder.send(input, attribute, *(args << options), &block)
+      end
+    end
+
+    define_method input.to_s + '_controls' do |attribute, *args, &block|
+      options = args.extract_options!
+      text    = args.any? ? args.shift : ''
+
+      self.controls(attribute, text, options) do |builder|
+        builder.send(input, attribute, *(args << options), &block)
+      end
+    end
+  end
+
+  protected
+
+  def errors_on?(attribute)
+    self.object.errors[attribute].present? if self.object.respond_to?(:errors)
+  end
+
+  private
+
+  #
+  # Returns an HTML id to uniquely identify the markup around an input field.
+  #
+  def _wrapper_id(attribute, suffix = nil)
+    [
+      _object_name + _object_index,
+      _attribute_name(attribute),
+      suffix,
+     ].compact.join('_') if attribute
+  end
+
+  #
+  # Returns any classes necessary for the wrapper div around fields for
+  # +attribute+, such as 'errors' if any errors are present on the attribute.
+  # Merges any +classes+ passed in.
+  #
+  def _wrapper_classes(attribute, *classes)
+    classes.push 'error' if attribute and self.errors_on?(attribute)
+    classes.compact.join(' ')
+  end
+
+  def _attribute_name(attribute)
+    attribute.to_s.gsub(/[\?\/\-]$/, '')
+  end
+
+  def _object_name
+    self.object_name.to_s.gsub(/\]\[|[^-a-zA-Z0-9:.]/, "_").sub(/_$/, "")
+  end
+
+  def _object_index
+    case
+      when options.has_key?(:index) then options[:index]
+      when defined?(@auto_index)    then @auto_index
+      else                               nil
+    end.to_s
+  end
+end
+
+class TwitterBootstrapFormalwear::FormControls < ActionView::Helpers::FormBuilder
+  attr_reader :template
+  attr_reader :object
+  attr_reader :object_name
+
+  TwitterBootstrapFormalwear::FormBuilder::INPUTS.each do |input|
+    define_method input do |attribute, *args, &block|
+      options = args.extract_options!
+      add_on  = options.delete(:add_on)
+      tag     = add_on.present? ? :div : :span
+      classes = [ "input", add_on ].compact.join('-')
+
+      template.content_tag(tag, :class => classes) do
+        template.concat super attribute, *(args << options)
+        template.concat self.error_span(attribute) if self.errors_on?(attribute)
+        block.call if block.present?
+      end
+    end
+  end
+
+=begin
+  def check_box(attribute, text, options = {}, checked_value = 1, unchecked_value = 0)
+    klasses = _merge_classes 'checkbox', options.delete(:inline) && 'inline'
+
+    self.label(attribute, :class => klasses) do
+      template.concat super(attribute, options, checked_value, unchecked_value)
+      template.concat text
+      yield if block_given?
+    end
+  end
+
+  def radio_button(attribute, value, text = nil, options = {})
+    klasses = _merge_classes 'radio', options.delete(:inline) && 'inline'
+
+    self.label(attribute, :class => klasses) do
+      template.concat super(attribute, value, options)
+      template.concat text || value.to_s.humanize.titleize
+      yield if block_given?
+    end
+  end
+=end
+
+  protected
+
+  def error_span(attribute, options = {})
+    options[:class] = _merge_classes options[:class], 'help-inline'
+
+    template.content_tag :span,
+      self.errors_for(attribute),
+      :class => options[:class]
+  end
+
+  def errors_for(attribute)
+    self.object.errors[attribute].try(:join, ', ')
+  end
+
+  def errors_on?(attribute)
+    self.object.errors[attribute].present? if self.object.respond_to?(:errors)
+  end
+
+  private
+
+  def _merge_classes(string, *classes)
+    string.to_s.split(' ').push(*classes.compact).join(' ')
+  end
+end