bootstrap4_helper 0.0.0 → 1.0.4

data/lib/bootstrap4_helper/component.rb

@@ -0,0 +1,106 @@
+module Bootstrap4Helper
+  # This super class is meant to contain commonly used methods that
+  # all sub classes can leverage.
+  #
+  # @note Every component that inherits from this class, needs to call the parent
+  #   initialization method! In order to properly render erb blocks within the
+  #   proper context, we need the template. The only way to get this, is to pass
+  #   in the template.
+  #
+  # @note the `context` mentioned above, refers to the context of `@template` and
+  #   not to be confused with `@context` that can be found in the sub classes.
+  #   `@context` refers to the Bootstrap class context of the component.
+  #
+  class Component
+    # Used to ensure that the helpers always have the propert context for
+    # rendering and bindings.
+    #
+    # @param [Class] template
+    #
+    def initialize(template)
+      @template = template
+    end
+
+    # Used to pass all context of content_tag to the template.  This ensures
+    # proper template binding of variables and methods!
+    #
+    # @param  [String]        name
+    # @param  [Hash|NilClass] content_or_options_with_block
+    # @param  [Hash|NilClass] options
+    # @param  [Boolean]       escape
+    # @return [String]
+    #
+    def content_tag(
+      name,
+      content_or_options_with_block = nil,
+      options = nil,
+      escape = true,
+      &block
+    )
+      @template.content_tag(
+        name,
+        content_or_options_with_block,
+        options,
+        escape,
+        &block
+      )
+    end
+
+    # Used to pass all context of the capture tag to then template.  This ensures
+    # proper template binding of variables and methods!
+    #
+    # @param  [Mixed] args
+    # @return [String]
+    #
+    def capture(*args)
+      @template.capture(*args)
+    end
+
+    # Used to pass all concat references to the template.  This ensures proper
+    # binding. Concat adds a String to the template Output buffer.  Useful when
+    # trying to add a String with no block.
+    #
+    # @param  [String] text
+    # @return [String]
+    #
+    def concat(text)
+      @template.concat(text)
+    end
+
+    # Used to parse method arguments.  If the first argument is
+    # a Hash, then it is assumed that the user left off the bootstrap
+    # contectual class.  So we will assign it to `secondary` and
+    # return the Hash to be used as options.
+    #
+    # @param  [Hash|NilClass|String|Symbol] args
+    # @return [Array]
+    #
+    def parse_arguments(*args)
+      first, second = *args
+      case first
+      when Hash, NilClass
+        ['secondary', first || second]
+      when Symbol, String
+        [first, second]
+      end
+    end
+
+    # Used to generate a (hopefully) unique ID for DOM elements.  Used as a
+    # fallback if the user doesn't specify one.
+    #
+    # @return [String]
+    #
+    def uuid
+      (0...10).map { rand(65..90).chr }.join
+    end
+
+    # Used to get config settings inside of components quicker.
+    #
+    # @param  [Symbol] setting
+    # @return [Mixed]
+    #
+    def config(setting, fallback)
+      Bootstrap4Helper.config.send(setting) || fallback
+    end
+  end
+end

data/lib/bootstrap4_helper/configuration.rb

@@ -0,0 +1,34 @@
+module Bootstrap4Helper
+  # Simple configuration object for setting options for the gem.
+  #
+  # @todo Build a better, more comprehensive system.
+  #
+  class Configuration
+    DEFAULT_SETTINGS = {
+      autoload_in_views: true,
+      card_title:        :h5,
+      card_text:         :p,
+      accordion_header:  :h5,
+      badge:             :span
+    }.freeze
+
+    attr_accessor(*DEFAULT_SETTINGS.keys)
+
+    # Class constructor
+    #
+    # @param  [Hash] _args
+    # @return [ClassName]
+    #
+    def initialize(_args = {})
+      DEFAULT_SETTINGS.each { |key, value| instance_variable_set("@#{key}", value) }
+    end
+
+    # Simple predicate method
+    #
+    # @return [Boolean]
+    #
+    def autoload_in_views?
+      @autoload_in_views
+    end
+  end
+end

data/lib/bootstrap4_helper/constants.rb

@@ -0,0 +1,27 @@
+module Bootstrap4Helper
+  # Simple class for storing constants
+  #
+  #
+  class Constants
+    COMPONENTS = %i[
+      component
+      alert
+      accordion
+      accordion_group
+      badge
+      card
+      card_grouping
+      card_group
+      card_deck
+      card_column
+      configuration
+      dropdown
+      dropdown/menu
+      modal
+      nav
+      spinner
+      tab
+      tab/content
+    ].freeze
+  end
+end

data/lib/bootstrap4_helper/dropdown.rb

@@ -0,0 +1,95 @@
+module Bootstrap4Helper
+  # Builds a Dropdown component that can be used in other components.
+  #
+  #
+  class Dropdown < Component
+    # Class constructor
+    #
+    # @param [ActionView]    template
+    # @param [Symbol|String] type
+    # @param [Hash]          opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    #
+    def initialize(template, type = :dropdown, opts = {}, &block)
+      super(template)
+
+      @type    = type
+      @id      = opts.fetch(:id,    uuid)
+      @class   = opts.fetch(:class, '')
+      @data    = opts.fetch(:data,  {})
+      @content = block || proc { '' }
+    end
+
+    # Used to generate a button for the dropdown.  The buttons default as just
+    # a button that opens the coresponding dropdown menu.  The `split: true` option
+    # make the button just the arrow indicator that open the menu.
+    #
+    # @param  [Symbol] context
+    # @param  [Hash]   opts
+    # @option opts [Boolean] :split
+    # @option opts [String]  :id
+    # @option opts [String]  :class
+    # @option opts [Hash]    :data
+    # @return [String]
+    #
+    def button(context = :primary, opts = {})
+      split = opts.fetch(:split, false)
+      id    = opts.fetch(:id,    nil)
+      klass = opts.fetch(:class, '')
+      data  = opts.fetch(:data,  {}).merge(toggle: 'dropdown')
+      extra = split ? 'dropdown-toggle-split' : ''
+
+      content_tag(
+        :button,
+        id:    id,
+        type:  'button',
+        class: "dropdown-toggle btn btn-#{context} #{klass} #{extra}",
+        data:  data,
+        aria:  { haspopup: true, expanded: false }
+      ) do
+        split ? content_tag(:span, 'Toggle Dropdwon', class: 'sr-only') : yield
+      end
+    end
+
+    # Used to create a new `Dropdown::Menu`
+    #
+    # @param  [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @return [Dropdown::Menu]
+    #
+    def menu(opts = {}, &block)
+      Menu.new(@template, opts, &block)
+    end
+
+    # String reprentation of the object.
+    #
+    # @return [String]
+    #
+    def to_s
+      content_tag :div, id: @id, class: "#{container_class} #{@class}", data: @data do
+        @content.call(self)
+      end
+    end
+
+    private
+
+    # Returns the container class for the dropdown component.
+    #
+    # @return [String]
+    #
+    def container_class
+      case @type
+      when :dropdown
+        'dropdown'
+      when :group
+        'btn-group'
+      else
+        ''
+      end
+    end
+  end
+end

data/lib/bootstrap4_helper/dropdown/menu.rb

@@ -0,0 +1,140 @@
+module Bootstrap4Helper
+  class Dropdown
+    # Builds a menu component for use in dropdowns.
+    #
+    #
+    class Menu < Component
+      # Class constructor
+      #
+      # @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)
+
+        @id      = opts.fetch(:id,    uuid)
+        @class   = opts.fetch(:class, '')
+        @data    = opts.fetch(:data,  {})
+        @content = block || proc { '' }
+      end
+
+      # Use this method when the `item`, `link` in the item in the menu  is nothing
+      # more than a hyperlink.
+      #
+      # @param  [String] name
+      # @param  [Hash]   options
+      # @param  [Hash]   html_options
+      # @return [String]
+      #
+      def link(name = nil, options = nil, html_options = nil, &block)
+        html_options = (html_options || {}).merge(class: 'dropdown-item')
+
+        @template.link_to(name, options, html_options, &block)
+      end
+
+      # Use this method when you are using the item in the menu as trigger for tab
+      # content.
+      #
+      # @param [Symbol|String] target
+      # @param [Hash] opts
+      # @option opts [String]  :id
+      # @option opts [String]  :class
+      # @option opts [Hash]    :data
+      # @option opts [Hash]    :aria
+      # @return [String]
+      #
+      def item(target, opts = {})
+        id    = opts.fetch(:id,    nil)
+        klass = opts.fetch(:class, '')
+        data  = opts.fetch(:data,  {}).merge(toggle: 'tab')
+        aria  = opts.fetch(:aria,  {})
+
+        content_tag(
+          :a,
+          id:    id,
+          class: "dropdown-item #{klass}",
+          href:  "##{target}",
+          aria:  aria,
+          data:  data
+        ) do
+          block_given? ? yield : target.to_s.titleize
+        end
+      end
+
+      # Builds a Text component
+      #
+      # @param  [Symbol|String] text
+      # @param  [Hash] opts
+      # @option opts [String]  :id
+      # @option opts [String]  :class
+      # @option opts [Hash]    :data
+      # @return [String]
+      #
+      def text(text, opts = {}, &block)
+        build_sub_component :span, text, 'item-text', opts, &block
+      end
+
+      # Builds a Header component
+      #
+      # @param  [Symbol|String] text
+      # @param  [Hash] opts
+      # @option opts [String]  :id
+      # @option opts [String]  :class
+      # @option opts [Hash]    :data
+      # @return [String]
+      #
+      def header(text, opts = {}, &block)
+        build_sub_component :h6, text, 'header', opts, &block
+      end
+
+      # Builds a divider element
+      #
+      # @return [String]
+      #
+      def divider
+        content_tag :div, '', class: 'dropdown-divider'
+      end
+
+      # String representation of the object.
+      #
+      # @return [String]
+      #
+      def to_s
+        content_tag :div, id: @id, class: "dropdown-menu #{@class}", data: @data do
+          @content.call(self)
+        end
+      end
+
+      private
+
+      # Used to build specific components.
+      #
+      # @param [Symbol] tag
+      # @param [Symbol|String] text
+      # @param [Symbol|String] type
+      # @param [Hash] opts
+      # @option opts [String]  :id
+      # @option opts [String]  :class
+      # @option opts [Hash]    :data
+      # @return [String]
+      #
+      def build_sub_component(tag, text, type, opts)
+        id    = opts.fetch(:id,    nil)
+        klass = opts.fetch(:class, '')
+        data  = opts.fetch(:data,  {})
+
+        content_tag(
+          tag,
+          id:    id,
+          class: "dropdown-#{type} #{klass}",
+          data:  data
+        ) do
+          block_given? ? yield : text || ''
+        end
+      end
+    end
+  end
+end

data/lib/bootstrap4_helper/initialize.rb

@@ -0,0 +1,19 @@
+module Bootstrap4Helper
+  # Naming convention used as to not pollute views where the module is
+  # included.  @config is a common instance variable name.  We don't want
+  # to risk overriding another developers variable.
+  #
+  @_bs4h_config = Configuration.new
+
+  class << self
+    # Simple interface for exposing the configuration object.
+    #
+    # @return [Bootstrap4Helper::Configuration]
+    #
+    def config
+      yield @_bs4h_config if block_given?
+
+      @_bs4h_config
+    end
+  end
+end

data/lib/bootstrap4_helper/modal.rb

@@ -0,0 +1,167 @@
+module Bootstrap4Helper
+  # Builds a Modal window component.
+  #
+  #
+  class Modal < Component
+    # Class constructor
+    #
+    # @param  [ActionView] template
+    # @param  [Hash] opts
+    # @option opts [String]  :id
+    # @option opts [String]  :class
+    # @option opts [Hash]    :data
+    # @option opts [Boolean] :scrollable
+    # @option opts [Boolean] :vcentered
+    #
+    def initialize(template, opts = {}, &block)
+      super(template)
+
+      @id         = opts.fetch(:id,         uuid)
+      @class      = opts.fetch(:class,      '')
+      @data       = opts.fetch(:data,       {})
+      @scrollable = opts.fetch(:scrollable, false)
+      @vcentered  = opts.fetch(:vcentered,  false)
+      @content    = block || proc { '' }
+    end
+
+    # Build the header component for the modal.
+    #
+    # @param  [Hash] opts
+    # @option opts [String]  :id
+    # @option opts [String]  :class
+    # @option opts [Hash]    :data
+    # @return [String]
+    #
+    def header(opts = {}, &block)
+      build_main_component :header, opts, &block
+    end
+
+    # Builds the body component.
+    #
+    # @param  [Hash] opts
+    # @option opts [String]  :id
+    # @option opts [String]  :class
+    # @option opts [Hash]    :data
+    # @return [String]
+    #
+    def body(opts = {}, &block)
+      build_main_component :body, opts, &block
+    end
+
+    # Builds the footer component.
+    #
+    # @param  [Hash] opts
+    # @option opts [String]  :id
+    # @option opts [String]  :class
+    # @option opts [Hash]    :data
+    # @return [String]
+    #
+    def footer(opts = {}, &block)
+      build_main_component :footer, opts, &block
+    end
+
+    # Builds a title component.
+    #
+    # @param  [Hash] opts
+    # @option opts [String]  :id
+    # @option opts [String]  :class
+    # @option opts [Hash]    :data
+    # @return [String]
+    #
+    def title(opts = {}, &block)
+      build_sub_component :h5, :title, opts, &block
+    end
+
+    # Builds a close button component.
+    #
+    # @param  [Hash] opts
+    # @option opts [String] :class
+    # @return [String]
+    #
+    def close_button(opts = {})
+      klass = opts.fetch(:class, '')
+
+      content_tag(
+        :button,
+        type:  'button',
+        class: block_given? ? klass : 'close',
+        data:  { dismiss: 'modal' },
+        aria:  { label: 'Close' }
+      ) do
+        block_given? ? yield : xbutton
+      end
+    end
+
+    # String representation of the object.
+    #
+    # @return [String]
+    #
+    def to_s
+      content_tag :div, id: @id, class: "modal #{@class}", tabindex: -1, role: 'dialog', data: @data do
+        content_tag :div, class: "modal-dialog #{scrollable} #{vcentered}", role: 'document' do
+          content_tag(:div, class: 'modal-content') { @content.call(self) }
+        end
+      end
+    end
+
+    private
+
+    # Used to build main components, usually divs.
+    #
+    # @param  [Symbol|String] type
+    # @param  [Hash] opts
+    # @return [String]
+    #
+    def build_main_component(type, opts = {}, &block)
+      build_sub_component :div, type, opts, &block
+    end
+
+    # Used to build more specific components.
+    #
+    # @param [Symbol] tag
+    # @param [Symbol|String] type
+    # @param [Hash] opts
+    # @option opts [String]  :id
+    # @option opts [String]  :class
+    # @option opts [Hash]    :data
+    # @return [String]
+    #
+    def build_sub_component(tag, type, opts = {}, &block)
+      id    = opts.fetch(:id,    nil)
+      klass = opts.fetch(:class, '')
+      data  = opts.fetch(:data,  {})
+
+      content_tag(
+        tag,
+        id:    id,
+        class: "modal-#{type} #{klass}",
+        data:  data,
+        &block
+      )
+    end
+
+    # Builds the `x` button normally used in the header.
+    #
+    # @return [String]
+    #
+    def xbutton
+      content_tag :span, '&times;'.html_safe, aria: { hidden: true }
+    end
+
+    # Gets the scrollable CSS class.
+    #
+    # @return [String]
+    #
+    def scrollable
+      @scrollable ? 'modal-dialog-scrollable' : ''
+    end
+
+    # Gets the vertical-center CSS class.
+    #
+    # @return [String]
+    #
+    def vcentered
+      @vcentered ? 'modal-dialog-centered' : ''
+    end
+  end
+end