Module: Preferences::InstanceMethods

Defined in:
lib/preferences.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

:nodoc:



297
298
299
300
301
 
# File 'lib/preferences.rb', line 297

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"]}



497
498
499
500
501
502
 
# File 'lib/preferences.rb', line 497

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"}



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

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"]



475
476
477
 
# File 'lib/preferences.rb', line 475

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) 


456
457
458
 
# File 'lib/preferences.rb', line 456

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"



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

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) 


360
361
362
363
364
365
366
 
# File 'lib/preferences.rb', line 360

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



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

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!



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

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