Module: EnumerateBy::MacroMethods

Defined in:
lib/enumerate_by.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extended(base) ⇒ Object

:nodoc:



15
16
17
18
19
20
21
22
 
# File 'lib/enumerate_by.rb', line 15

def self.extended(base) #:nodoc:
  base.class_eval do
    # Tracks which associations are backed by an enumeration
    # {"foreign key" => "association name"}
    class_inheritable_accessor :enumeration_associations
    self.enumeration_associations = {}
  end
end

Instance Method Details

#enumerate_by(attribute = :name, options = {}) ⇒ Object

Indicates that this class is an enumeration.

The default attribute used to enumerate the class is name. You can override this by specifying a custom attribute that will be used to uniquely reference a record.

Note that a presence and uniqueness validation is automatically defined for the given attribute since all records must have this value in order to be properly enumerated.

Configuration options:

  • :cache - Whether to cache all finder queries for this enumeration. Default is true.

Defining enumerators

The enumerators of the class uniquely identify each record in the table. The enumerator value is based on the attribute described above. In scenarios where the records are managed in code (like colors, countries, states, etc.), records can be automatically synchronized via #bootstrap.

Accessing records

The actual records for an enumeration can be accessed via shortcut helpers like so:

Color['red']    # => #<Color id: 1, name: "red">
Color['green']  # => #<Color id: 2, name: "green">

When caching is enabled, these lookup queries are cached so that there is no performance hit.

Associations

When using enumerations together with belongs_to associations, the enumerator value can be used as a shortcut for assigning the association.

In addition, the enumerator value is automatically used during serialization (xml and json) of the associated record instead of the foreign key for the association.

For more information about how to use enumerations with associations, see EnumerateBy::Extensions::Associations and EnumerateBy::Extensions::Serializer.

Finders

In order to be consistent by always using enumerators to reference records, a set of finder extensions are added to allow searching for records like so:

class Car < ActiveRecord::Base
  belongs_to :color
end

Car.find_by_color('red')
Car.all(:conditions => {:color => 'red'})

For more information about finders, see EnumerateBy::Extensions::BaseConditions.



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/enumerate_by.rb', line 84

def enumerate_by(attribute = :name, options = {})
  options.reverse_merge!(:cache => true)
  options.assert_valid_keys(:cache)
  
  extend EnumerateBy::ClassMethods
  extend EnumerateBy::Bootstrapped
  include EnumerateBy::InstanceMethods
  
  # The attribute representing a record's enumerator
  cattr_accessor :enumerator_attribute
  self.enumerator_attribute = attribute
  
  # Whether to perform caching of enumerators within finder queries
  cattr_accessor :perform_enumerator_caching
  self.perform_enumerator_caching = options[:cache]
  
  # The cache store to use for queries (default is a memory store)
  cattr_accessor :enumerator_cache_store
  self.enumerator_cache_store = ActiveSupport::Cache::MemoryStore.new
  
  validates_presence_of attribute
  validates_uniqueness_of attribute
end

#enumeration? ⇒ Boolean

Does this class define an enumeration? Always false.

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/enumerate_by.rb', line 109

def enumeration?
  false
end