hanami-helpers 0.0.0 → 0.3.0

data/lib/hanami/helpers/form_helper/html_node.rb

@@ -0,0 +1,79 @@
+require 'hanami/helpers/html_helper/html_node'
+
+module Hanami
+  module Helpers
+    module FormHelper
+      # HTML form node
+      #
+      # @since 0.2.0
+      # @api private
+      #
+      # @see Hanami::Helpers::HtmlHelper::HtmlNode
+      class HtmlNode < ::Hanami::Helpers::HtmlHelper::HtmlNode
+        # Initialize a new HTML form node
+        #
+        # @param name [Symbol,String] the name of the tag
+        # @param content [String,Proc,Hanami::Helpers::HtmlHelper::FormBuilder,NilClass] the optional content
+        # @param attributes [Hash,NilClass] the optional tag attributes
+        # @param options [Hash] a set of data
+        #
+        # @return [Hanami::Helpers::FormHelper::HtmlNode]
+        #
+        # @since 0.2.0
+        # @api private
+        def initialize(name, content, attributes, options)
+          super
+
+          @verb       = options.fetch(:verb,       nil)
+          @csrf_token = options.fetch(:csrf_token, nil)
+
+          @builder = FormBuilder.new(
+            options.fetch(:name),
+            options.fetch(:values)
+          )
+        end
+
+        private
+        # Resolve the (nested) content
+        #
+        # @return [String] the content
+        #
+        # @since 0.2.0
+        # @api private
+        #
+        # @see Hanami::Helpers::HtmlHelper::HtmlNode#content
+        def content
+          _method_override!
+          _csrf_protection!
+          super
+        end
+
+        # Inject a hidden field to make Method Override possible
+        #
+        # @since 0.2.0
+        # @api private
+        def _method_override!
+          return if @verb.nil?
+
+          verb = @verb
+          @builder.resolve do
+            input(type: :hidden, name: :_method, value: verb)
+          end
+        end
+
+        # Inject a hidden field for CSRF Protection token
+        #
+        # @since 0.2.0
+        # @api private
+        def _csrf_protection!
+          return if @csrf_token.nil?
+
+          _csrf_token = @csrf_token
+          @builder.resolve do
+            input(type: :hidden, name: FormHelper::CSRF_TOKEN, value: _csrf_token)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanami/helpers/form_helper/values.rb

@@ -0,0 +1,38 @@
+require 'hanami/utils/hash'
+
+module Hanami
+  module Helpers
+    module FormHelper
+      class Values
+        GET_SEPARATOR = '.'.freeze
+
+        def initialize(values, params)
+          @values = Utils::Hash.new(values).stringify!
+          @params = params
+        end
+
+        def get(key)
+          @params.get(key) || _get_from_values(key)
+        end
+
+        private
+        def _get_from_values(key)
+          initial_key, *keys = key.to_s.split(GET_SEPARATOR)
+          result             = @values[initial_key]
+
+          Array(keys).each do |k|
+            break if result.nil?
+
+            result = if result.respond_to?(k)
+              result.public_send(k)
+            else
+              nil
+            end
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/hanami/helpers/html_helper.rb

@@ -0,0 +1,207 @@
+require 'hanami/helpers/html_helper/html_builder'
+
+module Hanami
+  module Helpers
+    # HTML builder
+    #
+    # By including <tt>Hanami::Helpers::HtmlHelper</tt> it will inject one private method: <tt>html</tt>.
+    # This is a HTML5 markup builder.
+    #
+    # Features:
+    #   * Support for complex markup without the need of concatenation
+    #   * Auto closing HTML5 tags
+    #   * Custom tags
+    #   * Content tag auto escape (XSS protection)
+    #   * Support for view local variables
+    #
+    # Usage:
+    #
+    #   * It knows how to close tags according to HTML5 spec (1)
+    #   * It accepts content as first argument (2)
+    #   * It accepts another builder as first argument (3)
+    #   * It accepts content as block which returns a string (4)
+    #   * It accepts content as a block with nested markup builders (5)
+    #   * It builds attributes from given hash (6)
+    #   * It combines attributes and block (7)
+    #
+    # @since 0.1.0
+    #
+    # @see Hanami::Helpers::HtmlHelper#html
+    #
+    # @example Usage
+    #   # 1
+    #   html.div # => <div></div>
+    #   html.img # => <img>
+    #
+    #   # 2
+    #   html.div('hello') # => <div>hello</div>
+    #
+    #   # 3
+    #   html.div(html.p('hello')) # => <div><p>hello</p></div>
+    #
+    #   # 4
+    #   html.div { 'hello' }
+    #   # =>
+    #   #<div>
+    #   #  hello
+    #   #</div>
+    #
+    #   # 5
+    #   html.div do
+    #     p 'hello'
+    #   end
+    #   # =>
+    #   #<div>
+    #   #  <p>hello</p>
+    #   #</div>
+    #
+    #   # 6
+    #   html.div('hello', id: 'el', 'data-x': 'y') # => <div id="el" data-x="y">hello</div>
+    #
+    #   # 7
+    #   html.div(id: 'yay') { 'hello' }
+    #   # =>
+    #   #<div id="yay">
+    #   #  hello
+    #   #</div>
+    #
+    #   # 8
+    #   html do
+    #     li 'Hello'
+    #     li 'Hanami'
+    #   end
+    #   # =>
+    #   #<li>Hello</li>
+    #   #<li>Hanami</li>
+    #
+    #
+    #
+    # @example Complex markup
+    #   #
+    #   # NOTICE THE LACK OF CONCATENATION BETWEEN div AND input BLOCKS <3
+    #   #
+    #
+    #   html.form(action: '/users', method: 'POST') do
+    #     div do
+    #       label 'First name', for: 'user-first-name'
+    #       input type: 'text', id: 'user-first-name', name: 'user[first_name]', value: 'L'
+    #     end
+    #
+    #     input type: 'submit', value: 'Save changes'
+    #   end
+    #   # =>
+    #   #<form action="/users" method="POST" accept-charset="utf-8">
+    #   #  <div>
+    #   #    <label for="user-first-name">First name</label>
+    #   #    <input type="text" id="user-first-name" name="user[first_name]" value="L">
+    #   #  </div>
+    #   #  <input type="submit" value="Save changes">
+    #   #</form>
+    #
+    #
+    #
+    # @example Custom tags
+    #   html.tag(:custom, 'Foo', id: 'next') # => <custom id="next">Foo</custom>
+    #   html.empty_tag(:xr, id: 'next')      # => <xr id="next">
+    #
+    #
+    #
+    # @example Auto escape
+    #  html.div('hello')         # => <div>hello</hello>
+    #  html.div { 'hello' }      # => <div>hello</hello>
+    #  html.div(html.p('hello')) # => <div><p>hello</p></hello>
+    #  html.div do
+    #    p 'hello'
+    #  end # => <div><p>hello</p></hello>
+    #
+    #
+    #
+    #  html.div("<script>alert('xss')</script>")
+    #    # =>  "<div>&lt;script&gt;alert(&apos;xss&apos;)&lt;&#x2F;script&gt;</div>"
+    #
+    #  html.div { "<script>alert('xss')</script>" }
+    #    # =>  "<div>&lt;script&gt;alert(&apos;xss&apos;)&lt;&#x2F;script&gt;</div>"
+    #
+    #  html.div(html.p("<script>alert('xss')</script>"))
+    #    # => "<div><p>&lt;script&gt;alert(&apos;xss&apos;)&lt;&#x2F;script&gt;</p></div>"
+    #
+    #  html.div do
+    #    p "<script>alert('xss')</script>"
+    #  end
+    #    # => "<div><p>&lt;script&gt;alert(&apos;xss&apos;)&lt;&#x2F;script&gt;</p></div>"
+    #
+    #
+    # @example Basic usage
+    #   #
+    #   # THE VIEW CAN BE A SIMPLE RUBY OBJECT
+    #   #
+    #
+    #   require 'hanami/helpers'
+    #
+    #   class MyView
+    #     include Hanami::Helpers::HtmlHelper
+    #
+    #     # Generates
+    #     # <aside id="sidebar">
+    #     #    <div>hello</hello>
+    #     #  </aside>
+    #     def sidebar
+    #       html.aside(id: 'sidebar') do
+    #         div 'hello'
+    #       end
+    #     end
+    #   end
+    #
+    #
+    # @example View context
+    #   #
+    #   # LOCAL VARIABLES FROM VIEWS ARE AVAILABLE INSIDE THE NESTED BLOCKS OF HTML BUILDER
+    #   #
+    #
+    #   require 'hanami/view'
+    #   require 'hanami/helpers'
+    #
+    #   Book = Struct.new(:title)
+    #
+    #   module Books
+    #     class Show
+    #       include Hanami::View
+    #       include Hanami::Helpers::HtmlHelper
+    #
+    #       def title_widget
+    #         html.div do
+    #           h1 book.title
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    #   book     = Book.new('The Work of Art in the Age of Mechanical Reproduction')
+    #   rendered = Books::Show.render(format: :html, book: book)
+    #
+    #   rendered
+    #     # => <div>
+    #     #      <h1>The Work of Art in the Age of Mechanical Reproduction</h1>
+    #     #    </div>
+    module HtmlHelper
+      private
+      # Instantiate an HTML builder
+      #
+      # @param blk [Proc,Hanami::Helpers::HtmlHelper::HtmlBuilder,NilClass] the optional content block
+      #
+      # @return [Hanami::Helpers::HtmlHelper::HtmlBuilder] the HTML builder
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Helpers::HtmlHelper
+      # @see Hanami::Helpers::HtmlHelper::HtmlBuilder
+      def html(&blk)
+        if block_given?
+          HtmlBuilder.new.fragment(&blk)
+        else
+          HtmlBuilder.new
+        end
+      end
+    end
+  end
+end

data/lib/hanami/helpers/html_helper/empty_html_node.rb

@@ -0,0 +1,92 @@
+module Hanami
+  module Helpers
+    module HtmlHelper
+      # Empty HTML node
+      #
+      # @since 0.1.0
+      # @api private
+      class EmptyHtmlNode
+        # List of attributes that get special treatment when rendering.
+        #
+        # @since 0.2.5
+        # @api private
+        #
+        # @see http://www.w3.org/html/wg/drafts/html/master/infrastructure.html#boolean-attribute
+        BOOLEAN_ATTRIBUTES = %w{allowfullscreen async autobuffer autofocus
+          autoplay checked compact controls declare default defaultchecked
+          defaultmuted defaultselected defer disabled draggable enabled
+          formnovalidate hidden indeterminate inert ismap itemscope loop
+          multiple muted nohref noresize noshade novalidate nowrap open
+          pauseonexit pubdate readonly required reversed scoped seamless
+          selected sortable spellcheck translate truespeed typemustmatch
+          visible
+        }.freeze
+
+        # Attributes separator
+        #
+        # @since 0.1.0
+        # @api private
+        ATTRIBUTES_SEPARATOR = ' '.freeze
+
+        # Initialize a new empty HTML node
+        #
+        # @param name [Symbol,String] the name of the tag
+        # @param attributes [Hash,NilClass] the optional tag attributes
+        #
+        # @return [Hanami::Helpers::HtmlHelper::EmptyHtmlNode]
+        #
+        # @since 0.1.0
+        # @api private
+        def initialize(name, attributes)
+          @name       = name
+          @attributes = attributes
+        end
+
+        # Resolve and return the output
+        #
+        # @return [String] the output
+        #
+        # @since 0.1.0
+        # @api private
+        def to_s
+          %(<#{ @name }#{attributes}>)
+        end
+
+        private
+        # Resolve the attributes
+        #
+        # @return [String,NilClass] the tag attributes
+        #
+        # @since 0.1.0
+        # @api private
+        def attributes
+          return if @attributes.nil?
+          result = ''
+
+          @attributes.each do |attribute_name, value|
+            if boolean_attribute?(attribute_name)
+              result << boolean_attribute(attribute_name, value) if value
+            else
+              result << attribute(attribute_name, value)
+            end
+          end
+
+          result
+        end
+
+        def boolean_attribute?(attribute_name)
+          BOOLEAN_ATTRIBUTES.include?(attribute_name.to_s)
+        end
+
+        # Do not render boolean attributes when their value is _false_.
+        def boolean_attribute(attribute_name, value)
+          %(#{ATTRIBUTES_SEPARATOR}#{ attribute_name }="#{ attribute_name }")
+        end
+
+        def attribute(attribute_name, value)
+          %(#{ATTRIBUTES_SEPARATOR}#{ attribute_name }="#{ value }")
+        end
+      end
+    end
+  end
+end

data/lib/hanami/helpers/html_helper/html_builder.rb

@@ -0,0 +1,376 @@
+require 'hanami/utils' # RUBY_VERSION >= '2.2'
+require 'hanami/utils/class_attribute'
+require 'hanami/utils/escape'
+require 'hanami/helpers/html_helper/empty_html_node'
+require 'hanami/helpers/html_helper/html_node'
+require 'hanami/helpers/html_helper/html_fragment'
+require 'hanami/helpers/html_helper/text_node'
+
+module Hanami
+  module Helpers
+    module HtmlHelper
+      # HTML Builder
+      #
+      # @since 0.1.0
+      class HtmlBuilder
+        # HTML5 content tags
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @see Hanami::Helpers::HtmlHelper::HtmlNode
+        # @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element
+        CONTENT_TAGS = [
+          'a',
+          'abbr',
+          'address',
+          'article',
+          'aside',
+          'audio',
+          'b',
+          'bdi',
+          'bdo',
+          'blockquote',
+          'body',
+          'button',
+          'canvas',
+          'caption',
+          'cite',
+          'code',
+          'colgroup',
+          'data',
+          'datalist',
+          'del',
+          'details',
+          'dfn',
+          'div',
+          'dl',
+          'dt',
+          'dd',
+          'em',
+          'fieldset',
+          'figcaption',
+          'figure',
+          'footer',
+          'form',
+          'h1',
+          'h2',
+          'h3',
+          'h4',
+          'h5',
+          'h6',
+          'head',
+          'header',
+          'i',
+          'iframe',
+          'ins',
+          'kbd',
+          'label',
+          'legend',
+          'li',
+          'link',
+          'main',
+          'map',
+          'mark',
+          'math',
+          'menu',
+          'meter',
+          'nav',
+          'noscript',
+          'object',
+          'ol',
+          'optgroup',
+          'option',
+          'output',
+          'p',
+          'pre',
+          'progress',
+          'q',
+          'rp',
+          'rt',
+          'ruby',
+          's',
+          'samp',
+          'script',
+          'section',
+          'select',
+          'small',
+          'span',
+          'strong',
+          'style',
+          'sub',
+          'summary',
+          'sup',
+          'svg',
+          'table',
+          'tbody',
+          'td',
+          'template',
+          'textarea',
+          'tfoot',
+          'th',
+          'thead',
+          'time',
+          'title',
+          'tr',
+          'u',
+          'ul',
+          'video',
+        ].freeze
+
+        # HTML5 empty tags
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @see Hanami::Helpers::HtmlHelper::EmptyHtmlNode
+        # @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element
+        EMPTY_TAGS = [
+          'area',
+          'base',
+          'br',
+          'col',
+          'embed',
+          'hr',
+          'img',
+          'input',
+          'keygen',
+          'link',
+          'menuitem',
+          'meta',
+          'param',
+          'source',
+          'track',
+          'wbr',
+        ].freeze
+
+        # New line separator
+        #
+        # @since 0.1.0
+        # @api private
+        NEWLINE = "\n".freeze
+
+        CONTENT_TAGS.each do |tag|
+          class_eval %{
+            def #{ tag }(content = nil, attributes = nil, &blk)
+              @nodes << self.class.html_node.new(:#{ tag }, blk || content, attributes || content, options)
+              self
+            end
+          }
+        end
+
+        EMPTY_TAGS.each do |tag|
+          class_eval %{
+            def #{ tag }(attributes = nil)
+              @nodes << EmptyHtmlNode.new(:#{ tag }, attributes)
+              self
+            end
+          }
+        end
+
+        include Utils::ClassAttribute
+
+        class_attribute :html_node
+        self.html_node = ::Hanami::Helpers::HtmlHelper::HtmlNode
+
+        # Initialize a new builder
+        #
+        # @return [Hanami::Helpers::HtmlHelper::HtmlBuilder] the builder
+        #
+        # @since 0.1.0
+        # @api private
+        def initialize
+          @nodes = []
+        end
+
+        def options
+        end
+
+        # Define a custom tag
+        #
+        # @param name [Symbol,String] the name of the tag
+        # @param content [String,Hanami::Helpers::HtmlHelper::HtmlBuilder,NilClass] the optional content
+        # @param attributes [Hash,NilClass] the optional tag attributes
+        # @param blk [Proc] the optional nested content espressed as a block
+        #
+        # @return [self]
+        #
+        # @since 0.1.0
+        # @api public
+        #
+        # @see Hanami::Helpers::HtmlHelper
+        #
+        # @example
+        #   html.tag(:custom) # => <custom></custom>
+        #
+        #   html.tag(:custom, 'foo') # => <custom>foo</custom>
+        #
+        #   html.tag(:custom, html.p('hello')) # => <custom><p>hello</p></custom>
+        #
+        #   html.tag(:custom) { 'foo' }
+        #   # =>
+        #   #<custom>
+        #   #  foo
+        #   #</custom>
+        #
+        #   html.tag(:custom) do
+        #     p 'hello'
+        #   end
+        #   # =>
+        #   #<custom>
+        #   #  <p>hello</p>
+        #   #</custom>
+        #
+        #   html.tag(:custom, 'hello', id: 'foo', 'data-xyz': 'bar') # => <custom id="foo" data-xyz="bar">hello</custom>
+        #
+        #   html.tag(:custom, id: 'foo') { 'hello' }
+        #   # =>
+        #   #<custom id="foo">
+        #   #  hello
+        #   #</custom>
+        def tag(name, content = nil, attributes = nil, &blk)
+          @nodes << HtmlNode.new(name, blk || content, attributes || content, options)
+          self
+        end
+
+        # Define a HTML fragment
+        #
+        # @param blk [Proc] the optional nested content espressed as a block
+        #
+        # @return [self]
+        #
+        # @since 0.2.6
+        # @api public
+        #
+        # @see Hanami::Helpers::HtmlHelper
+        #
+        # @example
+        #   html.fragment('Hanami') # => Hanami
+        #
+        #   html do
+        #     p 'hello'
+        #     p 'hanami'
+        #   end
+        #   # =>
+        #     <p>hello</p>
+        #     <p>hanami</p>
+        def fragment(&blk)
+          @nodes << HtmlFragment.new(&blk)
+          self
+        end
+
+        # Defines a custom empty tag
+        #
+        # @param name [Symbol,String] the name of the tag
+        # @param attributes [Hash,NilClass] the optional tag attributes
+        #
+        # @return [self]
+        #
+        # @since 0.1.0
+        # @api public
+        #
+        # @see Hanami::Helpers::HtmlHelper
+        #
+        # @example
+        #   html.empty_tag(:xr) # => <xr>
+        #
+        #   html.empty_tag(:xr, id: 'foo') # => <xr id="foo">
+        #
+        #   html.empty_tag(:xr, id: 'foo', 'data-xyz': 'bar') # => <xr id="foo" data-xyz="bar">
+        def empty_tag(name, attributes = nil)
+          @nodes << EmptyHtmlNode.new(name, attributes)
+          self
+        end
+
+        # Defines a plain string of text. This particularly useful when you
+        # want to build more complex HTML.
+        #
+        # @param content [String] the text to be rendered.
+        #
+        # @return [self]
+        #
+        # @see Hanami::Helpers::HtmlHelper
+        # @see Hanami::Helpers::HtmlHelper::TextNode
+        #
+        # @example
+        #
+        #   html.label do
+        #     text "Option 1"
+        #     radio_button :option, 1
+        #   end
+        #
+        #   # <label>
+        #   #   Option 1
+        #   #   <input type="radio" name="option" value="1" />
+        #   # </label>
+        def text(content)
+          @nodes << TextNode.new(content)
+          self
+        end
+
+        # @since 0.2.5
+        # @api private
+        alias_method :+, :text
+
+        # Resolves all the nodes and generates the markup
+        #
+        # @return [Hanami::Utils::Escape::SafeString] the output
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @see http://www.rubydoc.info/gems/hanami-utils/Hanami/Utils/Escape/SafeString
+        def to_s
+          Utils::Escape::SafeString.new(@nodes.map(&:to_s).join(NEWLINE))
+        end
+
+        # Encode the content with the given character encoding
+        #
+        # @param encoding [Encoding,String] the encoding or its string representation
+        #
+        # @return [String] the encoded string
+        #
+        # @since 0.2.5
+        # @api private
+        def encode(encoding)
+          to_s.encode(encoding)
+        end
+
+        # Check if there are nested nodes
+        #
+        # @return [TrueClass,FalseClass] the result of the check
+        #
+        # @since 0.1.0
+        # @api private
+        def nested?
+          @nodes.any?
+        end
+
+        # Resolve the context for nested contents
+        #
+        # @since 0.1.0
+        # @api private
+        if RUBY_VERSION >= '2.2' && !Utils.jruby?
+          def resolve(&blk)
+            @context = blk.binding.receiver
+            instance_exec(&blk)
+          end
+        else
+          def resolve(&blk)
+            @context = eval 'self', blk.binding
+            instance_exec(&blk)
+          end
+        end
+
+        # Forward missing methods to the current context.
+        # This allows to access views local variables from nested content blocks.
+        #
+        # @since 0.1.0
+        # @api private
+        def method_missing(m, *args, &blk)
+          @context.__send__(m, *args, &blk)
+        end
+      end
+    end
+  end
+end