bh 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 391d2887c75ed952c021d758e428f486de5f5f15
-  data.tar.gz: 15037d24fab141aaf1d7623e39aad31e44312197
+  metadata.gz: a6f8f3688bcb37ed7b85baa2a23cd0182d8733bf
+  data.tar.gz: 67f60fe7a5e89f1e6c8cb985521f3d0b14ed145a
 SHA512:
-  metadata.gz: b525dc2a2c86b8952d65e078e808a39e3c3cfa8eaa25d3b2d4fac61bb8a412594375a367cc3478d6d0b79a35c8b1ab2a3decd688c356cc0dfd5ddafce0596ccf
-  data.tar.gz: 5acccce283c5abaae55615bb02c3fece400ffac531c94456cd334893bfa2f1bef71e55949b8faf7d0245c133f6160bebd89bb14f1ca046baa0780b7be3721b72
+  metadata.gz: 090b4c224d5b115d9f861f5a67b53ab56ba70be1a009d1496dcf6a50a41d64079865bbec9f1e604774b1cef9726bedee877ca68384b118213a8c02d03a0356f4
+  data.tar.gz: eb42afcf33bcab3e145c3f6f1bf7690f260b922e8bdd690e4b50480ea5911da26b2b03709f975ba7cc78a38e3f7fb73ae06d800b2daa4b312275ec2ae5574599

data/.gitignore

@@ -20,5 +20,4 @@ tmp
 *.o
 *.a
 _site/
-spec/dummy
 mkmf.log

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private
+--markup markdown

data/CHANGELOG.md

@@ -6,6 +6,15 @@ For more information about changelogs, check
 [Keep a Changelog](http://keepachangelog.com) and
 [Vandamme](http://tech-angels.github.io/vandamme).
 
+## 1.1.0 - 2014-09-20
+
+* [FEATURE] Add `icon` helper
+* [FEATURE] Add `font_awesome_css` helper
+* [FEATURE] Add `dropdown` helper
+* [FEATURE] Add `progress_bar` helper
+* [ENHANCEMENT] Add `:fieldset` option to decide whether `fields_for` should wrap fields in a <fieldset> tag
+* [FEATURE] Add `button` helper
+
 ## 1.0.1 - 2014-09-14
 
 * [BUGFIX] Remove `form-control` class from `file_field` (#20)

data/README.md

@@ -55,7 +55,7 @@ How to install
 
 Bh is meant to be included in Rails apps by adding this line to the Gemfile:
 
-    gem 'bh', '~> 1.0'
+    gem 'bh', '~> 1.1'
 
 Since the gem follows [Semantic Versioning](http://semver.org), indicating the
 version number in your Gemfile in the *'~> major.minor'* format guarantees
@@ -92,7 +92,7 @@ document the changes in CHANGELOG.md and README.md, bump the version, then run
 
 Remember that the bh gem follows [Semantic Versioning](http://semver.org).
 
-Any new release that makes backward-compatible bug fixes should bump the *patch* version (1.0.x).
+Any new release that makes backward-compatible bug fixes should bump the *patch* version (1.1.x).
 
 Any new release that adds backward-compatible features should bump the *minor* version (1.x.0).
 
@@ -107,7 +107,11 @@ If you find that a method is missing, fork the project, add the missing code,
 write the appropriate tests, then submit a pull request, and it will gladly
 be merged!
 
-To run the tests, simply type `rspec` on the command line.
+To run the tests, simply type `bundle exec rspec` on the command line.
+
+To see the HTML generated by helpers in a browser,
+edit the [spec/dummy/index.html file](https://github.com/claudiob/bh/blob/master/spec/dummy/index.html),
+then type `bundle exec middleman` and point your browser to [http://0.0.0.0:4567](http://0.0.0.0:4567).
 
 Don’t hesitate to send code comments, issues or pull requests through GitHub
-and to spread the love. Thanks! :)
+and to spread the love. And [don’t click here](http://bit.ly/move-to-la)! Thanks! :)

data/bh.gemspec

@@ -31,4 +31,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'yard' #, '~> 0.8.0'
   spec.add_development_dependency 'coveralls' #, '~> 0.7.0'
   spec.add_development_dependency 'activemodel'
+
+  # For spec/dummy
+  spec.add_development_dependency 'middleman-core' #, '~> 3.3.5'
 end

data/config.rb

@@ -0,0 +1,6 @@
+# If you are developing new helpers and want a quick way to see them in
+# a browser, type `bundle exec middleman` and browse to http://localhost:4567
+# The browser will show the interpolated content of spec/dummy/index.html.erb
+# which you are free to edit as you please to display new helpers.
+set :source, 'spec/dummy'
+activate :bh

data/lib/bh.rb

@@ -1,4 +1,5 @@
 require 'bh/railtie' if defined?(Rails)
+require 'bh/middleman' if defined?(Middleman)
 
 # Adds Bootstrap styles to Rails helpers
 module Bh

data/lib/bh/helpers/alert_helper.rb

@@ -49,12 +49,8 @@ module Bh
     end
 
     def alert_class(context = nil)
-      context = case context.to_s
-        when 'success', 'notice' then :success
-        when 'warning' then :warning
-        when 'danger', 'alert' then :danger
-        else 'info'
-      end
+      valid_contexts = %w(success info warning danger)
+      context = context_for context, default: 'info', valid: valid_contexts
       "alert alert-#{context}"
     end
 

data/lib/bh/helpers/base_helper.rb

@@ -21,5 +21,19 @@ module Bh
       block_given? ? args[1] = html_options : args[2] = html_options
       args
     end
+
+    def context_for(context = nil, options = {})
+      context = case context.to_s
+        when 'notice' then 'success'
+        when 'alert' then 'danger'
+        else context.to_s
+      end
+
+      if options.fetch(:valid, []).map(&:to_s).include? context
+        context
+      else
+        options.fetch :default, 'default'
+      end
+    end
   end
 end

data/lib/bh/helpers/button_helper.rb

@@ -0,0 +1,63 @@
+require 'bh/helpers/base_helper'
+
+module Bh
+  # Provides methods to include buttons.
+  # @see http://getbootstrap.com/components/#buttons
+  module ButtonHelper
+    include BaseHelper
+
+    # Returns an HTML block tag that follows the Bootstrap documentation
+    # on how to display *buttons*.
+    #
+    # The content of the button can either be passed as the first parameter (in
+    # which case, the options are the second parameter), or as a block (in
+    # which case, the options are the first paramter).
+    # @example An button with plain-text content passed as the first parameter.
+    #   <%= button 'Your profile was updated!', context: :info %>
+    # @example A button with HTML content passed as a block.
+    #   <%= button context: :info %>
+    #     <%= glyphicon :star %> Star
+    #   <% end %>
+    #
+    # @return [String] an HTML block tag for a button.
+    # @param [String] content_or_options_with_block the content to display in
+    #   the button.
+    # @param [Hash] options the display options for the button.
+    # @option options [#to_s] :context (:default) the contextual alternative to
+    #   apply to the button depending on its importance. Can be :default,
+    #   :primary, :success, :info, :warning, :danger or :link.
+    # @option options [#to_s] :size the size of the button.
+    # @option options [#to_s] :layout if set to :block, span the button for
+    #   the full width of the parent.
+    def button(content_or_options_with_block = nil, options = nil, &block)
+      if block_given?
+        button_string capture(&block), content_or_options_with_block || {}
+      else
+        button_string content_or_options_with_block, options || {}
+      end
+    end
+
+  private
+
+    def button_string(content = nil, options = {})
+      append_class! options, btn_class(options)
+      content_tag :button, content, options
+    end
+
+    def btn_class(options = {})
+      valid_contexts = %w(primary success info warning danger link)
+      context = context_for options.delete(:context), valid: valid_contexts
+      "btn btn-#{context}"
+
+      size = case options.delete(:size).to_s
+        when 'lg', 'large' then 'btn-lg'
+        when 'sm', 'small' then 'btn-sm'
+        when 'xs', 'extra_small' then 'btn-xs'
+      end
+
+      layout = 'btn-block' if options.delete(:layout).to_s == 'block'
+
+      ['btn', "btn-#{context}", size, layout].compact.join ' '
+    end
+  end
+end

data/lib/bh/helpers/cdn_helper.rb

@@ -21,6 +21,16 @@ module Bh
       bootstrap_asset options.merge(name: 'bootstrap-theme', extension: 'css')
     end
 
+    # @return [String] the URL of the Font Awesome CSS file
+    # @param [Hash] options the options for which CSS file to retrieve.
+    # @option options [String] :version the version of Font Awesome.
+    # @option options [String] :scheme the URI scheme to use.
+    # @option options [Boolean] :minified whether to use the minified version.
+    # @see http://fontawesome.io/get-started/
+    def font_awesome_css(options = {})
+      font_awesome_asset options.merge(name: 'font-awesome', extension: 'css')
+    end
+
     # @return [String] the URL of the Bootstrap JS file
     # @param [Hash] options the options for which JS file to retrieve.
     # @option options [String] :version the version of Bootstrap.
@@ -32,19 +42,29 @@ module Bh
 
   private
 
-    # @return [String] the version of Bootstrap assets to use if unspecified.
-    def bootstrap_version
-      '3.2.0'
+    # @note if unspecified, the version should match the latest available
+    #   version. If that's not the case, it's a bug and should be fixed.
+    def bootstrap_asset(options = {})
+      options[:version] ||= '3.2.0'
+      cdn_asset options.merge(library: 'bootstrap')
     end
 
-    def bootstrap_asset(options = {})
-      version = options.fetch :version, bootstrap_version
+    # @note if unspecified, the version should match the latest available
+    #   version. If that's not the case, it's a bug and should be fixed.
+    def font_awesome_asset(options = {})
+      options[:version] ||= '4.2.0'
+      cdn_asset options.merge(library: 'font-awesome')
+    end
+
+    def cdn_asset(options = {})
+      version = options[:version]
       extension = options[:extension]
       name = options[:name]
+      library = options[:library]
       name = "#{name}.min" if options.fetch(:minified, true)
       scheme = "#{options[:scheme]}:" if options[:scheme]
       host = '//netdna.bootstrapcdn.com'
-      "#{scheme}#{host}/bootstrap/#{version}/#{extension}/#{name}.#{extension}"
+      "#{scheme}#{host}/#{library}/#{version}/#{extension}/#{name}.#{extension}"
     end
   end
 end

data/lib/bh/helpers/dropdown_helper.rb

@@ -0,0 +1,82 @@
+require 'bh/helpers/base_helper'
+
+module Bh
+  # Provides methods to include dropdowns.
+  # @see http://getbootstrap.com/components/#dropdowns
+  # @see http://getbootstrap.com/components/#btn-dropdowns
+  module DropdownHelper
+    include BaseHelper
+
+    # Returns an HTML block tag that follows the Bootstrap documentation
+    # on how to display *dropdowns*.
+    #
+    # The skeleton of the dropdown is an unordered list; its content is passed
+    # as block to the list of dropdown items.
+    # Since the most common use for a dropdown is to display a menu of links, a
+    # variable is set inside the block so that every call to +link_to+
+    # generates a link *surrounded by a list item* and with the appropriate
+    # menu item attributes.
+    # @example A right-aligned dropdown with two links.
+    #   <%= dropdown 'Menu', align: :right do %>
+    #     <%= link_to 'Home', '/' %>
+    #     <%= link_to 'Profile', '/profile' %>
+    #   <% end %>
+    #
+    # @return [String] an HTML block tag for a dropdown.
+    # @param [#to_s] caption the caption for the dropdown button.
+    # @param [Hash] options the display options for the dropdown.
+    # @option options [Boolean] :groupable (true) if true, uses the "btn-group"
+    #   class rather than then "dropdown" class, so that multiple dropdown
+    #   buttons can be aligned in the same row (as a group of buttons).
+    # @option options [Boolean] :split (false) if true, creates a split button
+    #   that only toggles the dropdown when clicked on the rightmost part.
+    # @option options [#to_s] :direction if set to :up, the dropdown appears
+    #   above the button, rather than below.
+    # @option options [#to_s] :align if set to :right, the dropdown is aligned
+    #   to the right-end of the button, rather than to the left-end.
+    # @option options [#to_s] :context (:default) the context for the button,
+    #   which determines its color.
+    # @option options [#to_s] :size the size of the button.
+    # @yield block the content of the dropdown
+    # @see http://getbootstrap.com/components/#dropdowns
+    # @see http://getbootstrap.com/components/#btn-dropdowns
+    def dropdown(caption, options = {}, &block)
+      options ||= {}
+      options[:id] ||= "dropdown-#{rand 10**10}"
+      options[:caption] = caption
+      options[:div_class] = dropdown_div_class options
+      options[:button_class] = dropdown_button_class options
+      options[:list_class] = dropdown_list_class options
+      layout = options[:split] ? 'bh/dropdown_split' : 'bh/dropdown'
+      @dropdown_link = true
+      dropdown = render layout: layout, locals: options, &block
+      dropdown.tap{ @dropdown_link = false }
+    end
+
+  private
+
+    def dropdown_div_class(options = {})
+      group = options.fetch(:groupable, true) ? 'btn-group' : 'dropdown'
+      direction = 'dropup' if options[:direction].to_s == 'up'
+      [group, direction].compact.join ' '
+    end
+
+    def dropdown_list_class(options = {})
+      align = 'dropdown-menu-right' if options[:align].to_s == 'right'
+      ['dropdown-menu', align].compact.join ' '
+    end
+
+    def dropdown_button_class(options = {})
+      valid_contexts = %w(primary success info warning danger link)
+      context = context_for options[:context], valid: valid_contexts
+
+      size = case options[:size].to_s
+        when 'lg', 'large' then 'btn-lg'
+        when 'sm', 'small' then 'btn-sm'
+        when 'xs', 'extra_small' then 'btn-xs'
+      end
+
+      ['btn', "btn-#{context}", size].compact.join ' '
+    end
+  end
+end

data/lib/bh/helpers/form/fields_for_helper.rb

@@ -14,7 +14,9 @@ module Bh
         fields_options[:layout] ||= @options[:layout]
         fields_options[:errors] ||= @options[:errors]
         title = fields_options.delete(:title) { record_name.to_s.humanize }
-        fieldset(title) { super record_name, record_object, fields_options, &block }
+        wrap_in_fieldset = fields_options.fetch :fieldset, true
+        fields = super record_name, record_object, fields_options, &block
+        wrap_in_fieldset ? fieldset(title) { fields } : fields
       end
     end
   end

data/lib/bh/helpers/glyphicon_helper.rb

@@ -1,24 +1,24 @@
-require 'bh/helpers/base_helper'
+require 'bh/helpers/icon_helper'
 
 module Bh
   # Provides methods to include Glyphicons.
   # @see http://getbootstrap.com/components/#glyphicons
   module GlyphiconHelper
-    include BaseHelper
+    include IconHelper
 
     # Returns an HTML block tag that follows the Bootstrap documentation
     # on how to display *glyphicons*.
     # @return [String] an HTML block tag for a glyphicon.
-    # @param [#to_s] the name of the icon to display, with either dashes or
-    #   underscores to separate multiple words.
+    # @param [#to_s] name the name of the icon to display, with either dashes
+    #   or underscores to separate multiple words.
+    # @param [Hash] options the options passed to the HTML tag that displays
+    #   the icon.
     # @example Display the "zoom in" glyphicon
     #   glyphicon :zoom_in
     # @example Display the "zoom out" glyphicon
     #   glyphicon 'zoom-out'
     def glyphicon(name = nil, options = {})
-      append_class! options, 'glyphicon'
-      append_class! options, "glyphicon-#{name.to_s.gsub '_', '-'}" if name
-      content_tag :span, nil, options
+      icon name, options.merge(library: :glyphicons)
     end
   end
 end

data/lib/bh/helpers/icon_helper.rb

@@ -0,0 +1,41 @@
+require 'bh/helpers/base_helper'
+
+module Bh
+  # Provides methods to include vector icons from different libraries.
+  # @see http://getbootstrap.com/components/#glyphicons
+  # @see http://fortawesome.github.io/Font-Awesome/examples/#bootstrap
+  module IconHelper
+    include BaseHelper
+
+    # Returns an HTML block tag to display a vector icon.
+    # @return [String] an HTML block tag for a vector icon.
+    # @param [#to_s] name the name of the icon to display, with either dashes
+    #   or underscores to separate multiple words.
+    # @param [Hash] options the options for the icon tag. The following options
+    #   are used by the +icon+ method, while the remaining ones are passed
+    #   to the HTML tag that displays the icon.
+    # @option options [#to_s] :library (:glyphicons) the vector icon library
+    #   to use. Valid values are 'glyphicon', 'glyphicons' (for Glyphicons),
+    #   'font-awesome', 'font_awesome' and 'fa' (for Font Awesome).
+    # @example Display the "zoom in" glyphicon
+    #   icon :zoom_in
+    # @example Display the "fire" font awesome icon
+    #   icon 'fire', library: :font_awesome
+    def icon(name = nil, options = {})
+      prefix = library_prefix_for options.delete(:library)
+      append_class! options, prefix
+      append_class! options, "#{prefix}-#{name.to_s.gsub '_', '-'}" if name
+      content_tag :span, nil, options
+    end
+
+  private
+
+    def library_prefix_for(name)
+      case name.to_s.underscore
+        when 'font_awesome' then :fa
+        when '', 'glyphicons' then :glyphicon
+        else name
+      end
+    end
+  end
+end

data/lib/bh/helpers/link_to_helper.rb

@@ -12,10 +12,19 @@ module Bh
     # Overrides ActionView +link_to+ to be able to add the 'navbar-brand'
     # class to the link in case the link is inside of an alert.
     def link_to(*args, &block)
-      args = add_link_class!('alert-link', *args, &block) if @alert_link
-      args = add_link_class!('navbar-brand', *args, &block) if @navbar_vertical
-      link = super *args, &block
-      @nav_link ? content_tag(:li, link, nav_list_item_options(*args, &block)) : link
+      if @alert_link
+        super *add_link_class!('alert-link', *args, &block), &block
+      elsif @navbar_vertical
+        super *add_link_class!('navbar-brand', *args, &block), &block
+      elsif @dropdown_link
+        content_tag :li, role: :presentation do
+          super *add_menu_item_attributes!(*args, &block), &block
+        end
+      elsif @nav_link
+        content_tag :li, super(*args, &block), nav_item_options(*args, &block)
+      else
+        super *args, &block
+      end
     end
 
   private
@@ -24,9 +33,16 @@ module Bh
       append_class_as! :class, new_class, *args, &block
     end
 
-    def nav_list_item_options(*args, &block)
+    def nav_item_options(*args, &block)
       options = (block_given? ? args[0] : args[1]) || {}
       {class: 'active'} if current_page? options
     end
+
+    def add_menu_item_attributes!(*args, &block)
+      html_options = (block_given? ? args[1] : args[2]) || {}
+      html_options.reverse_merge! role: 'menuitem', tabindex: '-1'
+      block_given? ? args[1] = html_options : args[2] = html_options
+      args
+    end
   end
 end