wrap_it 0.2.0 → 1.0.0

data/lib/wrap_it/link.rb

@@ -1,6 +1,22 @@
 module WrapIt
   #
-  # Link
+  # HTML link element
+  #
+  # You can specify link by `link`, `href` or `url` option or by first String
+  # argument. Also includes {TextContainer} module, so you can specify link
+  # body with `text` or `body` option or by second String argument or inside
+  # block.
+  #
+  # @example usage
+  #   link = WrapIt::Link.new(template, 'http://some.url', 'text')
+  #   link.render # => '<a href="http://some.url">test</a>'
+  #   link = WrapIt::Link.new(template, link: 'http://some.url', text: 'text')
+  #   link.render # => '<a href="http://some.url">test</a>'
+  #   link = WrapIt::Link.new(template, 'text', link: http://some.url')
+  #   link.render # => '<a href="http://some.url">test</a>'
+  #
+  # @example in template
+  #   <%= link 'http://some.url' do %>text<% end %>
   #
   # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
   #
@@ -9,33 +25,40 @@ module WrapIt
 
     default_tag 'a'
 
+    option :link, if: %i(link href url)
+
+    # extract first string argument as link only if it not specified in options
+    argument(:link, first_only: true, after_options: true,
+             if: String, and: ->{ !option_provided?(:link, :href, :url) }
+    ) do |_, v|
+      self.href = v
+    end
+
+    #
+    # Retrieves current link
+    #
+    # @return [String] link
     def href
-      @options[:href]
+      html_attr[:href]
     end
 
+    #
+    # Sets link
+    # @param  value [String] link
+    #
+    # @return [String] setted link
     def href=(value)
       if value.is_a?(Hash)
-        defined?(Rails) || fail(
+        WrapIt.rails? || fail(
           ArgumentError,
           'Hash links supported only in Rails env'
         )
         value = @template.url_for(value)
       end
       value.is_a?(String) || fail(ArgumentError, 'Wrong link type')
-      @options[:href] = value
-    end
-
-    before_initialize do
-      link = @options[:link] || @options[:href] || @options[:url]
-      @options.delete(:link)
-      @options.delete(:href)
-      @options.delete(:url)
-      unless link.is_a?(String) || link.is_a?(Hash)
-        @block.nil? && tmp = @arguments.extract_first!(String)
-        link = @arguments.extract_first!(String)
-        tmp.nil? || @arguments.unshift(tmp)
-      end
-      link.nil? || self.href = link
+      html_attr[:href] = value
     end
+    alias_method :link=, :href=
+    alias_method :url=, :href=
   end
 end

data/lib/wrap_it/sections.rb

@@ -1,12 +1,60 @@
 module WrapIt
   #
-  # Adds sections functionality
+  # Sections is a smart way to make complex components with inheritance.
+  #
+  # Sections is just array of named HTML markup pieces. You can place any
+  # section before or after another at class level and change their content
+  # at instance level.
+  #
+  # Each component have three stages. First is initialization, then sections
+  # capturing and rendering. You can change any sections content until
+  # rendering stage begins. Finally, renderer joins all sections in order,
+  # that they have at render time.
+  #
+  # {WrapIt::Base} provides following sections: main section is `:content`.
+  # All text from block captured there. `:render_arguments` and `:render_block`
+  # also provided, so arguments and block passed to render method captured
+  # here.
+  #
+  # Access to sections at instance level performed throw hash-like getter and
+  # setter ([] and []=) of self.
+  #
+  # With this functionality you can easy organize you inheritance, so any
+  # descendant can change sections order or any section content without
+  # changes to unrelated sections.
+  #
+  # @example sections usage
+  #   class IconedButton < WrapIt::Base
+  #     include TextContainer
+  #     html_class 'btn'
+  #     section :icon
+  #     place :icon, before: :content
+  #
+  #     after_capture do
+  #       self[:icon] = html_safe('<i class="my-icon"></i>')
+  #     end
+  #   end
+  #
+  #   class RightIconedButton < IconedButton
+  #     place :icon, after: :content
+  #   end
+  #
+  #   b1 = IconedButton.new(template, 'text')
+  #   b2 = RightIconedButton.new(template, 'text')
+  #   b1.render # => '<div class="btn"><i class="my-icon"></i>text</div>'
+  #   b2.render # => '<div class="btn">text<i class="my-icon"></i></div>'
   #
   # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
   #
   module Sections
+    # Documentation includes
+    # @!parse extend  Sections::ClassMethods
+
+    # module implementation
+
     extend DerivedAttributes
 
+    #
     def self.included(base)
       base == Base || fail(
         TypeError,
@@ -15,6 +63,11 @@ module WrapIt
       base.extend ClassMethods
     end
 
+    #
+    # Retrieves specified section content
+    # @param  name [Symbol] section name
+    #
+    # @return [String] section content
     def [](name)
       @section_names ||= self.class.sections
       return nil unless @section_names.include?(name)
@@ -22,6 +75,12 @@ module WrapIt
       @sections[name] ||= empty_html
     end
 
+    #
+    # Sets specified section content
+    # @param  name [Symbol] section name
+    # @param  value [String] content
+    #
+    # @return [String] section content
     def []=(name, value)
       @section_names ||= self.class.sections
       return unless @section_names.include?(name)
@@ -30,13 +89,24 @@ module WrapIt
     end
 
     #
-    # Class methods to include
+    # {Sections} class methods
     #
     module ClassMethods
+      #
+      # Retrieves all sections, including ancestors
+      #
+      # @return [Array<Symbol>] array of sections
       def sections
         collect_derived(:@sections)
       end
 
+      #
+      # Defines new section or sections. Places its to end of section list
+      #
+      # @overload section([name, ...])
+      #   @param name [Symbol, String] section name
+      #
+      # @return [void]
       def section(*args)
         @sections ||= []
         args.flatten.each do |name|
@@ -49,6 +119,10 @@ module WrapIt
         end
       end
 
+      #
+      # Retrieves section names in current order
+      #
+      # @return [Array<Symbol>] ordered sections array
       def placement
         @placement ||=
           if self == Base
@@ -59,6 +133,20 @@ module WrapIt
           end
       end
 
+      #
+      # Places specific section in specified place
+      #
+      # @overload place(src, to)
+      #   @param  src [Symbol] section name to place
+      #   @param  to [Hash] single key-value hash. Key can be `:before` or
+      #     `after`, value can be `:begin`, `:end` or section name
+      #
+      # @overload place(src, at, dst)
+      #   @param  src [Symbol] section name to place
+      #   @param  at [Symbol] can be `:before` or `:after`
+      #   @param  dst [Symbol] can be `:begin`, `:end` or section name
+      #
+      # @return [void]
       def place(src, at, dst = nil)
         if dst == nil && at.is_a?(Hash) && at.keys.size == 1
           dst = at.values[0]

data/lib/wrap_it/switches.rb

@@ -5,40 +5,28 @@ module WrapIt
   # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
   #
   module Switches
+    # Documentation includes
+    # @!parse extend  Switches::ClassMethods
+
+    # module implementation
+
     extend DerivedAttributes
 
+    #
     def self.included(base)
       base == Base || fail(
         TypeError,
         "#{self.class.name} can be included only into WrapIt::Base"
       )
       base.extend ClassMethods
-      base.after_initialize :switches_init
-    end
-
-    private
-
-    def switches_init
-      @switches = {}
-      keys = switches.keys
-      @options.keys.select { |o| keys.include?(o) }.each do |switch|
-        send("#{switches[switch][:name]}=", @options.delete(switch) == true)
-      end
-      @arguments.extract!(Symbol, and: [keys]).each do |switch|
-        send("#{switches[switch][:name]}=", true)
-      end
-    end
-
-    def switches
-      @switches_hash ||= self.class.collect_derived(:@switches, {}, :merge)
+      base.before_initialize { @switches = {} }
     end
 
     #
-    # Class methods to include
+    # {Switches} class methods
     #
     module ClassMethods
       #
-      # @dsl
       # Adds `switch`. Switch is a boolean flag. When element created, creation
       # arguments will be scanned for `Symbol`, that equals to `name`. If
       # it founded, switch turned on. Also creation options inspected. If
@@ -57,11 +45,11 @@ module WrapIt
       # on or removed in other case.
       #
       # @param  name [String, Symbol] Switch name. Converted to `Symbol`.
-      # @param  opts [Hash] Switch options
-      # @options opts [true, String, Symbol, Array<String, Symbol>] :html_class
+      # @param  options [Hash] Switch options
+      # @option options [true, String, Symbol, Array<String, Symbol>] :html_class
       #   HTML classes list that will automatically added to element if switch
       #   is on or removed from element if switch id off.
-      # @options opts [Symbol, Array<Symbol>] :aliases list of aliases.
+      # @option options [Symbol, Array<Symbol>] :aliases list of aliases.
       #   Warning! Values are not converted - pass only `Symbols` here.
       # @yield [state] Runs block when switch state changed, gives it to block.
       # @yieldparam state [Boolean] Whether switch is on or off.
@@ -83,11 +71,28 @@ module WrapIt
               end
             end
         end
-        names = [name] + [[options[:aliases]] || []].flatten.compact
+
         define_method("#{name}?") { @switches[name] == true }
         define_method("#{name}=", &Switches.setter(name, &block))
         @switches ||= {}
-        names.each { |n| @switches[n] = options }
+
+        @switches[name] = options
+
+        o_params = {}
+        a_params = { if: Symbol, and: name }
+        if options.key?(:aliases)
+          aliases = [options[:aliases]].flatten.compact
+          o_params[:if] = [name] + aliases
+          a_params[:and] = [name] + aliases
+        end
+
+        option(name, **o_params) do |_, v|
+          send("#{options[:name]}=", v == true)
+        end
+
+        argument(name, **a_params) do |_, _|
+          send("#{options[:name]}=", true)
+        end
       end
     end
 
@@ -96,19 +101,18 @@ module WrapIt
     #
     # Makes switch setter block
     # @param  name [String] switch name
-    # @param  &block [Proc] switch block
     #
     # @return [Proc] switch setter block
     def self.setter(name, &block)
       proc do |value|
-        opts = switches[name]
+        opts = self.class.collect_derived(:@switches, {}, :merge)[name]
         cb_return = block.nil? || instance_exec(value == true, &block)
         unless cb_return == false
           @switches[name] = value == true
           if value == true
-            opts.key?(:html_class) && add_html_class(*opts[:html_class])
+            opts.key?(:html_class) && html_class << opts[:html_class]
           else
-            opts.key?(:html_class) && remove_html_class(*opts[:html_class])
+            opts.key?(:html_class) && html_class.delete(*opts[:html_class])
           end
         end
       end

data/lib/wrap_it/text_container.rb

@@ -1,30 +1,103 @@
 module WrapIt
   #
-  # TextContainer
+  # Provides functionality for text-contained components.
+  #
+  # Text can be captured from `:text` or `:body` option, or as first unparsed
+  # String argument, or in block, provided to constructor.
+  #
+  # If block given, text will be captured from it in priority, so String
+  # arguments and options will not parsed. You can cancel this manner by
+  # calling {ClassMethods#text_in_block text_in_block(false)} method.
+  #
+  # This module adds `body` section before base `content` section.
   #
   # @author Alexey Ovchinnikov <alexiss@cybernetlab.ru>
   #
   module TextContainer
+    #
     def self.included(base)
       base.class_eval do
+        extend ClassMethods
+
         default_tag 'p', false
 
+        option(:body, if: %i(body text)) { |_, v| body << v }
+        argument(:body, first_only: true, after_options: true,
+                 if: String,
+                 and: ->{ !block_provided? || !text_in_block? }) do |_, v|
+          self.class.html_safe? && v = html_safe(v)
+          body << v
+        end
+
         section :body
         place :body, :before, :content
 
-        after_initialize do
-          @body = @arguments.extract_first!(String) || empty_html
-          @body += @options[:body] || @options[:text] || empty_html
-          @options.delete(:body)
-          @options.delete(:text)
-        end
-
         after_capture do
-          self[:body] = html_safe(@body) unless @body.nil?
+          self[:body] = html_safe(@body) unless @body.nil? || @body.empty?
         end
       end
     end
 
-    attr_accessor :body
+    #
+    # Retrieves body text
+    #
+    # @return [String] text
+    def body
+      @body ||= empty_html
+    end
+
+    module ClassMethods
+      #
+      # Sets priotiy of text source
+      #
+      # @param  value [Boolean] `true` means if block present - text will
+      #   be captured from there. `false` means first to inspect arguments and
+      #   options and if it ommited retirieve text from block.
+      #
+      # @return [Boolean] current value
+      def text_in_block(value = nil)
+        if value.nil?
+          @text_in_block.nil? && @text_in_block = true
+          @text_in_block
+        else
+          @text_in_block = value == true
+        end
+      end
+
+      #
+      # Retrieves block priority
+      #
+      # @return [Boolean] current value
+      def text_in_block?
+        @text_in_block.nil? && @text_in_block = true
+        @text_in_block
+      end
+
+      #
+      # Sets whether text from arguments are html-safe
+      # @param value [Boolean] `true` means that text from arguments have
+      #   proper markup and component will mark it as save via html_safe
+      #   method. `flase` means, that this values can contain unsafe content,
+      #   so user should make html-safe string by itself.
+      #
+      # @return [Boolean] current value
+      def html_safe(value = nil)
+        if value.nil?
+          @html_safe.nil? && @html_safe = true
+          @html_safe
+        else
+          @html_safe = value == true
+        end
+      end
+
+      #
+      # Retrieves whether text from attributes are html-safe
+      #
+      # @return [Boolean] current value
+      def html_safe?
+        @html_safe.nil? && @html_safe = true
+        @html_safe
+      end
+    end
   end
 end