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 trusty’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.



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

def initialize(options = {})
  %i[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.



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

def allow_blank
  @allow_blank
end

#allow_change ⇒ Object (readonly)

Returns the value of attribute allow_change.



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

def allow_change
  @allow_change
end

#allow_display ⇒ Object (readonly)

Returns the value of attribute allow_display.



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

def allow_display
  @allow_display
end

#default ⇒ Object (readonly)

Returns the value of attribute default.



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

def default
  @default
end

#definer ⇒ Object (readonly)

Returns the value of attribute definer.



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

def definer
  @definer
end

#empty ⇒ Object (readonly)

Returns the value of attribute empty.



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

def empty
  @empty
end

#notes ⇒ Object (readonly)

Returns the value of attribute notes.



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

def notes
  @notes
end

#select_from ⇒ Object (readonly)

Returns the value of attribute select_from.



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

def select_from
  @select_from
end

#type ⇒ Object (readonly)

Returns the value of attribute type.



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

def type
  @type
end

#units ⇒ Object (readonly)

Returns the value of attribute units.



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

def units
  @units
end

#validate_with ⇒ Object (readonly)

Returns the value of attribute validate_with.



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

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) 


122
123
124
 
# File 'lib/trusty_cms/config/definition.rb', line 122

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) 


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

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) 


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

def empty?
  !!empty
end

#hidden? ⇒ Boolean

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

Returns:

  • (Boolean) 


139
140
141
 
# File 'lib/trusty_cms/config/definition.rb', line 139

def hidden?
  true if allow_display == false
end

#integer? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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



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

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) 


114
115
116
117
118
 
# File 'lib/trusty_cms/config/definition.rb', line 114

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.



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

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.



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

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) 


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

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) 


128
129
130
 
# File 'lib/trusty_cms/config/definition.rb', line 128

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



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

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?
    begin
      Integer(setting.value)
    rescue StandardError
      setting.errors.add :value, :not_a_number
    end
  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) 


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

def visible?
  true unless allow_display == false
end