Class: Settings::Setting

Inherits:
Object
  • Object
show all
Includes:
Zen::Validation
Defined in:
lib/zen/package/settings/lib/settings/setting.rb

Overview

Setting is a class that can be used to register and migrate settings without having to manually insert the data. It provides an API similar to registering packages or themes and takes care of synchronizing data between the database and the cache.

Adding Settings

In order to add a setting you'll first need to ensure there's at least a single setting group available. These groups don't add any extra features or whatsoever but are used to display settings in different tabs in the backend interface. In order to register a new group you'd write the following code:

Settings::SettingsGroup.add do |group|
  group.title = 'My Group'
  group.name  = :my_group
end

When registering a group you only need to specify a title and a name. The name is used to associate a setting with it's group and thus should always be unique. The title is displayed in the tab for the specific settings group.

Once a setting group has been added we can add a setting as following:

Settings::Setting.add do |setting|
  setting.title       = 'My Setting'
  setting.description = 'This is my setting!'
  setting.name        = :my_setting
  setting.group       = :my_group
  setting.type        = 'select'
  setting.values      = ['yorick', 'zen']
  setting.default     = 'yorick'
end

Note that the values array (or hash) is used to determine the possible values for a field. These values will only be used for elements that only allow a user to choose a single value (e.g. a checkbox). For the type getter/setter you can use any of the following values:

  • textbox
  • textarea
  • radio
  • checkbox
  • date
  • select
  • select_multiple

Migrating Settings

Once a setting has been added you still have to migrate it. Zen takes care of this so usually you don't need to manually migrate your settings. If you do want to migrate them however you can simple execute the following code:

Settings::Setting.migrate

Removing Settings

If you ever need to remove a setting both from the database and the system you can do so as following:

Settings::Setting.remove([:name, :name1])

You don't have to specify an array of names, you can also specify the name of a single setting to delete.

Since:

Constant Summary

Types =

Array containing all possible setting types.

Since:

  • 0.2.5

[
  'textbox',
  'textarea',
  'radio',
  'checkbox',
  'date',
  'select',
  'select_multiple'
]
REGISTERED =

Hash containing all registered settings.

Since:

  • 0.2.5

{}

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from Zen::Validation

#validates_filepath, #validates_format, #validates_length, #validates_presence

Instance Attribute Details

- (Object) default

The default value of the setting

Since:

  • 0.2.5



108
109
110
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 108

def default
  @default
end

- (String) description

Returns the description of the setting and translates it.

Returns:

  • (String)

Since:

  • 13-11-2011



247
248
249
250
251
252
253
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 247

def description
  begin
    return lang(@description)
  rescue
    return @description
  end
end

- (Object) group

The name of the settings group this setting belongs to

Since:

  • 0.2.5



99
100
101
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 99

def group
  @group
end

- (Object) name

The name of the setting

Since:

  • 0.2.5



90
91
92
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 90

def name
  @name
end

- (String) title

Returns the title of the setting and tries to translate it.

Returns:

  • (String)

Since:

  • 0.3



233
234
235
236
237
238
239
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 233

def title
  begin
    return lang(@title)
  rescue
    return @title
  end
end

- (Object) type

The type of setting (e.g. textbox)

Since:

  • 0.2.5



102
103
104
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 102

def type
  @type
end

- (Mixed) values

Retrieves the possible values for the setting. If the value is a Proc or Lambda (or anything else that responds to call()) it will be called and it's return value is used.

Returns:

  • (Mixed)

Since:

  • 0.2.8



305
306
307
308
309
310
311
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 305

def values
  if @values.respond_to?(:call)
    return @values.call
  else
    return @values
  end
end

Class Method Details

+ (Object) add {|setting| ... }

Registers a new setting using the specified block.

Examples:

Settings::Setting.add do |setting|
  setting.name    = 'example'
  setting.title   = 'Example setting'
  setting.group   = 'example'
  setting.type    = 'select'
  setting.values  = ['yorick', 'chuck']
end

Yields:

  • (setting)

Since:

  • 0.2.5



125
126
127
128
129
130
131
132
133
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 125

def add
  setting = self.new

  yield setting

  setting.validate

  REGISTERED[setting.name] = setting
end

+ (Object) migrate

Inserts all settings into the database. This method will ignore the settings that have already been inserted into the database.

Since:

  • 0.2.5



141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 141

def migrate
  settings = ::Settings::Model::Setting.all.map { |s| s.name }

  REGISTERED.each do |name, setting|
    name = name.to_s

    if !settings.include?(name)
      Zen.database[:settings].insert(
        :name  => name,
        :value => setting.serialize(setting.default)
      )
    end
  end
end

+ (Object) remove(names)

Removes the settings who's names match those specified in the array. The values of these settings will also be removed from the database.

Parameters:

  • namese (Array) —

    An array with setting names to remove.

Since:

  • 0.2.5



163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 163

def remove(names)
  if names.class != Array
    names = [names]
  end

  names.each_with_index do |v, k|
    names[k] = v.to_s
    REGISTERED.delete(v.to_sym)
  end

  ::Settings::Model::Setting.filter(:name => names).destroy
end

Instance Method Details

- (Array) form_parameters

Returns the parameters for the BlueForm helper.

Returns:

  • (Array)

Since:

  • 0.3



319
320
321
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 319

def form_parameters
  return BlueFormParameters.send(type, self)
end

- (String) serialize(value)

Serializes a value using Marshal and packs it so that it can be stored in the database.

Parameters:

  • value (Mixed) —

    The value to serialize.

Returns:

  • (String)

Since:

  • 13-11-2011



351
352
353
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 351

def serialize(value)
  return [Marshal.dump(value)].pack('m')
end

- (TrueClass|FalseClass) true?

Small helper method that makes it a bit easier to check if a certain setting is set to true or false. Because settings are stored as strings with values of "1" or "0" you'd normally have to do the following:

get_setting(:allow_registration).value == '1'

This method allows you to do the following instead:

get_setting(:allow_registration).true?

Returns:

  • (TrueClass|FalseClass)

Since:

  • 12-11-2011



337
338
339
340
341
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 337

def true?
  val = value

  return val.is_a?(String) && val == '1'
end

- (Mixed) unserialize(value)

Unserializes a value that was serialized using #serialize.

Parameters:

  • value (String) —

    The value to unserialize.

Returns:

  • (Mixed)

Since:

  • 13-11-2011



363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 363

def unserialize(value)
  begin
    return Marshal.load(value.unpack('m')[0])
  rescue
    begin
      return Marshal.load(value)
    rescue
      Ramaze::Log.debug(
        'Failed to unpack the setting using Marshal, using the ' \
          'raw value instead'
      )

      return value
    end
  end
end

- (Object) validate

Validates all attributes of this class.

Since:

  • 0.2.5



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 182

def validate
  validates_presence([:name, :title, :group, :type])

  # Validate the setting type
  if !Types.include?(type)
    raise(::Zen::ValidationError, "The setting type \"#{type}\" is invalid.")
  end

  # Check if the setting hasn't been registered yet
  if REGISTERED.key?(name)
    raise(
      ::Zen::ValidationError,
      "The setting #{name} has already been registered"
    )
  end

  # Validate the group
  if !Settings::SettingsGroup::REGISTERED.key?(group)
    raise(
      ::Zen::ValidationError,
      "The settings group \"#{group}\" doesn't exist."
    )
  end
end

- (Object) value

Retrieves the setting. If it exists in the cache the cache's value is used, otherwise it will be retrieved from the SQL database and cached.

Since:

  • 0.2.6.1



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 277

def value
  val = ::Ramaze::Cache.settings.fetch(name)

  # Get the setting from the database
  if val.nil?
    setting = ::Settings::Model::Setting[:name => name.to_s]

    # If the value is also nil we'll use the default value
    if setting.value.nil? or setting.value.empty?
      val = default
    else
      val = setting.value
    end

    ::Ramaze::Cache.settings.store(name, val)
  end

  return unserialize(val)
end

- (Object) value=(value)

Updates the value of a setting both in the cache and the SQL database.

Parameters:

  • value (String) —

    The value to set the setting to.

Since:

  • 0.2.6.1



261
262
263
264
265
266
267
268
269
 
# File 'lib/zen/package/settings/lib/settings/setting.rb', line 261

def value=(value)
  value = serialize(value)

  # First we'll update the SQL database
  ::Settings::Model::Setting[:name => name.to_s].update(:value => value)

  # Sync the cache
  ::Ramaze::Cache.settings.store(name, value)
end