lotus-helpers 0.0.0 → 0.1.0

data/lib/lotus/helpers/html_helper.rb

@@ -0,0 +1,192 @@
+require 'lotus/helpers/html_helper/html_builder'
+
+module Lotus
+  module Helpers
+    # HTML builder
+    #
+    # By including <tt>Lotus::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 Lotus::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>
+    #
+    #
+    #
+    # @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">
+    #   #  <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 'lotus/helpers'
+    #
+    #   class MyView
+    #     include Lotus::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 'lotus/view'
+    #   require 'lotus/helpers'
+    #
+    #   Book = Struct.new(:title)
+    #
+    #   module Books
+    #     class Show
+    #       include Lotus::View
+    #       include Lotus::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
+      #
+      # @return [Lotus::Helpers::HtmlHelper::HtmlBuilder] the HTML builder
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Helpers::HtmlHelper
+      # @see Lotus::Helpers::HtmlHelper::HtmlBuilder
+      def html
+        HtmlBuilder.new
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module Lotus
+  module Helpers
+    module HtmlHelper
+      # Empty HTML node
+      #
+      # @since 0.1.0
+      # @api private
+      class EmptyHtmlNode
+        # 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 [Lotus::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 = [nil]
+
+          @attributes.each do |name, value|
+            result << %(#{ name }="#{ value }")
+          end
+
+          result.join(ATTRIBUTES_SEPARATOR)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,296 @@
+require 'lotus/utils' # RUBY_VERSION >= '2.2'
+require 'lotus/utils/escape'
+require 'lotus/helpers/html_helper/empty_html_node'
+require 'lotus/helpers/html_helper/html_node'
+
+module Lotus
+  module Helpers
+    module HtmlHelper
+      # HTML Builder
+      #
+      # @since 0.1.0
+      class HtmlBuilder
+        # HTML5 content tags
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @see Lotus::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',
+          '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 Lotus::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 << HtmlNode.new(:#{ tag }, blk || content, attributes || content)
+              self
+            end
+          }
+        end
+
+        EMPTY_TAGS.each do |tag|
+          class_eval %{
+            def #{ tag }(attributes = nil)
+              @nodes << EmptyHtmlNode.new(:#{ tag }, attributes)
+              self
+            end
+          }
+        end
+
+        # Initialize a new builder
+        #
+        # @return [Lotus::Helpers::HtmlHelper::HtmlBuilder] the builder
+        #
+        # @since 0.1.0
+        # @api private
+        def initialize
+          @nodes = []
+        end
+
+        # Define a custom tag
+        #
+        # @param name [Symbol,String] the name of the tag
+        # @param content [String,Lotus::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 Lotus::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)
+          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 Lotus::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
+
+        # Resolves all the nodes and generates the markup
+        #
+        # @return [Lotus::Utils::Escape::SafeString] the output
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @see http://www.rubydoc.info/gems/lotus-utils/Lotus/Utils/Escape/SafeString
+        def to_s
+          Utils::Escape::SafeString.new(@nodes.map(&:to_s).join(NEWLINE))
+        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