Module: Preferences::InstanceMethods

Defined in:
lib/preferences.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

:nodoc:



282
283
284
285
286
 
# File 'lib/preferences.rb', line 282

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



481
482
483
484
485
486
 
# File 'lib/preferences.rb', line 481

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



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

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



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

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) 


440
441
442
 
# File 'lib/preferences.rb', line 440

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"



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

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) 


344
345
346
347
348
349
350
 
# File 'lib/preferences.rb', line 344

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



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

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!



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

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] = value
  
  value
end