lotus-helpers 0.2.0 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c48523257c329e031af02471ad83b63a56290bca
-  data.tar.gz: ec1dba8d370b280d0fb14992b2955c916e9c96da
+  metadata.gz: 30f2cf703b4746c9bd13c43eb4f7e8d080251dd2
+  data.tar.gz: 78149500f0aefbcd5748f5184d5927cbc3e524e1
 SHA512:
-  metadata.gz: ee14aad1c7167c3dd942f22b59a15776c3ed6381d8eef769322b4f377716e62fe07fbe0b2666f7d1e2ce0ab0ad637560e6dbcc5649dd3515cdad60b80d2dacd0
-  data.tar.gz: 9bf9dcaf0da1206f54d11188dc36d0ebc876d76d80c9c1a1498f177560096c66d79c1725255ee1311a349bc183390a4f209270c303be554c97743edca81b738a
+  metadata.gz: 903e02d8560775ebae4c3801cd263d7477766065bf31936e845c245c4a1d526093b2375e7900e5244522b2e9aaafc7c4f84c47cb9f8c1c4fa38b15bb2019a5dc
+  data.tar.gz: 3e840682aef29d505b238de7085cb6703ae31dff639c8b31b04064f4498a5d87f553fe09ae302cd2419d45bfaa8fffa15d7016425f3c24291e3f83b5e9310c34

data/README.md

@@ -22,7 +22,7 @@ View helpers for Ruby applications
 
 ## Rubies
 
-__Lotus::Helpers__ supports Ruby (MRI) 2+ and JRuby 1.7 (with 2.0 mode).
+__Lotus::Helpers__ supports Ruby (MRI) 2+
 
 ## Installation
 

data/lib/lotus-helpers.rb

@@ -0,0 +1 @@
+require 'lotus/helpers'

data/lib/lotus/helpers/form_helper.rb

@@ -38,13 +38,14 @@ module Lotus
     #   * <tt>fields_for</tt>
     #   * <tt>form_for</tt>
     #   * <tt>label</tt>
+    #   * <tt>text_area</tt>
     #   * <tt>text_field</tt>
     #   * <tt>password_field</tt>
     #   * <tt>radio_button</tt>
     #   * <tt>select</tt>
     #   * <tt>submit</tt>
     #
-    # @since x.x.x
+    # @since 0.2.0
     #
     # @see Lotus::Helpers::FormHelper#form_for
     # @see Lotus::Helpers::HtmlHelper
@@ -77,13 +78,13 @@ module Lotus
     module FormHelper
       # Default HTTP method for form
       #
-      # @since x.x.x
+      # @since 0.2.0
       # @api private
       DEFAULT_METHOD = 'POST'.freeze
 
       # Default charset
       #
-      # @since x.x.x
+      # @since 0.2.0
       # @api private
       DEFAULT_CHARSET = 'utf-8'.freeze
 
@@ -91,29 +92,29 @@ module Lotus
       #
       # This key is shared with <tt>lotusrb</tt>, <tt>lotus-controller</tt>.
       #
-      # @since x.x.x
+      # @since 0.2.0
       # @api private
       CSRF_TOKEN = :_csrf_token
 
       # Form object
       #
-      # @since x.x.x
+      # @since 0.2.0
       class Form
         # @return [Symbol] the form name
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         attr_reader :name
 
         # @return [String] the form action
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         attr_reader :url
 
         # @return [::Hash] the form values
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         attr_reader :values
 
@@ -142,7 +143,7 @@ module Lotus
         # @param attributes [Hash,NilClass] a Hash of attributes to pass to the
         #   <tt>form</tt> tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Pass A Value
         #   # Given the following view
@@ -206,7 +207,7 @@ module Lotus
         #
         # @return [String] the method for the action
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::FormHelper::DEFAULT_METHOD
@@ -234,7 +235,7 @@ module Lotus
       #
       # @return [Lotus::Helpers::FormHelper::FormBuilder] the form builder
       #
-      # @since x.x.x
+      # @since 0.2.0
       #
       # @see Lotus::Helpers::FormHelper
       # @see Lotus::Helpers::FormHelper::Form
@@ -410,7 +411,7 @@ module Lotus
       #
       # @return [String,NilClass] token, if present
       #
-      # @since x.x.x
+      # @since 0.2.0
       def csrf_token
         if defined?(session)
           session[CSRF_TOKEN]

data/lib/lotus/helpers/form_helper/form_builder.rb

@@ -8,19 +8,19 @@ module Lotus
     module FormHelper
       # Form builder
       #
-      # @since x.x.x
+      # @since 0.2.0
       #
       # @see Lotus::Helpers::HtmlHelper::HtmlBuilder
       class FormBuilder < ::Lotus::Helpers::HtmlHelper::HtmlBuilder
         # Set of HTTP methods that are understood by web browsers
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         BROWSER_METHODS = ['GET', 'POST'].freeze
 
         # Checked attribute value
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::FormHelper::FormBuilder#radio_button
@@ -28,7 +28,7 @@ module Lotus
 
         # Selected attribute value for option
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::FormHelper::FormBuilder#select
@@ -36,7 +36,7 @@ module Lotus
 
         # Separator for accept attribute of file input
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::FormHelper::FormBuilder#file_input
@@ -44,7 +44,7 @@ module Lotus
 
         # Replacement for input id interpolation
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::FormHelper::FormBuilder#_input_id
@@ -52,7 +52,7 @@ module Lotus
 
         # Replacement for input value interpolation
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::FormHelper::FormBuilder#_value
@@ -60,7 +60,7 @@ module Lotus
 
         # Default value for unchecked check box
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::FormHelper::FormBuilder#check_box
@@ -68,7 +68,7 @@ module Lotus
 
         # Default value for checked check box
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::FormHelper::FormBuilder#check_box
@@ -96,7 +96,7 @@ module Lotus
         #
         # @return [Lotus::Helpers::FormHelper::FormBuilder] the form builder
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         def initialize(form, attributes, context = nil, &blk)
           super()
@@ -122,7 +122,7 @@ module Lotus
         #
         # @return [Lotus::Utils::Escape::SafeString] the output
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::HtmlHelper::HtmlBuilder#to_s
@@ -144,7 +144,7 @@ module Lotus
         # @param name [Symbol] the nested name, it's used to generate input
         #   names, ids, and to lookup params to fill values.
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -211,7 +211,7 @@ module Lotus
         # @param content [Symbol,String] the field name or a content string
         # @param attributes [Hash] HTML attributes to pass to the label tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -220,7 +220,7 @@ module Lotus
         #   %>
         #
         #  # Output:
-        #  #  <label for="book-extended-title">Extended Title</label>
+        #  #  <label for="book-extended-title">Extended title</label>
         #
         # @example Custom content
         #   <%=
@@ -231,6 +231,15 @@ module Lotus
         #  # Output:
         #  #  <label for="book-extended-title">Title</label>
         #
+        # @example Custom "for" attribute
+        #   <%=
+        #     # ...
+        #     label :extended_title, for: 'ext-title'
+        #   %>
+        #
+        #  # Output:
+        #  #  <label for="ext-title">Extended title</label>
+        #
         # @example Nested fields usage
         #   <%=
         #     # ...
@@ -245,7 +254,12 @@ module Lotus
         #  #  <input type="text" name="delivery[address][city] id="delivery-address-city" value="">
         def label(content, attributes = {})
           attributes = { for: _for(content, attributes.delete(:for)) }.merge(attributes)
-          content    = Utils::String.new(content).titleize
+          content    = case content
+                       when String, Lotus::Utils::String
+                         content
+                       else
+                         Utils::String.new(content).capitalize
+                       end
 
           super(content, attributes)
         end
@@ -273,7 +287,7 @@ module Lotus
         # @option attributes [String] :checked_value (defaults to "1")
         # @option attributes [String] :unchecked_value (defaults to "0")
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -349,7 +363,7 @@ module Lotus
         # @param name [Symbol] the input name
         # @param attributes [Hash] HTML attributes to pass to the input tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -368,7 +382,7 @@ module Lotus
         # @param name [Symbol] the input name
         # @param attributes [Hash] HTML attributes to pass to the input tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -387,7 +401,7 @@ module Lotus
         # @param name [Symbol] the input name
         # @param attributes [Hash] HTML attributes to pass to the input tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -406,7 +420,7 @@ module Lotus
         # @param name [Symbol] the input name
         # @param attributes [Hash] HTML attributes to pass to the input tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -425,7 +439,7 @@ module Lotus
         # @param name [Symbol] the input name
         # @param attributes [Hash] HTML attributes to pass to the input tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -444,7 +458,7 @@ module Lotus
         # @param name [Symbol] the input name
         # @param attributes [Hash] HTML attributes to pass to the input tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -466,7 +480,7 @@ module Lotus
         # @param attributes [Hash] HTML attributes to pass to the input tag
         # @option attributes [String,Array] :accept Optional set of accepted MIME Types
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -501,12 +515,103 @@ module Lotus
           input(attributes)
         end
 
+        # Number input
+        #
+        # @param name [Symbol] the input name
+        # @param attributes [Hash] HTML attributes to pass to the number input
+        #
+        # @example Basic usage
+        #   <%=
+        #     # ...
+        #     number_field :percent_read
+        #   %>
+        #
+        #   # Output:
+        #   #  <input type="number" name="book[percent_read]" id="book-percent-read" value="">
+        #
+        # You can also make use of the 'max', 'min', and 'step' attributes for
+        # the HTML5 number field.
+        #
+        # @example Advanced attributes
+        #   <%=
+        #     # ...
+        #     number_field :priority, min: 1, max: 10, step: 1
+        #   %>
+        #
+        #   # Output:
+        #   #  <input type="number" name="book[percent_read]" id="book-precent-read" value="" min="1" max="10" step="1">
+        def number_field(name, attributes = {})
+          input _attributes(:number, name, attributes)
+        end
+
+        # Text-area input
+        #
+        # @param name [Symbol] the input name
+        # @param content [String] the content of the textarea
+        # @param attributes [Hash] HTML attributes to pass to the textarea tag
+        #
+        # @since 0.2.5
+        #
+        # @example Basic usage
+        #   <%=
+        #     # ...
+        #     text_area :hobby
+        #   %>
+        #
+        #   # Output:
+        #   #  <textarea name="user[hobby]" id="user-hobby"></textarea>
+        #
+        # @example Set content
+        #   <%=
+        #     # ...
+        #     text_area :hobby, 'Football'
+        #   %>
+        #
+        #   # Output:
+        #   #  <textarea name="user[hobby]" id="user-hobby">Football</textarea>
+        #
+        # @example Set content and HTML attributes
+        #   <%=
+        #     # ...
+        #     text_area :hobby, 'Football', class: 'form-control'
+        #   %>
+        #
+        #   # Output:
+        #   #  <textarea name="user[hobby]" id="user-hobby" class="form-control">Football</textarea>
+        #
+        # @example Omit content and specify HTML attributes
+        #   <%=
+        #     # ...
+        #     text_area :hobby, class: 'form-control'
+        #   %>
+        #
+        #   # Output:
+        #   #  <textarea name="user[hobby]" id="user-hobby" class="form-control"></textarea>
+        #
+        # @example Force blank value
+        #   <%=
+        #     # ...
+        #     text_area :hobby, '', class: 'form-control'
+        #   %>
+        #
+        #   # Output:
+        #   #  <textarea name="user[hobby]" id="user-hobby" class="form-control"></textarea>
+        def text_area(name, content = nil, attributes = {})
+          if content.respond_to?(:to_hash)
+            attributes = content
+            content    = nil
+          end
+
+          attributes = {name: _input_name(name), id: _input_id(name)}.merge(attributes)
+          textarea(content || _value(name), attributes)
+        end
+
         # Text input
         #
         # @param name [Symbol] the input name
         # @param attributes [Hash] HTML attributes to pass to the input tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -531,7 +636,7 @@ module Lotus
         # @param value [String] the input value
         # @param attributes [Hash] HTML attributes to pass to the input tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -571,7 +676,7 @@ module Lotus
         # @param name [Symbol] the input name
         # @param attributes [Hash] HTML attributes to pass to the input tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -596,7 +701,7 @@ module Lotus
         # it automatically sets the <tt>selected</tt> attribute on the <tt><option></tt> tag.
         # This Lotus::Controller integration happens without any developer intervention.
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -649,7 +754,7 @@ module Lotus
         # @param content [String] The content
         # @param attributes [Hash] HTML attributes to pass to the button tag
         #
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @example Basic usage
         #   <%=
@@ -668,7 +773,7 @@ module Lotus
         # A set of options to pass to the sub form helpers.
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         def options
           Hash[name: @name, values: @values, verb: @verb, csrf_token: @csrf_token]
         end
@@ -677,7 +782,7 @@ module Lotus
         # Check the current builder is top-level
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         def toplevel?
           @attributes.any?
         end
@@ -685,7 +790,7 @@ module Lotus
         # Prepare for method override
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         def _method_override!
           verb = (@attributes.fetch(:method) { DEFAULT_METHOD }).to_s.upcase
 
@@ -700,7 +805,7 @@ module Lotus
         # Return CSRF Protection token from view context
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         def csrf_token
           @context.csrf_token if @context.respond_to?(:csrf_token)
         end
@@ -708,7 +813,7 @@ module Lotus
         # Return a set of default HTML attributes
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         def _attributes(type, name, attributes)
           { type: type, name: _input_name(name), id: _input_id(name), value: _value(name) }.merge(attributes)
         end
@@ -716,7 +821,7 @@ module Lotus
         # Input <tt>name</tt> HTML attribute
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         def _input_name(name)
           "#{ @name }[#{ name }]"
         end
@@ -724,7 +829,7 @@ module Lotus
         # Input <tt>id</tt> HTML attribute
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         def _input_id(name)
           name = _input_name(name).gsub(/\[(?<token>[[[:word:]]\-]*)\]/, INPUT_ID_REPLACEMENT)
           Utils::String.new(name).dasherize
@@ -733,7 +838,7 @@ module Lotus
         # Input <tt>value</tt> HTML attribute
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         def _value(name)
           name = _input_name(name).gsub(/\[(?<token>[[:word:]]*)\]/, INPUT_VALUE_REPLACEMENT)
           @values.get(name)
@@ -742,15 +847,20 @@ module Lotus
         # Input <tt>for</tt> HTML attribute
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         def _for(content, name)
-          _input_id(name || content)
+          case name
+          when String, Lotus::Utils::String
+            name
+          else
+            _input_id(name || content)
+          end
         end
 
         # Hidden field for check box
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @see Lotus::Helpers::FormHelper::FormBuilder#check_box
         def _hidden_field_for_check_box(name, attributes)
@@ -766,7 +876,7 @@ module Lotus
         # HTML attributes for check box
         #
         # @api private
-        # @since x.x.x
+        # @since 0.2.0
         #
         # @see Lotus::Helpers::FormHelper::FormBuilder#check_box
         def _attributes_for_check_box(name, attributes)
@@ -787,4 +897,3 @@ module Lotus
     end
   end
 end
-

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

@@ -5,7 +5,7 @@ module Lotus
     module FormHelper
       # HTML form node
       #
-      # @since x.x.x
+      # @since 0.2.0
       # @api private
       #
       # @see Lotus::Helpers::HtmlHelper::HtmlNode
@@ -19,7 +19,7 @@ module Lotus
         #
         # @return [Lotus::Helpers::FormHelper::HtmlNode]
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         def initialize(name, content, attributes, options)
           super
@@ -38,7 +38,7 @@ module Lotus
         #
         # @return [String] the content
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::HtmlHelper::HtmlNode#content
@@ -50,7 +50,7 @@ module Lotus
 
         # Inject a hidden field to make Method Override possible
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         def _method_override!
           return if @verb.nil?
@@ -63,7 +63,7 @@ module Lotus
 
         # Inject a hidden field for CSRF Protection token
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         def _csrf_protection!
           return if @csrf_token.nil?

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

@@ -6,6 +6,22 @@ module Lotus
       # @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
@@ -45,13 +61,30 @@ module Lotus
         # @api private
         def attributes
           return if @attributes.nil?
-          result = [nil]
+          result = ''
 
-          @attributes.each do |name, value|
-            result << %(#{ name }="#{ value }")
+          @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.join(ATTRIBUTES_SEPARATOR)
+          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

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

@@ -3,6 +3,7 @@ require 'lotus/utils/class_attribute'
 require 'lotus/utils/escape'
 require 'lotus/helpers/html_helper/empty_html_node'
 require 'lotus/helpers/html_helper/html_node'
+require 'lotus/helpers/html_helper/text_node'
 
 module Lotus
   module Helpers
@@ -253,6 +254,36 @@ module Lotus
           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 Lotus::Helpers::HtmlHelper
+        # @see Lotus::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 [Lotus::Utils::Escape::SafeString] the output

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

@@ -0,0 +1,33 @@
+module Lotus
+  module Helpers
+    module HtmlHelper
+      # Text node. Allows for text to be inserted between HTML tags.
+      #
+      # @since 0.2.5
+      # @api private
+      class TextNode
+        # Initialize a new text node
+        #
+        # @param content [String,#to_s] The content to be added.
+        #
+        # @return [Lotus::Helpers::HtmlHelper::TextNode]
+        #
+        # @since 0.2.5
+        # @api private
+        def initialize(content)
+          @content = content.to_s
+        end
+
+        # Resolve and return the output
+        #
+        # @return [String] the output
+        #
+        # @since 0.2.5
+        # @api private
+        def to_s
+          Utils::Escape.html(@content)
+        end
+      end
+    end
+  end
+end

data/lib/lotus/helpers/link_to_helper.rb

@@ -4,23 +4,130 @@ module Lotus
   module Helpers
     # LinkTo Helper
     #
-    # Including <tt>Lotus::Helpers::LinkTo</tt> will include the `link_to` method.
+    # Including <tt>Lotus::Helpers::LinkTo</tt> will include the
+    # <tt>link_to</tt> public method.
     #
-    # @since x.x.x
+    # This helper can be used both in views and templates.
     #
-    # @see Lotus::Helpers::HtmlHelper#html
-    #
-    # @example Usage
-    #   # 1
-    #   link_to('home', '/') # => <a href="/">home</a>
-    #
-    #   # 2
-    #   link_to('users', :users_path, class: 'my_users') # => <a href="/users" class="my_users">users</div>
+    # @since 0.2.0
     module LinkToHelper
       include Lotus::Helpers::HtmlHelper
 
-      def link_to(content, url, options = {}, &blk)
-        options[:href] = url
+      # Generates an anchor tag for the given arguments.
+      #
+      # Contents are automatically escaped.
+      #
+      # @overload link_to(content, url, options)
+      #   Use string as content
+      #   @param content [String] content used in the a tag
+      #   @param url [String] url used in href attribute
+      #   @param options [Hash] HTML attributes to pass to the a tag
+      #
+      # @overload link_to(url, options, &blk)
+      #   Use block as content
+      #   @param url [String] url used in href attribute
+      #   @param options [Hash] HTML attributes to pass to the a tag
+      #   @param blk [Proc] A block that describes the contents of the a tag
+      #
+      # @return [String] HTML markup for the link
+      #
+      # @raise [ArgumentError] if the signature isn't respected
+      #
+      # @since 0.2.0
+      #
+      # @see Lotus::Helpers::HtmlHelper#html
+      #
+      # @example Both content and URL are strings
+      #   <%= link_to('Home', '/') %>
+      #     # => <a href="/">Home</a>
+      #
+      # @example Content string with route helper
+      #   <%= link_to('Home', routes.path(:home)) %>
+      #     # => <a href="/">Home</a>
+      #
+      # @example HTML attributes
+      #   <%= link_to('Home', routes.path(:home), class: 'button') %>
+      #     # => <a href="/" class="button">Home</a>
+      #
+      # @example Automatic content escape (XSS protection)
+      #   <%= link_to(%(<script>alert('xss')</script>), '/') %>
+      #     # => <a href="/">&lt;script&gt;alert(&apos;xss&apos;)&lt;&#x2F;script&gt;</a>
+      #
+      # @example Automatic content block escape (XSS protection)
+      #   <%=
+      #     link_to('/') do
+      #       %(<script>alert('xss')</script>)
+      #     end
+      #   %>
+      #     # => <a href="/">\n&lt;script&gt;alert(&apos;xss&apos;)&lt;&#x2F;script&gt;\n</a>
+      #
+      # @example Content as block with string URL
+      #   <%=
+      #     link_to('/') do
+      #       'Home'
+      #     end
+      #   %>
+      #     # => <a href="/">Home</a>
+      #
+      # @example Content as block
+      #   <%=
+      #     link_to(routes.path(:home)) do
+      #       'Home'
+      #     end
+      #   %>
+      #     # => <a href="/">Home</a>
+      #
+      # @example Content as block with HTML attributes
+      #   <%=
+      #     link_to(routes.path(:home), id: 'home-link') do
+      #       'Home'
+      #     end
+      #   %>
+      #     # => <a href="/" id: 'home-link'>Home</a>
+      #
+      # @example Content as HTML builder block
+      #   <%=
+      #     link_to(routes.path(:home)) do
+      #       strong 'Home'
+      #     end
+      #   %>
+      #     # => <a href="/"><strong>Home</strong></a>
+      #
+      # @example Provides both content as first argument and block
+      #   <%=
+      #     link_to('Home', routes.path(:home)) do
+      #       strong 'Home'
+      #     end
+      #   %>
+      #     # => ArgumentError
+      #
+      # @example Without any argument
+      #   <%= link_to %>
+      #     # => ArgumentError
+      #
+      # @example Without any argument and empty block
+      #   <%=
+      #     link_to do
+      #     end
+      #   %>
+      #     # => ArgumentError
+      #
+      # @example With only content
+      #   <%= link_to 'Home' %>
+      #     # => ArgumentError
+      def link_to(content, url = nil, options = {}, &blk)
+        if block_given?
+          options = url || {}
+          url     = content
+          content = nil
+        end
+
+        begin
+          options[:href] = url or raise ArgumentError
+        rescue TypeError
+          raise ArgumentError
+        end
+
         html.a(blk || content, options).to_s
       end
     end

data/lib/lotus/helpers/number_formatting_helper.rb

@@ -8,7 +8,7 @@ module Lotus
     # By including <tt>Lotus::Helpers::NumberFormattingHelper</tt> it will
     # inject private method: <tt>format_number</tt>.
     #
-    # @since x.x.x
+    # @since 0.2.0
     module NumberFormattingHelper
       private
       # Format the given number, according to the options
@@ -29,10 +29,10 @@ module Lotus
       #
       # @raise [TypeError] if number can't be formatted
       #
-      # @since x.x.x
+      # @since 0.2.0
       #
       # @example
-      #   require 'lotus/helpers/number_formatter_helper'
+      #   require 'lotus/helpers/number_formatting_helper'
       #
       #   class Checkout
       #     include Lotus::Helpers::NumberFormattingHelper
@@ -66,14 +66,14 @@ module Lotus
 
       # Formatter
       #
-      # @since x.x.x
+      # @since 0.2.0
       # @api private
       class Formatter
         # Regex to delimitate integer part of a number
         #
         # @return [Regexp] the delimitation regex
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::NumberFormatter::Formatter#delimitate
@@ -83,7 +83,7 @@ module Lotus
         #
         # @return [Regexp] the guessing regex
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::NumberFormatter::Formatter#to_number
@@ -93,7 +93,7 @@ module Lotus
         #
         # @return [String] default separator
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         DEFAULT_SEPARATOR  = '.'.freeze
 
@@ -101,7 +101,7 @@ module Lotus
         #
         # @return [String] default delimiter
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         DEFAULT_DELIMITER  = ','.freeze
 
@@ -109,7 +109,7 @@ module Lotus
         #
         # @return [String] default precision
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         DEFAULT_PRECISION  = 2
 
@@ -121,7 +121,7 @@ module Lotus
         # @option options [String] :separator fractional part delimiter
         # @option options [Integer] :precision rounding precision
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         #
         # @see Lotus::Helpers::NumberFormatter::Formatter::DEFAULT_DELIMITER
@@ -140,7 +140,7 @@ module Lotus
         #
         # @raise [TypeError] if number can't be formatted
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         def format
           parts.join(@separator)
@@ -152,7 +152,7 @@ module Lotus
         #
         # @return [Array] parts
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         def parts
           integer_part, fractional_part = to_str.split(DEFAULT_SEPARATOR)
@@ -163,7 +163,7 @@ module Lotus
         #
         # @return [String] delimitated string
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         def delimitate(part)
           part.gsub(DELIMITATION_REGEX) { |digit| "#{digit}#{@delimiter}" }
@@ -175,7 +175,7 @@ module Lotus
         #
         # @raise [TypeError] if number can't be formatted
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         def to_str
           to_number.to_s
@@ -187,7 +187,7 @@ module Lotus
         #
         # @raise [TypeError] if number can't be formatted
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         def to_number
           case @number
@@ -205,7 +205,7 @@ module Lotus
         #
         # @return [Float,Complex,Rational,BigDecimal] rounded number, if applicable
         #
-        # @since x.x.x
+        # @since 0.2.0
         # @api private
         def rounded_number
           if @number.respond_to?(:round)

data/lib/lotus/helpers/version.rb

@@ -3,6 +3,6 @@ module Lotus
     # Define version
     #
     # @since 0.1.0
-    VERSION = '0.2.0'.freeze
+    VERSION = '0.2.5'.freeze
   end
 end

data/lotus-helpers.gemspec

@@ -6,8 +6,8 @@ require 'lotus/helpers/version'
 Gem::Specification.new do |spec|
   spec.name          = 'lotus-helpers'
   spec.version       = Lotus::Helpers::VERSION
-  spec.authors       = ['Luca Guidi', 'Trung Lê']
-  spec.email         = ['me@lucaguidi.com', 'trung.le@ruby-journal.com']
+  spec.authors       = ['Luca Guidi', 'Trung Lê', 'Alfonso Uceda']
+  spec.email         = ['me@lucaguidi.com', 'trung.le@ruby-journal.com', 'uceda73@gmail.com']
   spec.summary       = %q{Lotus helpers}
   spec.description   = %q{View helpers for Ruby applications}
   spec.homepage      = 'http://lotusrb.org'
@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.0.0'
 
-  spec.add_dependency 'lotus-utils', '~> 0.5'
+  spec.add_dependency 'lotus-utils', '~> 0.5', '>= 0.5.2'
 
   spec.add_development_dependency 'bundler',  '~> 1.6'
   spec.add_development_dependency 'rake',     '~> 10.0'

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: lotus-helpers
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.5
 platform: ruby
 authors:
 - Luca Guidi
 - Trung Lê
+- Alfonso Uceda
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-23 00:00:00.000000000 Z
+date: 2015-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lotus-utils
@@ -18,6 +19,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -25,6 +29,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.2
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -71,12 +78,14 @@ description: View helpers for Ruby applications
 email:
 - me@lucaguidi.com
 - trung.le@ruby-journal.com
+- uceda73@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.md
 - README.md
+- lib/lotus-helpers.rb
 - lib/lotus/helpers.rb
 - lib/lotus/helpers/escape_helper.rb
 - lib/lotus/helpers/form_helper.rb
@@ -87,6 +96,7 @@ files:
 - lib/lotus/helpers/html_helper/empty_html_node.rb
 - lib/lotus/helpers/html_helper/html_builder.rb
 - lib/lotus/helpers/html_helper/html_node.rb
+- lib/lotus/helpers/html_helper/text_node.rb
 - lib/lotus/helpers/link_to_helper.rb
 - lib/lotus/helpers/number_formatting_helper.rb
 - lib/lotus/helpers/routing_helper.rb
@@ -112,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Lotus helpers