bootstrap-view-helpers 0.0.3 → 0.0.4

data/README.md

@@ -4,16 +4,28 @@ This gem provides helper methods for various Bootstrap components.
 
 Includes support for:
 
+  * navigation
+    * nav bar
+    * nav list
   * buttons
     * `<button>`
     * `<a>` styled as button
+  * button groups
+  * button toolbars
   * labels and badges
   * dropdowns
     * nav dropdowns
     * button dropdowns
     * split-button dropdowns
   * accordion
+  * form helpers
+    * submit_tag_button 
   
+## Note
+
+This is a new gem undergoing a lot of change.  There is a chance that some backwards
+compatibility will be broken until things settle down.  
+
 ## Installation
 
 Add it to your Gemfile:
@@ -28,25 +40,93 @@ Run bundler:
 bundle install
 ```
 
+## API Documentation
+
+Complete [API documentation](http://rubydoc.info/gems/bootstrap-view-helpers/frames/file/README.md) at [RubyGems.org](https://rubygems.org/).
+
 ## Examples
 
-### Badges
+### Navigation
 
-Supports the Bootstrap badge types: 
-  * default
-  * success
-  * warning
-  * important
-  * info
-  * inverse
-  
+#### Navigation Bar
+```
+<%= nav_bar do %>      
+
+  <%= brand('Span Brand')%>
+  <%= brand('Link Brand', url: '#')%>
+
+  <%= nav_bar_links do %>
+
+    <%= nav_bar_link('Active', '#', active: true) %>
+    <%= nav_bar_link('Link1', '/link1') %>
+
+    <%= nav_bar_divider %>
+
+    <%= nav_dropdown('Foo') do %>
+      <%= dropdown_item('One', 'foo')%>
+    <% end %>
+
+     <% end %>
+   <% end %>
+```
+
+#### Navigation List (sidebar)
 ```erb
-<%= badge('Default') %>
-<%= badge('Info', :info) %>
-<%= badge('Warning', :warning, id: 'warn-id', class: 'more-class', my_key: 'my_value') %>
+<%= nav_list(id: 'my') do %>
+  <%= nav_list_header('Buttons & Labels') %>
+  <%= dropdown_item('Buttons', 'butons')%>
+  <%= dropdown_item('Labels', 'butons')%>
+<% end %>
+```
+
+### Buttons
+
+```ruby
+# button
+button('Default')
+
+# add url option to make <a> styled as button
+button('Home', url: '/')
+
+# a button styled as a link
+button('Home', :link)
+
+# give it a type; see BUTTON_TYPES
+button('Info', :info)
+
+# give it a size (see BUTTON_SIZES)
+button('Small', :small)
+
+# size, type, additional class and additional html attributes
+button('Warning', :warning, :large, id: 'warn-id', class: 'more-class', my_key: 'my_value')
+```
+
+### Button Groups
+
+```erb
+<%= button_group do %>
+  <%= button("Left", url: "/left") %>
+  <%= button("Right", id: 'right') %>
+<% end %>
+```
+
+### Button Toolbars
+
+```erb
+<%= button_toolbar do %>
+  <%= button('Single Button', url: '/single') %>
+  <%= button_group do %>
+    <%= button('Group Button 1') %>
+    <%= button('Group Button 2') %>
+  <% end %>
+  <%= button('Another Single') %>
+<% end %>
 ```
+### Labels and Badges
 
-### Labels (Stamps)
+http://twitter.github.io/bootstrap/components.html#labels-badges
+
+#### Labels (Stamps)
 
 Because `label` is a Rails helper method we use `stamp` -- because Elle thinks it looks like a stamp.
 
@@ -63,4 +143,55 @@ Supports the Bootstrap label types:
 <%= stamp('Info', :info) %>
 <%= stamp('Warning', :warning, id: 'warn-id', class: 'more-class', my_key: 'my_value') %>
 ```
+
+#### Badges
+Supports the Bootstrap badge types: 
+  * default
+  * success
+  * warning
+  * important
+  * info
+  * inverse
+  
+```erb
+<%= badge('Default') %>
+<%= badge('Info', :info) %>
+<%= badge('Warning', :warning, id: 'warn-id', class: 'more-class', my_key: 'my_value') %>
+```
+
+
+### Accordions
+
+See: http://twitter.github.io/bootstrap/javascript.html#collapse
+
+```erb
+<%= accordion do %>
+
+  <%= accordion_group('Section 1', open: true) do %>
+    content for group 1
+  <% end >
+
+  <%= accordion_group('Section 1') do %>
+    content for group 2
+  <% end %>
+
+<% end %>
+```
+
+### Form Helpers
+
+#### submit_tag_button
+
+Returns <input> similar to +#submit_tag()+ but:
+  * styled like a Bootstrap button, type `:primary`
+  * has `:disable_with` set to "Processing ..."
   
+```ruby
+submit_button_tag   # => <input class="btn btn-primary" data-disable-with="Processing ..." name="commit" type="submit" value="Save changes" />
+submit_button_tag('Save')
+submit_button_tag('Delete', :danger)
+submit_button_tag('Big', :large)
+submit_button_tag('With Options', :small, :info, id: 'my-id')
+```
+
+

data/app/helpers/bootstrap/accordion_helper.rb

@@ -1,6 +1,29 @@
+# Rails helpers for building Bootstrap accordions.
+#
+# See: http://twitter.github.io/bootstrap/javascript.html#collapse
+#
+#   <%= accordion do %>
+#
+#     <%= accordion_group('Section 1', open: true) do %>
+#       content for group 1
+#     <% end >
+#
+#     <%= accordion_group('Section 1') do %>
+#       content for group 2
+#     <% end %>
+#
+#   <% end %>
+#
 module Bootstrap::AccordionHelper
   
+  # Returns the outer html for a Bootstrap accordion.
+  #
+  # @param [Hash] options html attributes for accordion <div>
+  # @return [String] accordion html
+  # @yield Should contain calls to {Bootstrap::AccordionHelper#accordion_group}
+  # @yieldreturn [String] Html from {Bootstrap::AccordionHelper#accordion_group} calls
   def accordion(options={})
+    options = canonicalize_options(options)
     options = ensure_accordion_id(options)
     @accordion_id = options[:id]
     options = ensure_class(options, 'accordion')
@@ -10,12 +33,23 @@ module Bootstrap::AccordionHelper
     end
   end
   
+  # Returns the html for a Bootstrap accordion group.
+  # 
+  # @param [String] text the text in the accordion group header
+  # @param [Hash] options All keys except +:open+ become html attributes for the accordion group
+  # @option options [true] :open Set to +true+ if you want this group initially open
+  # @yield Html contents of accordion group
+  # @yieldreturn [String] Html for accordion group contents
   def accordion_group(text, options={})
+    options = canonicalize_options(options)
+    open = options.delete(:open)
+
     options = ensure_accordion_group_id(options)
     @accordion_group_id = options[:id]
-    open = options.delete(:open)
+
+    options = ensure_class(options, 'accordion-group')
     
-    content_tag(:div, class: 'accordion-group') do
+    content_tag(:div, options) do
       accordion_group_heading(text) + accordion_group_body(open) { yield }
     end
   end

data/app/helpers/bootstrap/badge_helper.rb

@@ -1,17 +1,14 @@
+# Rails helper for producing Twitter Bootstrap badges
+#
 # See: http://twitter.github.io/bootstrap/components.html#labels-badges
 # 
-# Helper for producing Twitter Bootstrap badges
-#
 # Default badge:
 #
+# @example
 #   badge('Default')
 #
-# Other badges (see BADGE_TYPES):
-#
 #   badge('Info', :info)
 #
-# Options passed through to <span> tag:
-#
 #   badge('Warning', :warning, id: 'warn-id', class: 'more-class', my_key: 'my_value')
 #
 module Bootstrap::BadgeHelper
@@ -19,6 +16,19 @@ module Bootstrap::BadgeHelper
   
   BADGE_TYPES = %w(default success warning important info inverse)
   
+  # Returns html for a Bootstrap badge.
+  #
+  # @overload badge(text, options={})
+  #   Returns html for +default+ badge
+  #   @param [String] text Text of badge
+  #   @param [Hash] options Html attributes for badge <span>
+  # @overload badge(text, badge_type, options={})
+  #   Returns html for badge of type _badge_type_
+  #   @param [String] text Text of badge
+  #   @param [String, Symbol] badge_type one of BADGE_TYPES
+  #   @param [Hash] options Html attributes for badge <span>
+  # @return [String] html for badge
+  # @raise [InvalidBadgeTypeError] When a badge type is passed and isn't one of the BADGE_TYPES
   def badge(*args)
     text = args.shift
     options = add_badge_classes(*args)
@@ -28,7 +38,7 @@ module Bootstrap::BadgeHelper
   private
   
   def add_badge_classes(*args)
-    options = args.extract_options!
+    options = canonicalize_options(args.extract_options!)
     validate_badge_types(args)
     classes = ['badge'] + args.map { |arg| "badge-#{arg}" }
     ensure_class(options, classes)

data/app/helpers/bootstrap/button_helper.rb

@@ -1,43 +1,44 @@
 # Helper for producing Twitter Bootstrap buttons OR links that look like buttons.
-# See: http://twitter.github.io/bootstrap/base-css.html#buttons
 #
-# Default button:
+# See:
+# * http://twitter.github.io/bootstrap/base-css.html#buttons
+# * http://twitter.github.io/bootstrap/components.html#buttonGroups
+# * http://twitter.github.io/bootstrap/components.html#buttonDropdowns
+# @example Button / Link
 #
-#   button('Default') #=> <button class="btn">Default</button>
+#   # button
+#   button('Default')
 #
-# Pass in a url to make a link that looks like a button:
-#
-#   button('Home', url: '/home')    #=> <a href="/home" class="btn">Home</a>
-#
-# Or make a <button> look like a link:
+#   # add url option to make <a> styled as button
+#   button('Home', url: '/')
 #
+#   # a button styled as a link
 #   button('Home', :link)
 #
-# Specify the type (see BUTTON_TYPES):
-#
+#   # give it a type; see BUTTON_TYPES
 #   button('Info', :info)
 #
-# Specify the size (see BUTTON_SIZES)
-#
+#   # give it a size (see BUTTON_SIZES)
 #   button('Small', :small)
 #
-# Options passed through to <span> tag:
-#
-#   button('Warning', :warning, :large id: 'warn-id', class: 'more-class', my_key: 'my_value')
-#
-# Button groups/toolbars: http://twitter.github.io/bootstrap/components.html#buttonGroups
-#
-#   = button_group do
-#     = button("Left", "/left")
-#     = button("Right", "/right")
-#
-#   = button_toolbar do
-#     = button('Single Button', '/single')
-#     = button_group
-#       = button('Group Button 1')
-#       = button('Group Button 2')
-#     = button('Another Single')
-#
+#   # size, type, additional class and additional html attributes
+#   button('Warning', :warning, :large, id: 'warn-id', class: 'more-class', my_key: 'my_value')
+#
+# @example Button Group
+#   <%= button_group do %>
+#     <%= button("Left", url: "/left") %>
+#     <%= button("Right", id: 'right') %>
+#   <% end %>
+#
+# @example Button Toolbar
+#    <%= button_toolbar do %>
+#      <%= button('Single Button', url: '/single') %>
+#      <%= button_group do %>
+#        <%= button('Group Button 1') %>
+#        <%= button('Group Button 2') %>
+#      <% end %>
+#      <%= button('Another Single') %>
+#   <% end %>
 module Bootstrap::ButtonHelper
   InvalidButtonModifierError = Class.new(StandardError)
 
@@ -47,9 +48,36 @@ module Bootstrap::ButtonHelper
   
   BUTTON_ALL = BUTTON_TYPES + BUTTON_SIZES + BUTTON_OTHERS
   
+  # Returns <button> or <a> styled as Bootstrap button
+  #
+  # @overload button(text, options={})
+  #   Default button
+  #   @param [String] text text of button
+  #   @param [Hash] options All keys except +:url+ become html attributes for the generated tag
+  #   @option options [String] :url if present, return a <a> styled as a button
+  # @overload button(text, type, options={})
+  #   Button of type _type_
+  #   @param [String] text text of button
+  #   @param [String, Symbol] type type of button; see {Bootstrap::ButtonHelper::BUTTON_TYPES}
+  #   @param [Hash] options All keys except +:url+ become html attributes for the generated tag
+  #   @option options [String] :url if present, return a <a> styled as a button
+  # @overload button(text, size, options={})
+  #   Button of size _size_
+  #   @param [String] text text of button
+  #   @param [String, Symbol] size size of button; see {Bootstrap::ButtonHelper::BUTTON_SIZES}
+  #   @param [Hash] options All keys except +:url+ become html attributes for the generated tag
+  #   @option options [String] :url if present, return a <a> styled as a button
+  # @overload button(text, type, size, options={})
+  #   Button of type _type_, size _size_
+  #   @param [String] text text of button
+  #   @param [String, Symbol] type type of button; see {Bootstrap::ButtonHelper::BUTTON_TYPES}
+  #   @param [String, Symbol] size size of button; see {Bootstrap::ButtonHelper::BUTTON_SIZES}
+  #   @param [Hash] options All keys except +:url+ become html attributes for the generated tag
+  #   @option options [String] :url if present, return a <a> styled as a button
+  # @return [String] Html for a <button> (or <a> if +url+ option passed in)
   def button(*args)
     text = args.shift
-    options = args.extract_options!
+    options = canonicalize_options(args.extract_options!)
     href = options.delete(:url)
     options = add_button_classes(options, args)
 
@@ -60,28 +88,48 @@ module Bootstrap::ButtonHelper
     end
   end
     
-  def button_toolbar
-    content_tag(:div, class: 'btn-toolbar') do
+  # Returns a Bootstrap button toolbar
+  #
+  # @param [Hash] options will be come html attributes of generated <div>
+  # @yield block usually consists of calls to {Bootstrap::ButtonHelper#button} or {Bootstrap::ButtonHelper#button_group}
+  # @yieldreturn [String] html for contents of toolbar
+  #
+  # @return [String] html for button toolbar
+  def button_toolbar(options={})
+    options = canonicalize_options(options)
+    options = ensure_class(options, 'btn-toolbar')
+    
+    content_tag(:div, options) do
       yield
     end
   end
   
-  def button_group
-    content_tag(:div, class: 'btn-group') do
+  # Returns a Bootstrap button group
+  #
+  # @param [Hash] options will be come html attributes of generated <div>
+  # @yield block usually consists of calls to {Bootstrap::ButtonHelper#button}
+  # @yieldreturn [String] html for contents of group
+  #
+  # @return [String] html for button group
+  def button_group(options={})
+    options = canonicalize_options(options)
+    options = ensure_class(options, 'btn-group')
+    
+    content_tag(:div, options) do
       yield
     end
   end
     
+  def validate_button_types_and_sizes(types_and_sizes)
+    types_and_sizes.each { |e| raise(InvalidButtonModifierError, e.inspect) unless BUTTON_ALL.include?(e.to_s) }
+  end
+
   private
   
   def add_button_classes(options, button_types_and_sizes)
-    validate_types_and_sizes(button_types_and_sizes)
+    validate_button_types_and_sizes(button_types_and_sizes)
     classes = ['btn'] + button_types_and_sizes.map { |e| "btn-#{e}" }
     ensure_class(options, classes)
   end
   
-  def validate_types_and_sizes(types_and_sizes)
-    types_and_sizes.each { |e| raise(InvalidButtonModifierError, e.inspect) unless BUTTON_ALL.include?(e.to_s) }
-  end
-  
 end

data/app/helpers/bootstrap/common_helper.rb

@@ -1,52 +1,73 @@
+# Utililty methods used by Bootstrap::*Heler classes
 module Bootstrap::CommonHelper
   ArgumentError = Class.new(::ArgumentError)
   
-  # Returns a new hash with the :class key's value converted to an
-  # Array with each element converted to a String.
-  # 
-  #   arrayify_class({})                       #=> {:class=>[]} 
-  #   arrayify_class(:class => 'foo')          #=> {:class=>["foo"]}
-  #   arrayify_class(:class => [:foo, 'bar'])  #=> {:class=>["foo", "bar"]} 
-  def arrayify_class(hash)
+  # Returns a new Hash with:
+  # * keys converted to Symbols
+  # * the +:class+ key has it value converted to an Array of String
+  # @raise [ArgumentError] if _hash_ is not a Hash
+  # @return [Hash]
+  def canonicalize_options(hash)
     raise ArgumentError.new("expected a Hash, got #{hash.inspect}") unless hash.is_a?(Hash)
-    
-    return hash if hash[:class] == false
-    
-    hash.dup.tap do |h|
-      classes = h[:class]
-      h[:class] = case
-        when classes.blank? then []
-        when classes.is_a?(Array) then classes.dup
-        else classes.to_s.split(/\s/)
-        end
-      h[:class].map!(&:to_s)
+
+    hash.symbolize_keys.tap do |h|
+      h[:class] = arrayify_class_and_stringify_elements(h[:class])
     end
   end
+
+  # Returns a new Array of String
+  # @example
+  #   arrayify_class_and_stringify_elements(nil)            #=> [] 
+  #   arrayify_class_and_stringify_elements('foo')          #=> ["foo"]
+  #   arrayify_class_and_stringify_elements([:foo, 'bar'])  #=> ["foo", "bar"]
+  # @return [Array of String]
+  def arrayify_class_and_stringify_elements(klass)
+    return false if klass == false
+    
+    case
+    when klass.blank? then []
+    when klass.is_a?(Array) then klass
+    else klass.to_s.strip.split(/\s/)
+    end.map(&:to_s)
+  end
   
   # Returns down-caret character used in various dropdown menus.
+  # @param [Hash] options html options for <span>
+  # @example
+  #   caret(id: 'my-id')   #=> <span class='caret' id='my-id'></span>
+  # @return [String]
   def caret(options={})
+    options= canonicalize_options(options)
     options = ensure_class(options, 'caret')
     content_tag(:span, nil, options)
   end
   
-  # Ensures that _hash_ has key of :class that includes _klass_.
+  # Returns new Hash where :class value includes _klasses_.
+  # 
+  # Assumes _hash_ has a key :class (Symbol) whose value is an Array of String.
+  # {Bootstrap::CommonHelper#canonicalize_options} will return such a Hash.
   #
-  #   ensure_class({}, 'foo')                            #=> {class: 'foo'}
-  #   ensure_class({class: 'bar', id: 'my-id'}, 'foo')   #=> {:class=>["bar", "foo"], :id=>"my-id"}
-  def ensure_class(hash, klass)
-    arrayify_class(hash).tap do |h|
-      klasses = Array(klass).map(&:to_s)
-      klasses.each do |k|
+  # @example
+  #   ensure_class({class: []}, 'foo')                               #=> {class: 'foo'}
+  #   ensure_class({class: ['bar'], id: 'my-id'}, ['foo', 'foo2'])   #=> {:class=>["bar", "foo", "foo2"], :id=>"my-id"}
+  # @param [Hash] hash
+  # @param [String, Array] klasses one or more classes to add to the +:class+ key of _hash_
+  # @return [Hash]
+  def ensure_class(hash, klasses)
+    hash.dup.tap do |h|
+      Array(klasses).map(&:to_s).each do |k|
         h[:class] << k unless h[:class].include?(k)
       end
     end
   end
 
   # Returns extra arguments that are Bootstrap modifiers.  Basically 2nd argument
-  # up to (not including) the last (hash) argument.
+  # up to (not including) the last (Hash) argument.
   #
+  # @example
   #   extract_extras('text')  #=> []
   #   extract_extras('text', :small, :info, id: 'foo')  #=> [:small, :info]
+  # @return [Array]
   def extract_extras(*args)
     args.extract_options!
     args.shift

data/app/helpers/bootstrap/dropdown_helper.rb

@@ -1,40 +1,66 @@
-# Helper methods for various Bootstrap dropdown menus
+# Rails helper methods for various Bootstrap dropdown menus
 #
 # * http://twitter.github.io/bootstrap/components.html#buttonDropdowns
 # * http://twitter.github.io/bootstrap/components.html#navbar
 #
-# All of the *_dropdown methods should have dropdown_item() or dropdown_divider()
-# as children.
+# @example nav dropdown
+#  <%= nav_dropdown('Admin') do %>
+#    <%= dropdown_item('Users', '/admin/users') %>
+#    <%= dropdown_item('Logs', '/admin/logs') %>
+#    <%= dropdown_divider %>
+#    <%= dropdown_item('Exceptions', '/admin/exceptions') %>
+#  <% end %>
 #
-#   = nav_dropdown('Admin') do
-#     = dropdown_item('Users', admin_users_path)
-#     = dropdown_item('Logs', admin_logs_path)
-#     = dropdown_divider
-#     = dropdown_item('Exceptions', admin_exceptions_path)
+# @example button dropdown
+#  <%= button_dropdown('Actions') do %>
+#    <%= dropdown_item('Action 1', '/action1') %>
+#    <%= dropdown_item('Action 2', '/action2') %>
+#  <% end %>
 #
-#   = button_dropdown('Actions') do
-#     / dropdown_items
-#
-#   = split_button_dropdown('Edit', edit_user_path(@user)) do
-#     / dropdown_items
+# @example split-button dropdown
+#   <%= split_button_dropdown('Default', url: '/default') do %>
+#     <%= dropdown_item('Action 1', '/action1') %>
+#     <%= dropdown_item('Action 2', '/action2') %>
+#   <% end %>#
 #
 module Bootstrap::DropdownHelper
   
-  # should be nested within a <ul class='nav'> tag
+  # Returns a drop-down menu of links
+  #
+  # Usually called from yielded block of {Bootstrap::NavHelper#nav_bar}
+  #
+  # @param [String] text text of dropdown link
+  # @yield yielded block is usually calls to {Bootstrap::NavHelper#dropdown_item} or {Bootstrap::NavHelper#dropdown_divider}
+  # @return [String] '<li class='dropdown'><ul class='dropdown-menu'> with contents of yielded block
   def nav_dropdown(text)
     content_tag(:li, class: 'dropdown') do
       nav_dropdown_link(text) + dropdown_ul { yield }
     end
   end
   
-  # likely nested within button_toolbar
+  # Returns a Bootstrap button dropdown
+  #
+  # Parameters have same semantics as in {Bootstrap::ButtonHelper#button}
+  #
+  # @overload button_dropdown('Text')
+  # @overload button_dropdown('Text', :info)
+  # @overload button_dropdown('Text', :info, :mini)
+  # @yield yielded block is usually calls to {Bootstrap::NavHelper#dropdown_item} or {Bootstrap::NavHelper#dropdown_divider}# @return [String]
   def button_dropdown(*args)
     content_tag(:div, class: 'btn-group') do
       button_dropdown_link(*args) + dropdown_ul { yield }
     end
   end
   
-  # likely nested within button_toolbar
+  # Returns a Bootstrap split-button dropdown
+  # 
+  # Parameters have same semantics as in {Bootstrap::ButtonHelper#button}
+  # 
+  # @overload split_button_dropdown('Text')
+  # @overload split_button_dropdown('Text', url: '/url')
+  # @overload split_button_dropdown('Text', :large, :danger, url: '/url')
+  # @yield yielded block is usually calls to {Bootstrap::NavHelper#dropdown_item} or {Bootstrap::NavHelper#dropdown_divider} 
+  # @return [String]
   def split_button_dropdown(*args)
     extras = extract_extras(*args)
     
@@ -43,12 +69,11 @@ module Bootstrap::DropdownHelper
     end
   end
   
-  # Must be nested under one of the *_dropdown methods:
-  #
-  #  dropdown_item('Action', '/action')
-  #  dropdown_item('Action')              # href set to 'javascript:void(0)'
-  #  dropdown_item('Action', id: 'foo')   # options passed to <a> tag
+  # Returns a link for use within various *_dropdown methods
   #
+  # @overload dropdown_item('Text')
+  # @overload dropdown_item('Text', url: '/url')
+  # @return [String]
   def dropdown_item(*args)
     options = args.extract_options!
     text = args.shift or raise "Need text to link to"
@@ -59,7 +84,8 @@ module Bootstrap::DropdownHelper
     end
   end
   
-  # Produces a line to divide sections of a dropdown menu
+  # Returns a divider for various dropdowns
+  # @return [String] <li class="divider">
   def dropdown_divider
     content_tag(:li, nil, class: 'divider')
   end

data/app/helpers/bootstrap/form_helper.rb

@@ -1,19 +1,59 @@
+# Rails helper methods associated with forms for Bootstrap.
+#
+# @example +#submit_button_tag()+ instead of +#submit_button()+
+#   submit_button_tag
+#   submit_button_tag('Save')
+#   submit_button_tag('Delete', :danger)
+#   submit_button_tag('Big', :large)
+#   submit_button_tag('With Options', :small, :info, id: 'my-id')
 module Bootstrap::FormHelper
+  InvalidButtonModifierError = Class.new(StandardError)
   
-  def submit_tag(value = "Save changes", options = {})
-    options = arrayify_class(options.symbolize_keys)
-    
-    class_arg = Array(options.delete(:class)).map(&:to_s)
-    classes = []
-    classes << 'btn-primary' unless options.delete(:bootstrap) == false ||
-       class_arg.detect { |e| e.starts_with?('btn-') }
-    class_arg.each { |e| classes << e }
-    classes << 'btn' if classes.detect { |e| e.starts_with?('btn-') }
-    options = ensure_class(options, classes)
+  # Returns <input> similar to +#submit_tag()+ but:
+  # * styled like a Bootstrap button, type :primary
+  # * has +:disable_with+ set to "Processing ..."
+  # See {Bootstrap::ButtonHelper} for documentation on button type and size
+  # @overload submit_button_tag(options={})
+  #   @param [Hash] options all options except +:disable_with+ become html attributes for <input> tag
+  #   @option options [String, false] :disable_with either override or turn off the disabling of the button
+  # @overload submit_button_tag(text, options={})
+  #   @param [String] text value of <input>
+  #   @param [Hash] options see +options+ param in first method signature
+  # @overload submit_button_tag(text, type, options={})
+  #   @param [String] text value of <input>
+  #   @param [String, Symbol] type type of button
+  #   @param [Hash] options see +options+ param in first method signature
+  # @overload submit_button_tag(text, size, options={})
+  #   @param [String] text value of <input>
+  #   @param [String, Symbol] size size of button
+  #   @param [Hash] options see +options+ param in first method signature
+  # @overload submit_button_tag(text, type, size, options={})
+  #   @param [String] text value of <input>
+  #   @param [String, Symbol] type type of button
+  #   @param [String, Symbol] size size of button
+  #   @param [Hash] options see +options+ param in first method signature
+  # @return [String]
+  def submit_button_tag(*args)
+    options = canonicalize_options(args.extract_options!)
     
+    value = if Bootstrap::ButtonHelper::BUTTON_ALL.include?(args.first.to_s)
+      "Save changes"
+    else
+      args.shift.presence || "Save changes"
+    end
+
+    button_classes = if args.present?
+      args.each { |e| raise(InvalidButtonModifierError, e.inspect) unless
+         Bootstrap::ButtonHelper::BUTTON_ALL.include?(e.to_s) }
+      ['btn'] + args.map { |e| "btn-#{e}" }
+    else
+      ['btn', 'btn-primary']
+    end
+    options = ensure_class(options, button_classes)
+
     options[:disable_with] = "Processing ..." unless options.has_key?(:disable_with)
 
-    super(value, options)
+    submit_tag(value, options)
   end
   
 end

data/app/helpers/bootstrap/nav_helper.rb

@@ -0,0 +1,125 @@
+# Rails view helpers for various Bootstrap navigation components.
+#
+# See: http://twitter.github.io/bootstrap/components.html#navbar
+# @example navigation bar (across top of page)
+#   <%= nav_bar do %>      
+#
+#     <%= brand('Span Brand')%>
+#     <%= brand('Link Brand', url: '#')%>
+#
+#     <%= nav_bar_links do %>
+#
+#       <%= nav_bar_link('Active', '#', active: true) %>
+#       <%= nav_bar_link('Link1', '/link1') %>
+#
+#       <%= nav_bar_divider %>
+#
+#       <%= nav_dropdown('Foo') do %>
+#         <%= dropdown_item('One', 'foo')%>
+#       <% end %>
+#
+#     <% end %>
+#   <% end %>
+#
+# @example navigation list (e.g., in sidebar)
+#   <%= nav_list(id: 'my') do %>
+#     <%= nav_list_header('Buttons & Labels') %>
+#     <%= dropdown_item('Buttons', 'butons')%>
+#     <%= dropdown_item('Labels', 'butons')%>
+#   <% end %>
+module Bootstrap::NavHelper
+  
+  # Returns a Bootstrap navigation bar
+  # @yield yield block usually consists of other {Bootstrap::NavHelper} helpers
+  # @yieldreturn the contents of the navigation bar
+  # @return [String]
+  def nav_bar()
+    content_tag(:header, class: 'navbar') do
+      content_tag(:nav, class: 'navbar-inner') do
+        yield
+      end
+    end
+  end
+  
+  # Returns a Bootstrap brand element
+  #
+  # @param [String] text text of the brand
+  # @param [Hash] options except for +:url+, becomes html attributes of returned tag
+  # @option options [String] :url if present, returned tag is an <a> (else <span>)
+  # @return [String] <a> if +:url+ option present, else <span>
+  def brand(text, options = {})
+    options = canonicalize_options(options)
+    options = ensure_class(options, 'brand')
+    url = options.delete(:url)
+    
+    if url.present?
+      link_to(text, url, options)
+    else
+      content_tag(:span, text, options)
+    end
+  end
+  
+  # Returns <ul> for a group of nav bar links.
+  #
+  # Usually called in +yield+ block of {Bootstrap::NavHelper#nav_bar}
+  #
+  # @yield block usually consists of calls to {Bootstrap::NavHelper#nav_bar_link} and {Bootstrap::NavHelper#nav_bar_divider}
+  # @return [String] <div class='nav'> containing results of yielded block
+  def nav_bar_links(options={})
+    options = canonicalize_options(options)
+    options = ensure_class(options, 'nav')
+    
+    content_tag(:div, options) do
+      yield
+    end
+  end
+  
+  # Returns a nav_bar_link
+  #
+  # Usually called within yield block of {Bootstrap::NavHelper#nav_bar}
+  #
+  # @param [String] text text of link
+  # @param [String] url url of link
+  # @param [Hash] options except for +:active+, becomes html attributes of link
+  # @option options [true] :active if set to true, displays as inactive
+  # @return [String] returns <a> within <li>
+  def nav_bar_link(text, url, options={})
+    a_options = canonicalize_options(options)
+    active = a_options.delete(:active)
+    
+    li_options = {class: ('active' if active)}
+    
+    content_tag(:li, li_options) do
+      link_to(text, url, a_options)
+    end
+  end
+  
+  # Returns divider (vertical bar) for separating items in a nav_bar
+  #
+  # @return [String] <li class="divider-vertical"></li>
+  def nav_bar_divider
+    content_tag(:li, nil, class: "divider-vertical")
+  end
+  
+  # Returns nav list
+  #
+  # @param [Hash] options becomes html attributes of enclosing <div>
+  # @yield block consists of calls to {Bootstrap::NavHelper#nav_list_header} and {Bootstrap::NavHelper#dropdown_item} 
+  # @return [String] <div class='well'><ul class='nav nav-list'> containg results of yielded block
+  def nav_list(options={})
+    options = canonicalize_options(options)
+    options = ensure_class(options, 'well')
+    content_tag(:div, options) do
+      content_tag(:ul, class: 'nav nav-list') do
+        yield
+      end
+    end
+  end
+  
+  # Returns header for nav_list
+  # @param [String] text text of header
+  # @return [String]
+  def nav_list_header(text)
+    content_tag(:li, text, class: 'nav-header')
+  end
+end

data/app/helpers/bootstrap/stamp_helper.rb

@@ -1,28 +1,32 @@
+# Rails helper for producing Twitter Bootstrap labels.  We use +#stamp()+ because +#label()+ is
+# a standard Rails helper method.
+#
 # See: http://twitter.github.io/bootstrap/components.html#labels-badges
 # 
-# Helper for producing Twitter Bootstrap labels.  We call them stamps because #label() is
-# a Rails helper method.
-#
-# Default label:
-#
+# @example
 #   stamp('Default')
-#
-# Other labels (see LABEL_TYPES):
-#
-#   stamp('Info', :info)
-#
-# Options passed through to <span> tag:
-#
+#   stamp('Info', :info)  
 #   stamp('Warning', :warning, id: 'warn-id', class: 'more-class', my_key: 'my_value')
 #
 module Bootstrap::StampHelper
   InvalidStampTypeError = Class.new(StandardError)
   
   LABEL_TYPES = %w(default success warning important info inverse)
-  
-  # stamp('Text')
-  # stamp('Text', :success)            # see LABEL_TYPES
-  # stamp('Text', :info, id: 'my-id')  # options passed thru to <span>
+
+  #=> see {Bootstrap::StampHelper::LABEL_TYPES}
+
+  # Returns a Bootstrap label
+  #
+  # @overload stamp(text, options={})
+  #   Returns a label of type :default
+  #   @param [String] text text of the label
+  #   @param [Hash] options html attributes for returned <span>
+  # @overload stamp(text, type, options={})
+  #   Returns a label of type _type_
+  #   @param [String] text text of the label
+  #   @param [Symbol, String] type type of label see {Bootstrap::StampHelper::LABEL_TYPES}
+  #   @param [Hash] options html attributes for returned <span>
+  # @return [String]
   def stamp(*args)
     text = args.shift
     options = add_label_classes(*args)
@@ -32,7 +36,7 @@ module Bootstrap::StampHelper
   private
   
   def add_label_classes(*args)
-    options = args.extract_options!
+    options = canonicalize_options(args.extract_options!)
     validate_label_types(args)
     classes = ['label'] + args.map { |arg| "label-#{arg}" }
     ensure_class(options, classes)

data/app/views/bootstrap_view_helpers/index.html.erb

@@ -1,3 +1,107 @@
 <h1>Examples</h1>
 
-<%= badge('Default') %>
+<%= split_button_dropdown('Default', url: '/default') do %>
+  <%= dropdown_item('Action 1', '/action1') %>
+  <%= dropdown_item('Action 2', '/action2') %>
+<% end %>
+
+<%= button_dropdown('Actions foo', url: 'foo') do %>
+  <%= dropdown_item('Action 1', '/action1') %>
+  <%= dropdown_item('Action 2', '/action2') %>
+<% end %>
+
+<%= nav_dropdown('Admin') do %>
+  <%= dropdown_item('Users', 'admin_users_path') %>
+  <%= dropdown_item('Logs', 'admin_logs_path') %>
+  <%= dropdown_divider %>
+  <%= dropdown_item('Exceptions', 'admin_exceptions_path') %>
+<% end %>
+  
+
+<%= button_group do %>
+  <%= button("Left", url: "/left") %>
+  <%= button("Right", id: 'right') %>
+<% end %>
+
+<%= button_toolbar do %>
+  <%= button('Single Button', url: '/single') %>
+  <%= button_group do %>
+    <%= button('Group Button 1') %>
+    <%= button('Group Button 2') %>
+  <% end %>
+  <%= button('Another Single') %>
+<% end %>
+#
+<div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div><div>
+<%= badge('Default') %>
+</div>

data/lib/bootstrap-view-helpers/version.rb

@@ -1,3 +1,3 @@
 module BootstrapViewHelpers
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bootstrap-view-helpers
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-17 00:00:00.000000000 Z
+date: 2013-05-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -27,6 +27,54 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: jquery-rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sass-rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: bootstrap-sass
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.3.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.3.1.0
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +155,38 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Rails view helpers for Bootstrap
 email:
 - steve.downtown@gmail.com
@@ -121,6 +201,7 @@ files:
 - app/helpers/bootstrap/common_helper.rb
 - app/helpers/bootstrap/dropdown_helper.rb
 - app/helpers/bootstrap/form_helper.rb
+- app/helpers/bootstrap/nav_helper.rb
 - app/helpers/bootstrap/stamp_helper.rb
 - app/views/bootstrap_view_helpers/index.html.erb
 - config/routes.rb
@@ -156,3 +237,4 @@ signing_key:
 specification_version: 3
 summary: Rails view helpers for Bootstrap
 test_files: []
+has_rdoc: