h1. classy_enum

ClassyEnum is a Ruby on Rails gem that adds class-based enumerator functionality to ActiveRecord attributes.

h2. Requirements

*Rails:* Any version of Rails 2.3.x or Rails 3.x. (Older versions of Rails may work, but have not been tested)

*Ruby:* Ruby 1.8.7 and 1.9.2.

h2. Installation

The gem is hosted at "rubygems.org":https://rubygems.org/gems/classy_enum and can be installed with: @gem install classy_enum@

h2. Example Usage

The most common use for ClassyEnum is to replace database lookup tables where the content and behavior is mostly static and has multiple "types". In this example, I have an ActiveRecord model called @Alarm@ with an attribute called @priority@. Priority is stored as a string (VARCHAR) type in the database and is converted to an enum value when requested. 

The fastest way to get up and running with ClassyEnum is to use the built-in Rails generator like so:

Rails 2.3.x:

<pre>
script/generate classy_enum AlarmPriority low medium high
</pre>

Rails 3.x

<pre>
rails g classy_enum AlarmPriority low medium high
</pre>

A new file will be created at app/enums/alarm_priority.rb that will look like:

<pre>
class AlarmPriority < ClassyEnum::Base
  enum_classes :low, :medium, :high
end

class AlarmPriorityLow
end

class AlarmPriorityMedium
end

class AlarmPriorityHigh
end
</pre>

That is the default setup, but can be changed to fit your needs, like so...

Using the @enum_classes@ method, I have defined three priority levels: low, medium, and high. Each priority level can have different properties and methods associated with it. In my example, each enum class has a method called @email?@. By default this method returns false, but is overridden for high priority alarms and returns true.

<pre>
class AlarmPriority < ClassyEnum::Base
  enum_classes :low, :medium, :high
  
  def email?
    false
  end
end

class AlarmPriorityHigh
  def email?
    true
  end
end
</pre>

Then in my ActiveRecord model, Alarm, I've added a line that calls @classy_enum_attr@. The first argument is required, and is the name of the class defined above. The second argument is optional and specifies which Alarm attribute will be used as an enumerable. 

In this case, I am using the class AlarmPriority, but the name of my attribute is priority. By default, it will use the name of class as the attribute name. If I wanted to do @alarm.alarm_priority@, I would not have included the second argument.

<pre>
class Alarm < ActiveRecord::Base
  classy_enum_attr :alarm_priority, :priority
    
  delegate :email?, :to => :priority
end
</pre>

With this setup, I can now do the following:

<pre>
@alarm = Alarm.create(:priority => :medium)
  
@alarm.priority => AlarmPriorityMedium
  
@alarm.email? => false
  
@alarm.update_attribute(:priority, :high)
  
@alarm.email? => true
</pre>

h2. Formtastic Support

To add ClassyEnum support to Formtastic, add the following to your formtastic.rb initializer (config/initializers/formtastic.rb):

<pre>
Formtastic::SemanticFormHelper.builder = ClassyEnum::SemanticFormBuilder
</pre>

Then in your Formtastic view forms, use this syntax: @<%= f.input :priority, :as => :enum_select %>@

h2. Notes

An ActiveRecord validator @validates_inclusion_of :field, :in => ENUM.all, :allow_nil => true@ is automatically added to your model when you use @classy_enum_attr@. 

h2. Copyright

Copyright (c) 2010 Peter Brown. See LICENSE for details.