bootstrap-view-helpers 0.0.5 → 0.0.6

data/README.md

@@ -7,6 +7,8 @@ Includes support for:
   * navigation
     * nav bar
     * nav list
+  * icons
+    * icons with text 
   * buttons
     * `<button>`
     * `<a>` styled as button
@@ -19,7 +21,8 @@ Includes support for:
     * split-button dropdowns
   * accordion
   * form helpers
-    * submit_tag_button 
+    * submit_tag_button
+    * cancel_tag_button
   
 ## Note
 
@@ -79,6 +82,30 @@ Complete [API documentation](http://rubydoc.info/gems/bootstrap-view-helpers/fra
 <% end %>
 ```
 
+### Icons
+
+See: http://twitter.github.io/bootstrap/base-css.html#icons
+
+Icons
+```ruby
+icon(:search)
+icon(:search, :white)
+icon(:search, :white, id: 'my-id')
+```
+
+Icons with Text
+```ruby
+icon(:search, 'Search')
+icon(:remove, :white, 'Delete')
+icon(:ok, 'Save', id: 'my-id')
+```
+
+Line up text when some have icons and some don't
+```ruby
+icon(:search, 'With icon')  # shows search icon
+icon(:blank, 'No icon')     # no icon, text will aligin if icons are stacked
+```
+
 ### Buttons
 
 ```ruby
@@ -194,4 +221,14 @@ submit_button_tag('Big', :large)
 submit_button_tag('With Options', :small, :info, id: 'my-id')
 ```
 
+#### cancel_tag_button
 
+Convenience method for standard "Cancel" button.  `<a>` tag styled as Bootstrap button.
+
+```ruby
+cancel_button_tag(url: '/')  # => <a href="/" class="btn">Cancel</a>
+cancel_button_tag('Go Back', url: '/')
+cancel_button_tag(:info, url: '/')
+cancel_button_tag(:large, url: '/')
+cancel_button_tag('Return', :small, :warning, url: '/', id: 'my-id')
+```

data/app/controllers/bootstrap_view_helpers_controller.rb

@@ -1,3 +1,4 @@
+# @private
 class BootstrapViewHelpersController < ApplicationController
   
   def index

data/app/helpers/bootstrap/common_helper.rb

@@ -1,33 +1,40 @@
-# Utililty methods used by Bootstrap::*Heler classes
+# Utililty methods used by Bootstrap::*Helper classes
 module Bootstrap::CommonHelper
   ArgumentError = Class.new(::ArgumentError)
   
   # Returns a new Hash with:
   # * keys converted to Symbols
-  # * the +:class+ key has it value converted to an Array of String
+  # * the +:class+ key has its value converted to an Array of String
+  # @example
+  #   canonicalize_options("id" => "ID", "class" => "CLASS")  # => {:id=>"ID", :class=>["CLASS"]} 
+  #   canonicalize_options(:class => 'one two')               # => {:class=>["one", "two"]}
+  #   canonicalize_options("class" => [:one, 2])              # => {:class=>["one", "2"]} 
+  # @param [Hash] hash typically an +options+ param to a method call
   # @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)
 
     hash.symbolize_keys.tap do |h|
-      h[:class] = arrayify_class_and_stringify_elements(h[:class])
+      h[:class] = arrayify_and_stringify_elements(h[:class])
     end
   end
 
-  # Returns a new Array of String
+  # Returns a new Array of String from _arg_.
   # @example
-  #   arrayify_class_and_stringify_elements(nil)            #=> [] 
-  #   arrayify_class_and_stringify_elements('foo')          #=> ["foo"]
-  #   arrayify_class_and_stringify_elements([:foo, 'bar'])  #=> ["foo", "bar"]
+  #   arrayify_and_stringify_elements(nil)            #=> [] 
+  #   arrayify_and_stringify_elements('foo')          #=> ["foo"]
+  #   arrayify_and_stringify_elements('foo bar')      #=> ["foo", "bar"]
+  #   arrayify_and_stringify_elements([:foo, 'bar'])  #=> ["foo", "bar"]
+  # @param [String, Array] arg
   # @return [Array of String]
-  def arrayify_class_and_stringify_elements(klass)
-    return false if klass == false
+  def arrayify_and_stringify_elements(arg)
+    return false if arg == false
     
     case
-    when klass.blank? then []
-    when klass.is_a?(Array) then klass
-    else klass.to_s.strip.split(/\s/)
+    when arg.blank? then []
+    when arg.is_a?(Array) then arg
+    else arg.to_s.strip.split(/\s/)
     end.map(&:to_s)
   end
   
@@ -42,11 +49,8 @@ module Bootstrap::CommonHelper
     content_tag(:span, nil, options)
   end
   
-  # Returns new Hash where :class value includes _klasses_.
+  # Returns new (canonicalized) 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.
-  #
   # @example
   #   ensure_class({class: []}, 'foo')                               #=> {class: 'foo'}
   #   ensure_class({class: ['bar'], id: 'my-id'}, ['foo', 'foo2'])   #=> {:class=>["bar", "foo", "foo2"], :id=>"my-id"}
@@ -54,6 +58,8 @@ module Bootstrap::CommonHelper
   # @param [String, Array] klasses one or more classes to add to the +:class+ key of _hash_
   # @return [Hash]
   def ensure_class(hash, klasses)
+    canonicalize_options(hash)
+    
     hash.dup.tap do |h|
       Array(klasses).map(&:to_s).each do |k|
         h[:class] << k unless h[:class].include?(k)

data/app/helpers/bootstrap/form_helper.rb

@@ -1,37 +1,60 @@
 # 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')
+# @example Bootstrap form-actions <div>
+#   <div class='form-actions'>
+#     <%= submit_button_tag %>
+#     <%= cancel_button_tag %>
+#   </div>
+#
 module Bootstrap::FormHelper
+  ArgumentError = Class.new(StandardError)
   InvalidButtonModifierError = Class.new(StandardError)
   
-  # Returns <input> similar to +#submit_tag()+ but:
+  # Convenience method for standard "Cancel" button.
+  #
+  # The +text, type,+ and +size+ arguments are all optional.
+  #
+  # Has same semantics as calls to {Bootstrap::ButtonHelper#button} except:
+  # * text defaults to "Cancel"
+  # * +:url+ option is required
+  # @example
+  #   cancel_button_tag(url: '/')
+  #   cancel_button_tag('Go Back', url: '/')
+  #   cancel_button_tag(:info, url: '/')
+  #   cancel_button_tag(:large, url: '/')
+  #   cancel_button_tag('Return', :small, :warning, url: '/', id: 'my-id')
+  # @overload cancel_button_tag(text, type, size, options={})
+  #   @param [String] text text of link
+  #   @param [Symbol] type type of button
+  #   @param [Symbol] size size of button
+  #   @param [Hash] options All keys except +:url+ become html attributes of the <a> tag
+  #   @option options [String] :url required
+  # @return [String] <a> tag styled as Bootstrap button
+  def cancel_button_tag(*args)
+    options = canonicalize_options(args.extract_options!)
+    raise(ArgumentError, "must pass a :url option") unless options.has_key?(:url)
+    options = ensure_class(options, 'btn')
+    
+    args.map!(&:to_s)
+    args.unshift("Cancel") if args.all? { |e| ::Bootstrap::ButtonHelper::BUTTON_ALL.include?(e) }
+
+    button(*args, options)
+  end
+  
+  # Returns <input> similar to +#submit_tag()+ but:  x
   # * 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
+  #   submit_button_tag('Save')
+  #   submit_button_tag('Delete', :danger)
+  #   submit_button_tag('Big', :large)
+  #   submit_button_tag('With Options', :small, :info, id: 'my-id')
   # @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
+  #   @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
   # @return [String]
   def submit_button_tag(*args)
     options = canonicalize_options(args.extract_options!)

data/app/helpers/bootstrap/icon_helper.rb

@@ -0,0 +1,30 @@
+# Helper methods for Bootstrap icons.
+#
+# See: http://twitter.github.io/bootstrap/base-css.html#icons
+#
+# @example Icons
+#   icon(:search)
+#   icon(:search, :white)
+#   icon(:search, :white, id: 'my-id')
+#
+# @example Icons with text
+#   icon(:search, 'Search')
+#   icon(:remove, :white, 'Delete')
+#   icon(:ok, 'Save', id: 'my-id')
+#
+# @example Text without icon
+#   # so text lines up when you have text but no icon
+#   icon(:blank, 'No icon')
+module Bootstrap::IconHelper
+  
+  # Returns a Bootstrap icon glyph.
+  #
+  # Optionally returns text with icon.
+  # 
+  # See class documentation (above) for examples.
+  # @return [String]
+  def icon(*args)
+    ::Bootstrap::IconRenderer.new(self, *args).html
+  end
+  
+end

data/app/helpers/bootstrap/icon_renderer.rb

@@ -0,0 +1,60 @@
+# @private
+class Bootstrap::IconRenderer
+  ArgumentError = Class.new(StandardError)
+  
+  delegate :canonicalize_options, :content_tag, :ensure_class, :h, to: :template
+  attr_accessor :template, :options, :args, :text
+  
+  def initialize(template, *args)
+    self.template = template
+    process_arguments(args)
+  end
+  
+  def html
+    icon_tag.tap do |tag|
+      tag << text if text.present?
+    end
+  end
+  
+  private
+  
+  def icon_tag
+    content_tag(:i, nil, options)
+  end
+  
+  def process_arguments(args)
+    self.options = canonicalize_options(args.extract_options!)
+    self.args = args.map { |e| e.to_s }
+
+    process_icon_type
+    process_icon_white
+    process_text
+  end
+  
+  def process_icon_type
+    icon_type = args.shift.presence or raise(ArgumentError, "must pass an icon type")
+    icon_class = icon_type == 'blank' ? 'icon-search' : "icon-#{icon_type}"
+    self.options = ensure_class(self.options, icon_class)
+    
+    if icon_type == 'blank'
+      options[:style] = [options[:style], 'opacity: 0'].map(&:presence).compact.join('; ')
+    end
+  end
+  
+  def process_icon_white
+    if args.delete('white')
+      self.options = ensure_class(options, "icon-white")
+    end
+  end
+
+  def process_text
+    self.text = if args.size == 0
+      nil
+    elsif args.size == 1
+      h(" #{args.first}")
+    else
+      raise ArgumentError, 'too many arguments'
+    end 
+  end
+
+end

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

@@ -1,5 +1,20 @@
 <h1>Examples</h1>
 
+<p>
+  <%= icon('search') %>
+  <%= stamp(icon('search', :white))%>
+  <%= stamp(icon('search', 'white', 'Search'))%>
+</p>
+<p>
+  <%= stamp(icon(:remove, :white, 'Delete'), :important)%>
+  <br />
+  <%= stamp(icon(:spacer, :white, 'Spacer'), :important)%>
+</p>
+<p>
+  <%= stamp(icon(:remove, 'Delete'), :important)%>
+  <br />
+  <%= stamp(icon(:spacer, 'Spacer'), :important)%>
+</p>
 <%= split_button_dropdown('Default', url: '/default') do %>
   <%= dropdown_item('Action 1', '/action1') %>
   <%= dropdown_item('Action 2', '/action2') %>

data/lib/bootstrap-view-helpers.rb

@@ -1,4 +1,5 @@
 require "bootstrap-view-helpers/engine"
 
+# @private
 module BootstrapViewHelpers
 end

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

@@ -1,3 +1,3 @@
 module BootstrapViewHelpers
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bootstrap-view-helpers
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-18 00:00:00.000000000 Z
+date: 2013-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -201,6 +201,8 @@ files:
 - app/helpers/bootstrap/common_helper.rb
 - app/helpers/bootstrap/dropdown_helper.rb
 - app/helpers/bootstrap/form_helper.rb
+- app/helpers/bootstrap/icon_helper.rb
+- app/helpers/bootstrap/icon_renderer.rb
 - app/helpers/bootstrap/nav_helper.rb
 - app/helpers/bootstrap/stamp_helper.rb
 - app/views/bootstrap_view_helpers/index.html.erb