bootstrap3_helper 1.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7690ea3af6632902048f7f389e97a9c2317e007c6dab849b754fabe805a7357e
-  data.tar.gz: 2c8234630ce566f379f1d1a46d9ab7e47e958c3b1059df4aa41a0003a27700bc
+  metadata.gz: 4052a52cedf01461e605010a66bbf78a2f1741e4046a755495226edeccff6027
+  data.tar.gz: 538817f6096634dcfead3335a03198f34bcecc987d95d22561f79e34553ffa50
 SHA512:
-  metadata.gz: d54b3740ae4f7bd45adcea82506ebe65fae16dcca0837c42e83ada33480c67053acaee9112ffe7029283d2d4babe71d0cfbe9183e97b8d30e886527fd2cf70e5
-  data.tar.gz: 5e42f3ff987c0e32aa5f2b5dd94c744abc7d4afbadeb41ee17da5b1cfd64b5975a123aa4d3d135e9dd2871fa9abd1ee3ec7d6862cd41d53a8bc41ece2e9a6ea8
+  metadata.gz: bc609fbe4d4cb0d76fcd70155ee21b9edb27741cd4b590bacce764408d34ca4fc47232ba4458fb6a657c9c4894a7310675ac6d774ae6ad567a31724b8fd52ebb
+  data.tar.gz: c6e1cdca50954072d204055706352aca4ee29abaa394749d1c623b2ce9eb43d970c3d5da51663cd641ccee0a98382459ebf4ee8f169ef3acc044186940c7b17b

data/README.md

@@ -1,4 +1,4 @@
-# Bootstrap3Helper
+# Bootstrap 3 Helper
 
 This gem was designed to help you rapidly build common Bootstrap 3 Components. They where designed to very flexible and reduce a lot of boiler plate HTML.
 
@@ -18,14 +18,42 @@ Or install it yourself as:
 
     $ gem install bootstrap3_helper
 
-## Usage
+## Panel Helper
 
-`Panel Helper`
+Panels supper the following methods:
+
+- body
+- heaader
+- footer
+- title
+
+```ruby
+# @overload panel_helper(context, opts)
+#   @param  [String|Symbol] context - :primary, :danger etc
+#   @param  [Hash] opts
+#   @option opts [String] :id
+#   @option opts [String] :class
+#   @option opts [Hash]   :data
+#   @option opts [Hash]   :aria
+#
+# @overload panel_helper(opts)
+#   @param  [Hash] opts
+#   @option opts [String] :id
+#   @option opts [String] :class
+#   @option opts [Hash]   :data
+#   @option opts [Hash]   :aria
+#
+# @yieldparam [Panel] panel
+# @return [String]
+```
+
+#### Example
 
 ```erb
 <%= panel_helper :primary do |p| %>
   <%= p.header id: 'optional-id', class: 'any-optional-extra-classes' do %>
-    Some Header for your panel
+    <%= p.header { 'Optional header title' }  %>
+    <p>Non styled content for header...</p>
   <% end %>
   <%= p.body id: 'optional-id', class: 'any-optional-extra-classes' do %>
      All your custom HTML or Ruby.  You can render blocks here, whatever
@@ -37,9 +65,25 @@ Or install it yourself as:
 end
 ```
 
----
+## Alert Helper
 
-`Alert Helper`
+```ruby
+# @overload alert_helper(context, opts)
+#   @param  [Symbol|String] context - :primary, :danger etc
+#   @param  [Hash] opts
+#   @option opts [String]  :id
+#   @option opts [String]  :class
+#   @option opts [Boolean] :dismissible
+#
+# @overload alert_helper(opts)
+#   @param  [Hash] opts
+#   @option opts [String] :id
+#   @option opts [String] :class
+#
+# @return [String]
+```
+
+### Example
 
 ```erb
 <%= alert_helper :success { 'Some success message' } %>
@@ -51,12 +95,28 @@ end
 <% end %>
 ```
 
----
+## Acordion Helper
 
-`Accordion Helper`
+```ruby
+# @overload accordion_helper(context, opts)
+#   @param  [Symbol|String] context - :primary, :danger etc
+#   @param  [Hash] opts
+#   @option opts [String] :id
+#   @option opts [String] :class
+#
+# @overload accordion_helper(opts)
+#   @param  [Hash] opts
+#   @option opts [String] :id
+#   @option opts [String] :class
+#
+# @yieldparam [Accordion] accordion
+# @return [String]
+```
+
+### Example
 
 ```erb
-<%= accordion_helper :primary, { class: 'optional-class', id: 'optional_id', collapse_id: 'optional_collapse_id', expanded: true } do |accordion| %>
+<%= accordion_helper :primary, id: 'optional_id', expanded: true do |accordion| %>
     <%= accordion.header do %>
         <span class="something">This is the heading....</span>
     <% end %>
@@ -66,11 +126,19 @@ end
 <% end %>
 ```
 
-**Note:** the accordion helper handles all the attributes and data attributes needed to sync up the javascript in order to give the component its functionality. You just worry about about the class or state of the component. The helper does the rest. But if you do want to control the collapse ID and syncing, `collapse_id` is the attribute you are looking for.
+**Note:** the accordion helper handles all the attributes and data attributes needed to sync up the javascript in order to give the component its functionality. You just worry about about the class or state of the component. The helper does the rest. But if you do want to control the collapse ID and syncing, `collapse_id` is the parameter you are looking for.
 
----
+## Accordion Group
 
-`AccordionGroup Helper`
+```ruby
+# @param  [Hash] opts
+# @option opts [String] :id
+# @option opts [String] :class
+# @yieldparam [AccordionGroup] group
+# @return [String]
+```
+
+### Example
 
 ```erb
 <%= accordion_group_helper do |g| %>
@@ -79,7 +147,7 @@ end
         <%= accordion.body do %>
             <p>This is accordion 1</p>
         <% end %>
-    <%end %>
+    <% end %>
     <% g.accordion :info do |accordion| %>
         <%= accordion.header { "Accordion 2" } %>
         <%= accordion.body do %>
@@ -91,45 +159,62 @@ end
         <%= accordion.body do %>
             <p>This is accordion 3</p>
         <% end %>
-    <%end %>
+    <% end %>
 <% end %>
 ```
 
-**Note:** the accordion_group helper handles all the attributes and data attributes needed to sync up the javascript in order to give the component its functionality. You just worry about about the class or state of the individual accordions. The helper does the rest.
+## Tab Helper
 
----
+Tabs respond to the following methods:
 
-`Panel Helper`
+- menu
+  - item (Used for linking to tab content)
+  - dropdown (Used for making dropdown menus)
+- content
 
-```erb
-<%= tabs_helper type: :pills do |menu, content| %>
-    <% menu.item(:testing1, class: 'active') { ' Testing 1' } %>
-    <% menu.item :testing2 %>
-    <% menu.item(:testing3) { ' Testing 3' } %>
-    <% menu.dropdown 'Testing Dropdown' do |dropdown| %>
-        <%= dropdown.item(:testing5 ) { 'Testing 5' } %>
-        <%= dropdown.item(:testing6 ) { 'Testing 6' } %>
-        <%= dropdown.item(:testing7 ) { 'Testing 7' } %>
-    <% end %>
+```ruby
+# @param  [Hash] opts
+# @option args [String|Symbol] :type - :tabs, :pills
+# @option args [String]        :id
+# @option args [String]        :class
+# @yieldparam [Tabs] tabs
+# @return [String]
+```
 
+### Example
 
-    <% content.item :testing1, class: 'active' do %>
-        Testing 1 content
-    <% end %>
-    <% content.item :testing2 do %>
-        Testing 2 content
-    <% end %>
-    <% content.item :testing3 do %>
-        Testing 3 content
-    <% end %>
-    <% content.item :testing5 do %>
-        Testing 5 content
-    <% end %>
-    <% content.item :testing6 do %>
-        Testing 6 content
+```erb
+<%= tabs_helper type: :pills do |tabs| %>
+    <%= tabs.menu do |menu| %>
+        <%= menu.item(:testing1, class: 'active') { ' Testing 1' } %>
+        <%= menu.item :testing2 %>
+        <%= menu.item(:testing3) { ' Testing 3' } %>
+        <%= menu.dropdown 'Testing Dropdown' do |dropdown| %>
+            <%= dropdown.item(:testing5 ) { 'Testing 5' } %>
+            <%= dropdown.item(:testing6 ) { 'Testing 6' } %>
+            <%= dropdown.item(:testing7 ) { 'Testing 7' } %>
+        <% end %>
     <% end %>
-    <% content.item :testing7 do %>
-        Testing 7 content
+
+    <%= tabs.content do |content| %>
+        <% content.pane :testing1, class: 'active' do %>
+            Testing 1 content
+        <% end %>
+        <% content.pane :testing2 do %>
+            Testing 2 content
+        <% end %>
+        <% content.pane :testing3 do %>
+            Testing 3 content
+        <% end %>
+        <% content.pane :testing5 do %>
+            Testing 5 content
+        <% end %>
+        <% content.pane :testing6 do %>
+            Testing 6 content
+        <% end %>
+        <% content.pane :testing7 do %>
+            Testing 7 content
+        <% end %>
     <% end %>
 <% end %>
 ```

data/lib/bootstrap3_helper/accordion.rb

@@ -1,169 +1,134 @@
-# @root
-#
-#
-module Bootstrap3Helper
-  # @description
-  # - Used to generate Bootstrap Accordion objects.
+module Bootstrap3Helper # :nodoc:
+  # Used to generate Bootstrap Accordion objects.
   #
-  #  <code>
-  #    <%= accordion_helper :primary do |accordion| %>
-  #        <%= accordion.header do %>
-  #            <span class="something">This is the heading....</span>
-  #        <% end %>
-  #        <%= accordion.body do %>
-  #            <p>This is the body of the accordion....</p>
-  #        <% end %>
-  #    <% end %>
-  #  </code>
   #
   class Accordion < Component
-    # @description
-    # - Initlize a new accordion object.  If this part of a parent element, i.e
+    # Initlize a new accordion object.  If this part of a parent element, i.e
     # AccordionGroup, we need to keep track of the parent element id, so we can
     # pass it down to the other components.
     #
     # @param [Class] template - Template in which your are binding too.
-    # @param [NilClass|String|Symbol|Hash] - Bootstrap class context, or options hash.
+    # @param [NilClass|String|Symbol|Hash] context_or_options Bootstrap class context, or options hash.
     # @param [Hash] opts
-    #   <code>
-    #      args = {
-    #        parent_id:   [String]
-    #        id:          [String]
-    #        class:       [String]
-    #        collapse_id: [String]
-    #        expanded:    Boolean
-    #      }
-    #   </code>
+    # @option opts [String]  :parent_id   The parent element ID if this accordion is part of a group.
+    # @option opts [String]  :id          The ID of the element
+    # @option opts [String]  :class       Custom class for the component.
+    # @option opts [String]  :collapse_id The ID of the element to collapse when clicked.
+    # @option opts [Boolean] :expanded    Initial state of the accordion.
     # @return [Accordion]
     #
-    def initialize(template, context_or_options = nil, opts = {})
+    def initialize(template, context_or_options = nil, opts = {}, &block)
       super(template)
-      @context, args = parse_arguments(context_or_options, opts)
+      @context, args = parse_context_or_options(context_or_options, opts)
 
       @parent_id   = args.fetch(:parent_id, nil)
       @id          = args.fetch(:id, nil)
       @class       = args.fetch(:class, '')
       @collapse_id = args.fetch(:collapse_id, uuid)
       @expanded    = args.fetch(:expanded, false)
+      @content     = block || proc { '' }
+      @panel       = Panel.new(@template, context_or_options, opts)
     end
 
-    # @description
-    # - Creates the header element for the accordion
-    #
-    # @note
-    # - NilClass :to_s  returns an empty String
-    #
-    # @params [Hash] args
-    #   <code>
-    #      args = {
-    #        id:      [String]
-    #        class:   [String]
-    #        data:    [Hash]
-    #      }
-    #   </code>
-    #
-    # @yields [Accordion] self
-    # @return [NilClass]
+    # Creates the header element for the accordion
+    #
+    # @param  [Symbol|String|Hash|NilClass] tag_or_options
+    # @param  [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @option opts [Hash]   :aria
+    # @return [String]
     #
-    # rubocop:disable Metrics/MethodLength
-    def header(args = {})
-      id    = args.fetch(:id, nil)
-      klass = args.fetch(:class, '')
-      data  = args.fetch(:data, {})
+    def header(tag_or_options = nil, opts = {}, &block)
+      tag, args = parse_tag_or_options(tag_or_options, opts)
 
+      data          = {}
       data[:toggle] = 'collapse'
-      data[:parent] = "##{@parent_id}"
+      data[:parent] = "##{@parent_id}" if @parent_id.present?
+      data[:target] = "##{@collapse_id}"
 
-      @header = content_tag :div, id: id, class: 'panel-heading ' + klass do
-        content_tag :h3, class: 'panel-title' do
-          content_tag :a, href: "##{@collapse_id}", data: data do
-            content = yield if block_given?
-            content.to_s.html_safe
-          end
-        end
+      @panel.header(tag, args.merge!(config_for: :accordions)) do
+        content_tag(
+          :span,
+          role: 'button',
+          data: data,
+          aria: { expanded: @expanded, controls: "##{@collapse_id}" },
+          &block
+        )
       end
     end
-    # rubocop:enable Metrics/MethodLength
 
-    # @description
-    # - Creates the body element for the accordion.
-    #
-    # @note
-    # - NilClass :to_s  returns an empty String
+    # Builds a title component for the accordion header.
+    #
+    # @param  [Symbol|String|Hash|NilClass] tag_or_options
+    # @param  [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @option opts [Hash]   :aria
+    # @return [String]
     #
-    # @params [Hash] args
-    #   <code>
-    #      args = {
-    #        id:      [String]
-    #        class:   [String]
-    #        data:    [Hash]
-    #      }
-    #   </code>
+    def title(tag_or_options = nil, opts = {}, &block)
+      tag, args = parse_tag_or_options(tag_or_options, opts)
+      @panel.title(tag, args.merge!(config_for: :accordions), &block)
+    end
+
+    # Creates the body element for the accordion.
     #
-    # @yields [Accordion] self
-    # @return [nilClass]
+    # @note NilClass :to_s  returns an empty String
     #
+    # @param [Hash] args
+    # @option args [String] :id
+    # @option args [String] :class
+    # @option args [Hash]   :data
+    # @yieldreturn [String]
     #
-    def body(args = {})
+    def body(tag_or_options = nil, opts = {}, &block)
+      tag, args = parse_tag_or_options(tag_or_options, opts)
+
       klass = 'panel-collapse collapse '
-      data  = args.fetch(:data, {})
-      klass += args.fetch(:class, '')
       klass += ' in' if @expanded
 
-      @body = content_tag :div, id: @collapse_id, class: klass do
-        content_tag :div, class: 'panel-body', data: data do
-          content = yield if block_given?
-          content.to_s.html_safe
-        end
+      content_tag(
+        :div,
+        id:    @collapse_id,
+        role:  'tabpanel',
+        class: klass,
+        aria:  { labelledby: "##{@collapse_id}" }
+      ) do
+        @panel.body(tag, args.merge!(config_for: :accordions), &block)
       end
     end
 
-    # @description
-    # - Creates the footer element for the accordion
-    #
-    # @params [Hash] args
-    #   <code>
-    #      args = {
-    #        id:      [String]
-    #        class:   [String]
-    #        data:    [Hash]
-    #      }
-    #   </code>
-    #
-    # @yields [Accordion] self
-    # @return [nilClass]
+    # Creates the footer element for the accordion
     #
+    # @param [Hash] args
+    # @option args [String] :id
+    # @option args [String] :class
+    # @option args [Hash]   :data
+    # @return [String]
     #
-    def footer(args = {})
-      id    = args.fetch(:id, nil)
-      klass = args.fetch(:class, '')
-      data  = args.fetch(:data, {})
-
-      @footer = content_tag :div, id: id, class: 'panel-footer ' + klass, data: data do
-        content = yield if block_given?
-        content.to_s.html_safe
-      end
+    def footer(tag_or_options = nil, opts = {}, &block)
+      tag, args = parse_tag_or_options(tag_or_options, opts)
+      @panel.footer(tag, args.merge!(config_for: :accordions), &block)
     end
 
-    # @description
-    # - The to string method here is what is responsible for rendering out the
+    # The to string method here is what is responsible for rendering out the
     # accordion element.  As long as the main method is rendered out in the
     # helper, you will get the entire accordion.
     #
     # @return [String]
     #
     def to_s
-      content = content_tag :div, id: @id, class: container_classes do
-        @header + @body + @footer
+      content_tag :div, id: @id, class: container_classes do
+        @content.call(self)
       end
-
-      content
     end
 
     private
 
-    # @description
-    # - Used to get the container element classes
+    # Used to get the container element classes
     #
     # @return [String]
     #

data/lib/bootstrap3_helper/accordion_group.rb

@@ -1,88 +1,79 @@
-# @root
-#
-#
-module Bootstrap3Helper
-  # @description
-  # - This class is used to general groups of accordions.
+module Bootstrap3Helper # :nodoc:
+  # This class is used to general groups of accordions.
   #
-  # <code>
-  #   <%= accordion_group_helper do |group| %>
-  #     <%= group.accordion :primary do |accordion| %>
-  #         <%= accordion.header { "accordion 1" } %>
-  #         <%= accordion.body do %>
-  #             <p>This is accordion 1</p>
-  #         <% end %>
+  # @example Rendering out an Accordion Group in template:
+  #   <code>
+  #     <%= accordion_group_helper do |group| %>
+  #       <%= group.accordion :primary do |accordion| %>
+  #           <%= accordion.header { "accordion 1" } %>
+  #           <%= accordion.body do %>
+  #               <p>This is accordion 1</p>
+  #           <% end %>
+  #       <% end %>
+  #       <%= group.accordion :info do |accordion| %>
+  #           <%= accordion.header { "accordion 2" } %>
+  #           <%= accordion.body do %>
+  #               <p>This is accordion 2</p>
+  #           <% end %>
+  #       <% end %>
+  #       <%= group.accordion :danger do |accordion| %>
+  #           <%= accordion.header { "accordion 3" } %>
+  #           <%= accordion.body do %>
+  #               <p>This is accordion 3</p>
+  #           <% end %>
+  #       <% end %>
   #     <% end %>
-  #     <%= group.accordion :info do |accordion| %>
-  #         <%= accordion.header { "accordion 2" } %>
-  #         <%= accordion.body do %>
-  #             <p>This is accordion 2</p>
-  #         <% end %>
-  #     <% end %>
-  #     <%= group.accordion :danger do |accordion| %>
-  #         <%= accordion.header { "accordion 3" } %>
-  #         <%= accordion.body do %>
-  #             <p>This is accordion 3</p>
-  #         <% end %>
-  #     <% end %>
-  #   <% end %>
-  # </code>
+  #   </code>
   #
   class AccordionGroup < Component
-    # @description
-    # - Used to initialize the main object.  This objects sole purpose is to
+    # Used to initialize the main object.  This objects sole purpose is to
     # generate a wrapper element with a distinct id and pass that id down to
     # all the child elements.
     #
-    def initialize(template, opts = {})
+    # @param [ActionView] template
+    # @param [Hash]       opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    #
+    def initialize(template, opts = {}, &block)
       super(template)
-      @accordions = []
-      @id = opts.fetch(:id, uuid)
-      @class = opts.fetch(:class, '')
+
+      @id      = opts.fetch(:id,    uuid)
+      @class   = opts.fetch(:class, '')
+      @data    = opts.fetch(:data,  {})
+      @content = block || proc { '' }
     end
 
-    # @description
-    # - This method is the main method for generating individual accordions.
+    # This method is the main method for generating individual accordions.
     # This is where you would pass in the html attributes.
     #
-    # @param [NilClass|String|Symbol|Hash] - Bootstrap class context, or options hash.
+    # @param [NilClass|String|Symbol|Hash] context_or_options
     # @param [Hash] opts
-    # <code>
-    #    args = {
-    #      id:      [String]
-    #      class:   [String]
-    #    }
-    # </code>
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @yieldreturn [Accordion] accordion
     #
-    # @yields [Accordion] accordion
-    # @return [nilClass]
-    #
-    def accordion(context_or_options = nil, opts = {})
+    def accordion(context_or_options = nil, opts = {}, &block)
       if context_or_options.is_a?(Hash)
         context_or_options[:parent_id] = @id
       else
         opts[:parent_id] = @id
       end
 
-      accordion = Accordion.new(@template, context_or_options, opts)
-      yield accordion if block_given?
-
-      @accordions.push(accordion)
+      Accordion.new(@template, context_or_options, opts, &block)
     end
 
-    # @description
-    # - The to string method here is what is responsible for rendering out the
+    # The to string method here is what is responsible for rendering out the
     # entire accordion.  As long as the main method is rendered out in the helper,
     # you will get all the contents.
     #
     # @return [String]
     #
     def to_s
-      content = content_tag :div, id: @id, class: "panel-group #{@class}" do
-        @accordions.map(&:to_s).join.html_safe
+      content_tag :div, id: @id, class: "panel-group #{@class}" do
+        @content.call(self)
       end
-
-      content
     end
   end
 end