= acts_as_enumeration

+acts_as_enumeration+ adds support for declaring an ActiveRecord class as an
enumeration.

== Resources

Wiki

* http://wiki.pluginaweek.org/Acts_as_enumeration

API

* http://api.pluginaweek.org/acts_as_enumeration

Development

* http://dev.pluginaweek.org/browser/trunk/acts_as_enumeration

Source

* http://svn.pluginaweek.org/trunk/acts_as_enumeration

== Description

Support for enumerations is dependent on the type of database you use.  For
example, MySQL has native support for the enum data type.  However, there is
no native Rails support for defining enumerations and the associations between
it and other models in the application.

acts_as_enumeration adds support for enumerations in Rails by providing methods
for interacting with records in a table as if they were values in an
enumeration.  The important thing to remember about this plugin is that you
always use the enumeration attributes within the application and know that the
enumeration ids are stored in the database.  This means that you would use 'red'
everywhere in your code when referencing the 'red' enumeration identifier, but
it would always be stored in the database with the integer value of 1.

In addition, remember that your enumerations act almost exactly like regular
ActiveRecord models.  This means that you can define validations, enumerations,
etc.  There is limited support for advanced finder options, address by the
acts_as_enumeration_in_memory plugin discussed later on.

== Usage

=== Default enumeration

  class Color < ActiveRecord::Base
    acts_as_enumeration
    
    create :id => 1, :name => 'red'
    create :id => 2, :name => 'blue'
    create :id => 3, :name => 'green'
  end

=== Customized enumeration

  class Book < ActiveRecord::Base
    acts_as_enumeration :title
    
    create :id => 1, :title => 'Blink'
  end

=== Additional enumeration attributes

  class Book < ActiveRecord::Base
    acts_as_enumeration :title
    
    column :author, :string
    column :num_pages, :integer
    
    validates_presence_of :author
    validates_presence_of :num_pages
    
    create :id => 1, :title => 'Blink', :author => 'Malcolm Gladwell', :num_pages => 277
  end

=== Associations

  class ColorGroup < ActiveRecord::Base
    acts_as_enumeration
    
    has_many :colors, :foreign_key => 'group_id'
    
    create :id => 1, :name => 'RGB'
    create :id => 2, :name => 'CMYK'
  end
  
  class Color < ActiveRecord::Base
    acts_as_enumeration
    
    column :group_id, :integer
    
    belongs_to :group, :class_name => 'ColorGroup'
    has_many :cars
  end

  class Car < ActiveRecord::Base
    belongs_to :color
  end

=== Setting enumeration attributes

  class Color < ActiveRecord::Base
    acts_as_enumeration
    
    create :id => 1, :name => 'red'
    create :id => 2, :name => 'blue'
    create :id => 3, :name => 'green'
  end
  
  class Car < ActiveRecord::Base
    belongs_to :car
  end
  
  car = Car.create(:color => 'red')
  car.color = 'blue'

== Future development

See acts_as_enumeration_in_memory[http://wiki.pluginaweek.org/Acts_as_enumeration_in_memory]
for more information about the future development of this plugin in terms of
ease of maintenance and utilization of ActiveRecord.  acts_as_enumeration_in_memory
is an experimental re-implementation of this plugin using an in-memory SQLite3
database.

== Testing

Before you can run any tests, the following gem must be installed:
* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]

To run against a specific version of Rails:

  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails

== Dependencies

* Rails 2.1 or later

== References

* Trevor Squires - enumerations_mixin[http://svn.protocool.com/rails/plugins/enumerations_mixin]