Module: Preferences::InstanceMethods

Defined in:
lib/preferences.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

:nodoc:



299
300
301
302
303
 
# File 'lib/preferences.rb', line 299

def self.included(base) #:nodoc:
  base.class_eval do
    alias_method :prefs, :preferences
  end
end

Instance Method Details

#preference_changes(group = nil) ⇒ Object

A map of the preferences that have changed in the current object.

Examples

user = User.find(:first)
user.preferred(:color)                      # => nil
user.preference_changes                     # => {}

user.write_preference(:color, 'red')
user.preference_changes                     # => {"color" => [nil, "red"]}
user.save
user.preference_changes                     # => {}

# Groups
user.preferred(:color, :car)                # => nil
user.preference_changes(:car)               # => {}
user.write_preference(:color, 'red', :car)
user.preference_changes(:car)               # => {"color" => [nil, "red"]}



499
500
501
502
503
504
 
# File 'lib/preferences.rb', line 499

def preference_changes(group = nil)
  preferences_changed(group).inject({}) do |changes, preference|
    changes[preference] = preference_change(preference, group)
    changes
  end
end

#preferences(group = nil) ⇒ Object

Finds all preferences, including defaults, for the current record. If looking up custom group preferences, then this will include all default preferences within that particular group as well.

Examples

A user with no stored values:

user = User.find(:first)
user.preferences
=> {"language"=>"English", "color"=>nil}

A user with stored values for a particular group:

user.preferred_color = 'red', :cars
user.preferences(:cars)
=> {"language=>"English", "color"=>"red"}



322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
 
# File 'lib/preferences.rb', line 322

def preferences(group = nil)
  preferences = preferences_group(group)

  unless preferences_group_loaded?(group)
    group_id, group_type = Preference.split_group(group)
    find_preferences(:group_id => group_id, :group_type => group_type).each do |preference|
      # fixed: ignore entries in database that are not present in the definition
      preferences[preference.name] = preference.value unless (preferences.include?(preference.name) || !preference_definitions[preference.name])
    end

    # Add defaults
    preference_definitions.each do |name, definition|
      preferences[name] = definition.default_value(group_type) unless preferences.include?(name)
    end
  end

  preferences.inject({}) do |typed_preferences, (name, value)|
    typed_preferences[name] = value.nil? ? value : preference_definitions[name].type_cast(value)
    typed_preferences
  end
end

#preferences_changed(group = nil) ⇒ Object

A list of the preferences that have unsaved changes.

Examples

user = User.find(:first)
user.preferences_changed                    # => []
user.write_preference(:color, 'red')
user.preferences_changed                    # => ["color"]
user.save
user.preferences_changed                    # => []

# Groups
user.preferences_changed(:car)              # => []
user.write_preference(:color, 'red', :car)
user.preferences_changed(:car)              # => ["color"]



477
478
479
 
# File 'lib/preferences.rb', line 477

def preferences_changed(group = nil)
  preferences_changed_group(group).keys
end

#preferences_changed?(group = nil) ⇒ Boolean

Whether any attributes have unsaved changes.

Examples

user = User.find(:first)
user.preferences_changed?                   # => false
user.write_preference(:color, 'red')
user.preferences_changed?                   # => true
user.save
user.preferences_changed?                   # => false

# Groups
user.preferences_changed?(:car)             # => false
user.write_preference(:color, 'red', :car)
user.preferences_changed(:car)              # => true

Returns:

  • (Boolean) 


458
459
460
 
# File 'lib/preferences.rb', line 458

def preferences_changed?(group = nil)
  !preferences_changed_group(group).empty?
end

#preferred(name, group = nil) ⇒ Object Also known as: prefers

Gets the actual value stored for the given preference, or the default value if nothing is present.

Examples

class User < ActiveRecord::Base
  preference :color, :string, :default => 'red'
end

user = User.create
user.preferred(:color)            # => "red"
user.preferred(:color, 'cars')    # => "red"
user.preferred(:color, Car.first) # => "red"

user.write_preference(:color, 'blue')
user.preferred(:color)            # => "blue"



387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'lib/preferences.rb', line 387

def preferred(name, group = nil)
  name = name.to_s
  assert_valid_preference(name)

  if preferences_group(group).include?(name)
    # Value for this group/name has been written, but not saved yet:
    # grab from the pending values
    value = preferences_group(group)[name]
  else
    # Grab the first preference; if it doesn't exist, use the default value
    group_id, group_type = Preference.split_group(group)
    preference = find_preferences(:name => name, :group_id => group_id, :group_type => group_type).first unless preferences_group_loaded?(group)

    value = preference ? preference.value : preference_definitions[name].default_value(group_type)
    preferences_group(group)[name] = value
  end

  definition = preference_definitions[name]
  value = definition.type_cast(value) unless value.nil?
  value
end

#preferred?(name, group = nil) ⇒ Boolean Also known as: prefers?

Queries whether or not a value is present for the given preference. This is dependent on how the value is type-casted.

Examples

class User < ActiveRecord::Base
  preference :color, :string, :default => 'red'
end

user = User.create
user.preferred(:color)              # => "red"
user.preferred?(:color)             # => true
user.preferred?(:color, 'cars')     # => true
user.preferred?(:color, Car.first)  # => true

user.write_preference(:color, nil)
user.preferred(:color)              # => nil
user.preferred?(:color)             # => false

Returns:

  • (Boolean) 


362
363
364
365
366
367
368
 
# File 'lib/preferences.rb', line 362

def preferred?(name, group = nil)
  name = name.to_s
  assert_valid_preference(name)

  value = preferred(name, group)
  preference_definitions[name].query(value)
end

#reload(*args) ⇒ Object

Reloads the pereferences of this object as well as its attributes



507
508
509
510
511
512
513
514
 
# File 'lib/preferences.rb', line 507

def reload(*args) #:nodoc:
  result = super

  @preferences.clear if @preferences
  @preferences_changed.clear if @preferences_changed

  result
end

#write_preference(name, value, group = nil) ⇒ Object

Sets a new value for the given preference. The actual Preference record is not created until this record is saved. In this way, preferences act exactly the same as attributes. They can be written to and validated against, but won’t actually be written to the database until the record is saved.

Examples

user = User.find(:first)
user.write_preference(:color, 'red')              # => "red"
user.save!

user.write_preference(:color, 'blue', Car.first)  # => "blue"
user.save!



424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
 
# File 'lib/preferences.rb', line 424

def write_preference(name, value, group = nil)
  name = name.to_s
  assert_valid_preference(name)

  preferences_changed = preferences_changed_group(group)
  if preferences_changed.include?(name)
    old = preferences_changed[name]
    preferences_changed.delete(name) unless preference_value_changed?(name, old, value)
  else
    old = clone_preference_value(name, group)
    preferences_changed[name] = old if preference_value_changed?(name, old, value)
  end

  value = convert_number_column_value(value) if preference_definitions[name].number?
  preferences_group(group)[name] = preference_definitions[name].type_cast(value)

  value
end