Module: Preferences::InstanceMethods

Defined in:
lib/preferences.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

:nodoc:



284
285
286
287
288
 
# File 'lib/preferences.rb', line 284

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



483
484
485
486
487
488
 
# File 'lib/preferences.rb', line 483

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



307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/preferences.rb', line 307

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|
      preferences[preference.name] = preference.value unless preferences.include?(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"]



461
462
463
 
# File 'lib/preferences.rb', line 461

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) 


442
443
444
 
# File 'lib/preferences.rb', line 442

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"



371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/preferences.rb', line 371

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) 


346
347
348
349
350
351
352
 
# File 'lib/preferences.rb', line 346

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



491
492
493
494
495
496
497
498
 
# File 'lib/preferences.rb', line 491

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!



408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
 
# File 'lib/preferences.rb', line 408

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 = value.to_i if preference_definitions[name].number?
  preferences_group(group)[name] = value

  value
end