Module: Preferences::InstanceMethods

Defined in:
lib/preferences.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

:nodoc:



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

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



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

def preference_changes(group = nil)
  preferences_changed(group).each_with_object({}) do |preference, changes|
    changes[preference] = preference_change(preference, group)
  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"}



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

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.each_with_object({}) do |(name, value), typed_preferences|
    typed_preferences[name] = value.nil? ? value : preference_definitions[name].type_cast(value)
  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"]



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

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) 


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

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"



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

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) 


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

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
  @preferences_changed&.clear

  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!



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

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