Class: WrapIt::Base

Inherits:
Object
  • Object
show all
Extended by:
Arguments::ClassMethods, Enums::ClassMethods, HTML::ClassMethods, Sections::ClassMethods, Switches::ClassMethods
Includes:
Arguments, Callbacks, DerivedAttributes, Enums, HTML, Renderer, Sections, Switches
Defined in:
lib/wrap_it/base.rb

Overview

Base class for all HTML helper classes

Examples:

Prevent user from changing element tag

class Helper < WrapIt::Base
  after_initialize { @tag = 'table' }
end

Including some simple HTML into content

class Helper < WrapIt::Base
  after_initialize do
    @icon = optioins.delete(:icon)
  end
  after_capture do
    unless @icon.nil?
    @content = html_safe("<i class=\"#{@icon}\"></i>") + @content
  end
end

Author:

Direct Known Subclasses

Container, Link

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(template, *args, &block) ⇒ Base

Returns a new instance of Base.



54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/wrap_it/base.rb', line 54

def initialize(template, *args, &block)
  @template, @block = template, block
  add_default_classes
  run_callbacks :initialize do
    capture_arguments!(args, &block)
    # TODO: uncomment following after html_attr implementation finished
    #html_attr.merge!(args.extract_options!)
    self.html_attr = args.extract_options!
    # TODO: find convenient way to save unprocessed arguments
    @arguments = args
  end
end

Instance Attribute Details

#helper_name ⇒ Object

Returns the value of attribute helper_name.



46
47
48
 
# File 'lib/wrap_it/base.rb', line 46

def helper_name
  @helper_name
end

Class Method Details

#argument(name, opts = {}) {|name, value| ... } ⇒ void Originally defined in module Arguments::ClassMethods

This method returns an undefined value.

Desclares argument for capturing on initialization process.

Inside initialization process, all arguments (except options hash), passed to constructor will be inspected to satisfy conditions, specified in :if and :and options. If this happens, and block given, it evaluated in context of component instance. If no block given, setter with name will be attempted to set value. In any way if conditions satisfied, argument removed from future processing.

If no conditions specified, the name of attribute taked as only condition.

Examples:

without conditions - name is a condition

class Button < WrapIt::Base
  argument(:disabled) { |name, value| puts 'DISABLED' }
end

Button.new(template, :disabled)   # => 'DISABLED'
Button.new(template, 'disabled')  # => nothing

with conditions and setter

class Button < WrapIt::Base
  argument :disabled, if: /^disable(?:d)?$/

  def disabled=(value)
    puts 'DISABLED'
  end
end

Button.new(template, :disabled)   # => 'DISABLED'
Button.new(template, 'disabled')  # => 'DISABLED'
Button.new(template, :disable)    # => 'DISABLED'
Button.new(template, 'some_text') # => nothing

Parameters:

  • name (Symbol) —

    unique name, used to refer to this declaration

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

  • :if (Object) —

    one or array of conditions that should be satisfied to capture argument. See CaptureArray for details. If array given, conditions will be or'ed.

  • :and (Object) —

    additional one or array of conditions, that will be and'ed with :if conditions.

  • :first_only (Boolean) — default: false —

    stop processing on first match

  • :after_options (Boolean) — default: false —

    process this argument after options

Yields:

  • (name, value) —

    yields every time argument captured. Evaluated in instance context

Yield Parameters:

  • name (Symbol) —

    name of argument, specified in name param above

  • value (Object) —

    real argument value

Since:

  • 1.0.0

#capture_arguments!(args, opts = {}, &block) ⇒ Array<Object> Originally defined in module Arguments::ClassMethods

Capture arguments for class and it's ancestors. All captured arguments and options will be extracted from original args argument.

Actually you rare needs to call this method directly. For example you can call it in instance capture_arguments! override to capture arguments for some child components.

Examples:

capturing arguments for child component

class Button < WrapIt::Base
  option(:color) { |name, value| puts "BUTTON COLOR IS: #{value}" }
end

class Toolbar < WrapIt::Base
  protected
  def capture_arguments!(args, &block)
    @button = Button.new(Button.capture_arguments!(args))
    super(args, &block) # ! don't forget to call parent method
  end
end

Toolbar.new(template, color: :red)  # => 'BUTTON COLOR IS red'

Parameters:

  • args (Array<Object>) —

    arguments to process (include options)

  • opts (Hash) (defaults to: {}) —

    options

  • &block (Proc) —

    block, passed to constructor if present

Options Hash (opts):

  • :inherited (Boolean) — default: true —

    process ancestors

  • :instance (Base) — default: nil —

    if specified valid instance, all #argument and #option blocks will and setters will be called.

Returns:

  • (Array<Object>) —

    captured arguments

.enum(name, values, opts = {}) {|value| ... } ⇒ void Originally defined in module Enums::ClassMethods

This method returns an undefined value.

Adds enum. When element created, creation arguments will be scanned for Symbol, that included contains in values. If it founded, enum takes this value. Also creation options inspected. If its contains name: value key-value pair with valid value, this pair removed from options and enum takes this value.

If you set html_class option to true, with each enum change, HTML class, composed from html_class_prefix and enum value will be added to element. If you want to override this prefix, specify it with html_class_prefix option. By default, enum changes are not affected to html classes.

This method also adds getter and setter for this enum.

Examples:

class Button < WrapIt::Base
  enum :style, i(red green black), html_class_prefix: 'btn-'
end

btn = Button.new(template, :green)
btn.render # => '<div class="btn-green">'
btn = Button.new(template, style: :red)
btn.render # => '<div class="btn-red">'

Parameters:

  • name (String, Symbol) —

    Enum name. Converted to Symbol.

  • opts (Hash) (defaults to: {}) —

    Enum options

Options Hash (opts):

  • :html_class_prefix (String, Symbol) —

    prefix of HTML class that will automatically added to element if enum changes its value.

  • :html_class (Boolean) —

    whether this enum changes should affect to html class.

  • :aliases (Symbol, Array<Symbol>) —

    list of enum aliases. Warning! Values are not converted - pass only Symbols here.

  • :default (String, Symbol) —

    default value for enum, if nil or wrong value given. Converted to Symbol.

Yields:

  • (value) —

    Runs block when enum value changed, gives it to block.

Yield Parameters:

  • value (Symbol) —

    New enum value.

Yield Returns:

  • (void)

#html_class([html_class, ...]) ⇒ void Originally defined in module HTML::ClassMethods

This method returns an undefined value.

Adds default html classes, thats are automatically added when element created.

Parameters:

  • html_class (String, Symbol, Array<String, Symbol>) —

    HTML class. Converted to String

.html_class_prefix(prefix = nil) ⇒ void Originally defined in module HTML::ClassMethods

This method returns an undefined value.

Sets HTML class prefix. It used in switchers and enums

Parameters:

  • prefix (String) (defaults to: nil) —

    HTML class prefix

#option(name, opts = {}) {|name, value| ... } ⇒ void Originally defined in module Arguments::ClassMethods

This method returns an undefined value.

Desclares option for capturing on initialization process.

Provides same manner as #argument but for hash of options, passed to constructor. Specified conditions are applied to options keys, not to values.

Hint: you can specify argument and options with same name to call same setter.

Examples:

shared setter

class Button < WrapIt::Base
  REGEXP = /^disable(?:d)?$/

  argument :disabled, if: REGEXP
  option   :disabled, if: i(disable disabled)

  def disabled=(value)
    if value == true || REGEXP =~ value.to_s
      puts 'DISABLED'
    end
  end
end

Button.new(template, :disabled)       # => 'DISABLED'
Button.new(template, 'disabled')      # => 'DISABLED'
Button.new(template, :disable)        # => 'DISABLED'
Button.new(template, disabled: true)  # => 'DISABLED'
Button.new(template, disable: true)   # => 'DISABLED'
Button.new(template, disable: false)  # => nothing
Button.new(template, 'some_text')     # => nothing

Parameters:

  • name (Symbol) —

    unique name, used to refer to this declaration

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

Yields:

  • (name, value) —

    yields every time option captured. Evaluated in instance context

Yield Parameters:

  • name (Symbol) —

    name of option, specified in name param above

  • value (Object) —

    real option value

Since:

  • 1.0.0

#place(src, to) ⇒ void #place(src, at, dst) ⇒ void Originally defined in module Sections::ClassMethods

This method returns an undefined value.

Places specific section in specified place

Overloads:

  • #place(src, to) ⇒ void

    Parameters:

    • src (Symbol) —

      section name to place

    • to (Hash) —

      single key-value hash. Key can be :before or after, value can be :begin, :end or section name

  • #place(src, at, dst) ⇒ void

    Parameters:

    • src (Symbol) —

      section name to place

    • at (Symbol) —

      can be :before or :after

    • dst (Symbol) —

      can be :begin, :end or section name

.placement ⇒ Array<Symbol> Originally defined in module Sections::ClassMethods

Retrieves section names in current order

Returns:

  • (Array<Symbol>) —

    ordered sections array

#section([name, ...]) ⇒ void Originally defined in module Sections::ClassMethods

This method returns an undefined value.

Defines new section or sections. Places its to end of section list

Parameters:

  • name (Symbol, String) —

    section name

.sections ⇒ Array<Symbol> Originally defined in module Sections::ClassMethods

Retrieves all sections, including ancestors

Returns:

  • (Array<Symbol>) —

    array of sections

.switch(name, options = {}) {|state| ... } ⇒ void Originally defined in module Switches::ClassMethods

This method returns an undefined value.

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 its contains name: true key-value pair, this pair removed from options and switch also turned on.

This method also adds getter and setter for this switch in form name? and name= respectively.

When html_class option specified and switch changes its state, HTML class for element will be computed as follows. if html_class options is true, html class produced from html_class_prefix and name of switch. If html_class is a String, Symbol or Array of this types, html class produced as array of html_class_prefix and each html_class concatinations. This classes added to element if switch is on or removed in other case.

Parameters:

  • name (String, Symbol) —

    Switch name. Converted to Symbol.

  • options (Hash) (defaults to: {}) —

    Switch options

Options Hash (options):

  • :html_class (true, String, Symbol, Array<String, Symbol>) —

    HTML classes list that will automatically added to element if switch is on or removed from element if switch id off.

  • :aliases (Symbol, Array<Symbol>) —

    list of aliases. Warning! Values are not converted - pass only Symbols here.

Yields:

  • (state) —

    Runs block when switch state changed, gives it to block.

Yield Parameters:

  • state (Boolean) —

    Whether switch is on or off.

Yield Returns:

  • (Object, FalseClass) —

    if you return false, value will ommited.

Instance Method Details

#[](name) ⇒ String Originally defined in module Sections

Retrieves specified section content

Parameters:

  • name (Symbol) —

    section name

Returns:

  • (String) —

    section content

#[]=(name, value) ⇒ String Originally defined in module Sections

Sets specified section content

Parameters:

  • name (Symbol) —

    section name

  • value (String) —

    content

Returns:

  • (String) —

    section content

#capture_arguments!(args, &block) ⇒ Array<Object> Originally defined in module Arguments

Captures arguments

In rare cases you can override this method to control directly arguments capturing process. Refer to capture_arguments! for examples.

Note that this method is protected, so override should be protected too.

Parameters:

  • args (Array<Object>) —

    arguments, passed to constructor

  • block (Proc) —

    block, passed to constructor

Returns:

  • (Array<Object>) —

    captured arguments

#html_attr ⇒ Hash Originally defined in module HTML

Retrieves HTML attributes hash (without HTML class and HTML data)

Returns:

  • (Hash) —

    attributes

#html_attr=(hash) ⇒ Hash Originally defined in module HTML

TODO: actually we should have separate setter and merge (see Base)

Sets HTML attributes hash.

Actually it merges its with current attributes. To remove some attributes use html_attr.delete(:attr). extracts HTML class and data from provided hash and places its to appropriate holder

Parameters:

  • hash (Hash) —

    attributes

Returns:

  • (Hash) —

    resulting attributes

#html_class ⇒ HTMLClass Originally defined in module HTML

Retrieves HTML class of element

See WrapIt::HTMLClass for details

Returns:

#html_class=(value) ⇒ HTMLClass Originally defined in module HTML

Sets HTML class(es) for element

Examples:

element.html_class = [:a, 'b', ['c', :d, 'a']]
element.html_class #=> ['a', 'b', 'c', 'd']

Parameters:

  • value (Symbol, String, Array<Symbol, String>) —

    HTML class or list of classes. All classes will be converted to Strings, duplicates are removed. Refer to WrapIt::HTMLClass description for details.

Returns:

#html_class_prefix ⇒ String Originally defined in module HTML

HTML class prefix getter

This prefix used in enums to combine HTML classes.

Returns:

  • (String) —

    HTML class prefix.

#html_data ⇒ Hash Originally defined in module HTML

Retrieves HTML data hash

Returns:

  • (Hash) —

    data

#omit_content? ⇒ Boolean

Returns:

  • (Boolean) 


81
82
83
 
# File 'lib/wrap_it/base.rb', line 81

def omit_content?
  self.class.get_derived(:@omit_content) == true
end

#render([content, ...]) {|element| ... } ⇒ String

Renders element to template

Parameters:

  • content (String) —

    additional content that will be appended to element content

Yields:

  • (element) —

    Runs block after capturing element content and before rendering it. Returned value appended to content.

Yield Parameters:

  • element (Base) —

    rendering element.

Yield Returns:

  • (String, nil) —

    content to append to HTML

Returns:

  • (String) —

    rendered HTML for element



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/wrap_it/base.rb', line 97

def render(*args, &render_block)
  # return cached copy if it available
  return @rendered unless @rendered.nil?

  capture_sections

  # add to content string args and block result if its present
  args.flatten.each { |a| self[:render_arguments] << a if a.is_a? String }
  if block_given?
    result = instance_exec(self, &render_block) || empty_html
    result.is_a?(String) && self[:render_block] << result
  end

  do_render
  do_wrap

  if @template.output_buffer.nil?
    # when render called from code, just return content as a String
    @rendered
  else
    # in template context, write content to templates buffer
    concat(@rendered)
    empty_html
  end
end

#run_callbacks(name) ⇒ void Originally defined in module Callbacks

This method returns an undefined value.

Runs specified callbacks with block

Runs first before callbacks in inheritance order, then yields block if it given and then after callbacks in reverse order.

Parameters:

  • name (Symbol) —

    callback name, that should be defined by callback method.

#tag ⇒ Object 



67
68
69
 
# File 'lib/wrap_it/base.rb', line 67

def tag
  @tag ||= (self.class.get_derived(:@default_tag) || 'div').to_s
end

#tag=(value) ⇒ Object 



71
72
73
74
 
# File 'lib/wrap_it/base.rb', line 71

def tag=(value)
  value.is_a?(Symbol) && value = value.to_s
  value.is_a?(String) && @tag = value
end

#unwrap ⇒ Object 



155
156
157
 
# File 'lib/wrap_it/base.rb', line 155

def unwrap
  @wrapper = nil
end

#wrap(wrapper) ⇒ void #wrap(wrapper_class, [arg, ...], options = {}) ⇒ void #wrap([arg, ...], options = {}) ⇒ void

This method returns an undefined value.

Wraps element with another.

You can provide wrapper directly or specify wrapper class as first argument. In this case wrapper will created with specified set of arguments and options. If wrapper class ommited, WrapIt::Base will be used.

If block present, it will be called when wrapper will rendered.

Overloads:

  • #wrap(wrapper) ⇒ void

    Parameters:

    • wrapper (Base) —

      wrapper instance.

  • #wrap(wrapper_class, [arg, ...], options = {}) ⇒ void

    Parameters:

    • wrapper_class (Class) —

      WrapIt::Base subclass for wrapper.

    • arg (String, Symbol) —

      wrapper creation arguments.

    • options (Hash) (defaults to: {}) —

      wrapper creation options.

  • #wrap([arg, ...], options = {}) ⇒ void

    Parameters:

    • arg (String, Symbol) —

      wrapper creation arguments.

    • options (Hash) (defaults to: {}) —

      wrapper creation options.



146
147
148
149
150
151
152
153
 
# File 'lib/wrap_it/base.rb', line 146

def wrap(*args, &block)
  if args.first.is_a?(Base)
    @wrapper = args.shift
  else
    wrapper_class = args.first.is_a?(Class) ? args.shift : Base
    @wrapper = wrapper_class.new(@template, *args, &block)
  end
end