module Card::View::Options::VooApi

VooApi methods let developers use view options dynamically.

Attributes

normalized_options[R]
  • @normalized_options are determined upon initialization and do not change

after that. @return [Hash] options

Public Class Methods

define_getter(option_key) click to toggle source
# File lib/card/view/options/voo_api.rb, line 25
def define_getter option_key
  define_method option_key do
    live_options[option_key]
  end
end
define_setter(option_key) click to toggle source
# File lib/card/view/options/voo_api.rb, line 31
def define_setter option_key
  define_method "#{option_key}=" do |value|
    live_options[option_key] = special_option_value(option_key, value) || value
  end
end
included(base) click to toggle source
# File lib/card/view/options/voo_api.rb, line 14
def included base
  # Developers can also set most options directly via accessors,
  # eg voo.title = "King"
  # :view, :show, and :hide have non-standard access (see #accessible_keys)

  base.accessible_keys.each do |option_key|
    define_getter option_key unless option_key == :items
    define_setter option_key
  end
end

Public Instance Methods

items() click to toggle source

“items”, the option used to configure views of each of a list of cards, is currently the only Hash option (thus this accessor override) @return [Hash]

# File lib/card/view/options/voo_api.rb, line 41
def items
  live_options[:items] ||= {}
end
normalize_cache(value) click to toggle source
# File lib/card/view/options/voo_api.rb, line 80
def normalize_cache value
  value&.to_sym
end
normalize_edit(value) click to toggle source
# File lib/card/view/options/voo_api.rb, line 76
def normalize_edit value
  value&.to_sym
end
normalize_input_type(value) click to toggle source
# File lib/card/view/options/voo_api.rb, line 72
def normalize_input_type value
  value&.to_sym
end
normalize_special_options!(opts) click to toggle source

ACCESSOR_HELPERS methods that follow the normalize_#{key} pattern are called by accessors (arguably that should be done during normalization!)

# File lib/card/view/options/voo_api.rb, line 61
def normalize_special_options! opts
  opts.each do |option_key, value|
    new_value = special_option_value option_key, value
    opts[option_key] = new_value if new_value
  end
end
normalize_wrap(value) click to toggle source
# File lib/card/view/options/voo_api.rb, line 84
def normalize_wrap value
  value = value.split(",").map(&:strip) if value.is_a? String
  Array.wrap(value).compact.flatten
end
slot_options() click to toggle source

options to be used in data attributes of card slots (normalized options with standard keys) FIXME: what we really want is options as they were when render was called. normalized is wrong because it can get changed before render. live is wrong because they can get changed after. current solution is a compromise. @return [Hash]

# File lib/card/view/options/voo_api.rb, line 51
def slot_options
  normalized_options.merge(view: requested_view)
                    .merge(normalized_visibility_options)
                    .slice(*Options.slot_keys)
end
special_option_value(option_key, value) click to toggle source
# File lib/card/view/options/voo_api.rb, line 68
def special_option_value option_key, value
  try "normalize_#{option_key}", value
end

Protected Instance Methods

live_options() click to toggle source
  • @live_options are dynamic and can be altered by the “voo” API at any time.

Such alterations are NOT used in the stub of the current voo, but they ARE inherited by children voos.

@return [Hash]

# File lib/card/view/options/voo_api.rb, line 96
def live_options
  @live_options ||= process_live_options
end

Private Instance Methods

add_implicit_options!() click to toggle source
# File lib/card/view/options/voo_api.rb, line 115
def add_implicit_options!
  @normalized_options[:view] = @raw_view
  @normalized_options[:main] = true if format.main?
  # opts[:context_names] = format.context_names
end
foreign_options_in(opts) click to toggle source

find non-standard option in Hash @param opts [Hash] options hash @return [Hash] options Hash

# File lib/card/view/options/voo_api.rb, line 199
def foreign_options_in opts
  foreign_opts = opts.reject { |k, _v| Options.all_keys.include? k }
  foreign_opts.empty? ? nil : foreign_opts
end
inherit_from_parent!(option_key) click to toggle source
# File lib/card/view/options/voo_api.rb, line 143
def inherit_from_parent! option_key
  return unless (parent_value = parent.live_options[option_key])

  @normalized_options[option_key] ||= parent_value
end
inherit_options_from_parent!() click to toggle source

standard inheritance from parent view object

# File lib/card/view/options/voo_api.rb, line 135
def inherit_options_from_parent!
  return unless parent

  Options.heir_keys.each do |option_key|
    inherit_from_parent! option_key
  end
end
normalize_options() click to toggle source

option normalization includes standardizing options into a hash with symbols as keys, managing standard view inheritance, and special handling for main_views.

# File lib/card/view/options/voo_api.rb, line 105
def normalize_options
  @normalized_options = opts = options_to_hash @raw_options.clone
  normalize_special_options! opts
  @optional = opts.delete(:optional) || false
  add_implicit_options!
  inherit_options_from_parent!
  validate_options! opts
  opts
end
options_to_hash(opts) click to toggle source

typically options are already a hash. this also handles an array of hashes and nil.

# File lib/card/view/options/voo_api.rb, line 123
def options_to_hash opts
  case opts
  when ActionController::Parameters
    opts.to_unsafe_h.deep_symbolize_keys
  when Hash  then opts.deep_symbolize_keys!
  when Array then opts[0].merge(opts[1]).deep_symbolize_keys!
  when nil   then {}
  else raise Card::Error, "bad view options: #{opts}"
  end
end
process_before_view() click to toggle source

This method triggers the “before” blocks which can alter the @live_options hash both directly and indirectly (via the voo API)

# File lib/card/view/options/voo_api.rb, line 162
def process_before_view
  format.before_view requested_view
end
process_live_options() click to toggle source
# File lib/card/view/options/voo_api.rb, line 149
def process_live_options
  @live_options = normalized_options.clone
  process_main_nest_options
  process_before_view
  process_visibility
  return :hide if hide_requested_view? # bail to avoid unnecessary processing

  process_view_wrappers
  @live_options
end
process_main_nest_options() click to toggle source

merge the options of the main nest into the @live_options They are not processed in normalize_options so that they’re NOT locked in the stub.

# File lib/card/view/options/voo_api.rb, line 184
def process_main_nest_options
  @live_options.merge! format.main_nest_options if @live_options[:main_view]
end
process_view_wrappers() click to toggle source

adds the wrappers assigned to ok_view in view definition

# File lib/card/view/options/voo_api.rb, line 167
def process_view_wrappers
  view_wrappers = format.view_setting(:wrap, ok_view)
  return unless view_wrappers.present?

  @live_options[:wrap] = Array.wrap(@live_options[:wrap])
  if view_wrappers.is_a? ::Hash
    view_wrappers.each_pair do |name, opts|
      @live_options[:wrap] << [name, opts]
    end
  else
    @live_options[:wrap] += Array.wrap(view_wrappers)
  end
end
validate_options!(opts) click to toggle source
# File lib/card/view/options/voo_api.rb, line 188
def validate_options! opts
  return unless (foreign_opts = foreign_options_in opts)

  # TODO: this should raise a UserError if the options come directly from params
  # (eg, mycard?slot[badoption]=true should not be treated as a server error)
  raise Card::Error, "illegal view options: #{foreign_opts}"
end