Skip to content
This repository

A class based enumerator gem for Rails

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.textile

classy_enum

ClassyEnum adds class-based enumerator functionality to your ActiveRecord model’s attributes.

Requirements

Rails: ClassyEnum should work with any version of Rails 2.3.×. Rails 3 support is in the works, and should be ready soon.

Ruby: ClassyEnum has been tested with Ruby 1.8.7 and 1.9.2.

Installation

The gem is hosted at rubygems.org

It can be installed with:

  gem install classy_enum

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:

script/generate classy_enum AlarmPriority low medium high

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

module AlarmPriority
  OPTIONS = [:low, :medium, :high]

  module InstanceMethods
  end

  module ClassMethods
  end

  include ClassyEnum
end

class AlarmPriorityLow
end

class AlarmPriorityMedium
end

class AlarmPriorityHigh
end

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

Using the OPTIONS constant, 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 value has a method called email?. By default this method returns false, but is overridden for high priority alarms and returns true.

It is important that you include ClassyEnum AFTER declaring your OPTIONS and Default methods because they are used when creating the enum classes

module AlarmPriority
  OPTIONS = [:low, :medium, :high]

  module InstanceMethods
    def email?
      false
    end
  end

  include ClassyEnum
end

class AlarmPriorityHigh
  def email?
    true
  end
end

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 module 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 module AlarmPriority, but the name of my attribute is priority. By default, it will use the name of module as the attribute name. If I wanted to do alarm.alarm_priority, I would not have included the second argument.

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

With this setup, I can now do the following:

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

Formtastic Support

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

Formtastic::SemanticFormHelper.builder = ClassyEnumHelper::SemanticFormBuilder

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

Notes

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

Copyright

Copyright © 2010 Peter Brown. See LICENSE for details.

Something went wrong with that request. Please try again.