Class: TrustyCms::Config::Definition

Inherits:
Object
  • Object
show all
Defined in:
lib/trusty_cms/config/definition.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Definition

Configuration ‘definitions’ are metadata held in memory that add restriction and description to individual config entries.

By default radiant’s configuration machinery is open and ad-hoc: config items are just globally-accessible variables. They’re created when first mentioned and then available in all parts of the application. The definition mechanism is a way to place limits on that behavior. It allows you to protect a config entry, to specify the values it can take and to validate it when it changes. In the next update it will also allow you to declare that a config item is global or site-specific.

The actual defining is done by TrustyCms::Config#define and usually in a block like this:

TrustyCms::Config.prepare do |config|
  config.namespace('users', :allow_change => true) do |users|
    users.define 'allow_password_reset?', :label => 'Allow password reset?'
  end
end

See the method documentation in TrustyCms::Config for options and conventions.



25
26
27
28
29
 
# File 'lib/trusty_cms/config/definition.rb', line 25

def initialize(options={})
  [:empty, :default, :type, :notes, :validate_with, :select_from, :allow_blank, :allow_change, :allow_display, :units, :definer].each do |attribute|
    instance_variable_set "@#{attribute}".to_sym, options[attribute]
  end
end

Instance Attribute Details

#allow_blank ⇒ Object (readonly)

Returns the value of attribute allow_blank.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def allow_blank
  @allow_blank
end

#allow_change ⇒ Object (readonly)

Returns the value of attribute allow_change.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def allow_change
  @allow_change
end

#allow_display ⇒ Object (readonly)

Returns the value of attribute allow_display.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def allow_display
  @allow_display
end

#default ⇒ Object (readonly)

Returns the value of attribute default.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def default
  @default
end

#definer ⇒ Object (readonly)

Returns the value of attribute definer.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def definer
  @definer
end

#empty ⇒ Object (readonly)

Returns the value of attribute empty.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def empty
  @empty
end

#notes ⇒ Object (readonly)

Returns the value of attribute notes.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def notes
  @notes
end

#select_from ⇒ Object (readonly)

Returns the value of attribute select_from.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def select_from
  @select_from
end

#type ⇒ Object (readonly)

Returns the value of attribute type.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def type
  @type
end

#units ⇒ Object (readonly)

Returns the value of attribute units.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def units
  @units
end

#validate_with ⇒ Object (readonly)

Returns the value of attribute validate_with.



5
6
7
 
# File 'lib/trusty_cms/config/definition.rb', line 5

def validate_with
  @validate_with
end

Instance Method Details

#allow_blank? ⇒ Boolean

Returns true unless :allow_blank has been explicitly set to false. Defaults to true. A config item that does not allow_blank must be set or it will not be valid.

Returns:

  • (Boolean) 


118
119
120
 
# File 'lib/trusty_cms/config/definition.rb', line 118

def allow_blank?
  true unless allow_blank == false
end

#boolean? ⇒ Boolean

Returns true if the definition included a :type => :boolean parameter. Config entries that end in ‘?’ are automatically considered boolean, whether a type is declared or not. config.boolean? may therefore differ from config.definition.boolean?

Returns:

  • (Boolean) 


41
42
43
 
# File 'lib/trusty_cms/config/definition.rb', line 41

def boolean?
  type == :boolean
end

#empty? ⇒ Boolean

Returns true if the definition included an :empty flag, which should only be the case for the blank, unrestricting definitions created when an undefined config item is set or got.

Returns:

  • (Boolean) 


34
35
36
 
# File 'lib/trusty_cms/config/definition.rb', line 34

def empty?
  !!empty
end

#hidden? ⇒ Boolean

Returns true if :allow_display has been explicitly set to false. Defaults to true.

Returns:

  • (Boolean) 


135
136
137
 
# File 'lib/trusty_cms/config/definition.rb', line 135

def hidden?
  true if allow_display == false
end

#integer? ⇒ Boolean

Returns true if the definition included a :type => :integer parameter

Returns:

  • (Boolean) 


52
53
54
 
# File 'lib/trusty_cms/config/definition.rb', line 52

def integer?
  type == :integer
end

#normalize_selection(choices) ⇒ Object

in definitions we accept anything that options_for_select would normally take here we standardises on an options array-of-arrays so that it’s easier to validate input



72
73
74
75
 
# File 'lib/trusty_cms/config/definition.rb', line 72

def normalize_selection(choices)
  choices = choices.to_a if Hash === choices
  choices = choices.collect{|c| (c.is_a? Array) ? c : [c,c]}
end

#selectable?(value) ⇒ Boolean

Returns true if the value is one of the permitted selections. Not case-sensitive.

Returns:

  • (Boolean) 


111
112
113
114
 
# File 'lib/trusty_cms/config/definition.rb', line 111

def selectable?(value)
  return true unless selector?
  selection.map(&:last).map(&:downcase).include?(value.downcase)
end

#selected(value) ⇒ Object

If the config item is a selector and :select_from specifies [name, value] pairs (as hash or array), this will return the name corresponding to the currently selected value.



80
81
82
83
84
 
# File 'lib/trusty_cms/config/definition.rb', line 80

def selected(value)
  if value && selector? && pair = selection.find{|s| s.last == value}
    pair.first
  end
end

#selection ⇒ Object

Returns the list of possible values for this config entry in a form suitable for passing to options_for_select. if :select_from is a proc it is called first with no arguments and its return value passed through.



59
60
61
62
63
64
65
66
67
 
# File 'lib/trusty_cms/config/definition.rb', line 59

def selection
  if selector?
    choices = select_from
    choices = choices.call if choices.respond_to? :call
    choices = normalize_selection(choices)
    choices.unshift ["",""] if allow_blank?
    choices
  end
end

#selector? ⇒ Boolean

Returns true if the definition included a :select_from parameter (either as list or proc).

Returns:

  • (Boolean) 


47
48
49
 
# File 'lib/trusty_cms/config/definition.rb', line 47

def selector?
  !select_from.blank?
end

#settable? ⇒ Boolean

Returns true unless :allow_change has been explicitly set to false. Defaults to true. A config item that is not settable cannot be changed in the running application.

Returns:

  • (Boolean) 


124
125
126
 
# File 'lib/trusty_cms/config/definition.rb', line 124

def settable?
  true unless allow_change == false
end

#validate(setting) ⇒ Object

Checks the supplied value against the validation rules for this definition. There are several ways in which validations might be defined or implied:

  • if :validate_with specifies a block, the setting object is passed to the block

  • if :type is :integer, we test that the supplied string resolves to a valid integer

  • if the config item is a selector we test that its value is one of the permitted options

  • if :allow_blank has been set to false, we test that the value is not blank



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/trusty_cms/config/definition.rb', line 93

def validate(setting)
  if allow_blank?
    return if setting.value.blank?
  else
    setting.errors.add :value, :blank if setting.value.blank?
  end
  if validate_with.is_a? Proc
    validate_with.call(setting)
  end
  if selector?
    setting.errors.add :value, :not_permitted unless selectable?(setting.value)
  end
  if integer?
    Integer(setting.value) rescue setting.errors.add :value, :not_a_number
  end
end

#visible? ⇒ Boolean

Returns true unless :allow_change has been explicitly set to false. Defaults to true. A config item that is not visible cannot be displayed in a radius tag.

Returns:

  • (Boolean) 


130
131
132
 
# File 'lib/trusty_cms/config/definition.rb', line 130

def visible?
  true unless allow_display == false
end