Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Define enumerations for a model attribute
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
rails
tasks
test
CHANGELOG
MIT-LICENSE
README
Rakefile
install.rb
uninstall.rb

README

= BelongsToEnum

IMPORTANT: Please be aware that I am no longer actively maintaining this plugin. I highly recommend the ActiveHash gem for setting up enum fields in your project.

== belongs_to_enum

Given that Task has an attribute status_id, you can define its enum fields like this:

    class Task < ActiveRecord::Base
      belongs_to_enum :status, { 1 => :new, 2 => :in_progress, 3 => :completed, 4 => :cancelled}
    end

Task will now have an array of status enum fields.

    >> Task.statuses
    => [EnumField(id: 1, name: :new, title: "New", position: 1, :default? => false), ... ]

Each EnumField object has the following attributes, of which only id and name are required:

* id
* name - symbol uniquely identifying the enum field
* title - for displaying the field in the view. Default is <code>name.to_s.titleize</code>.
* position - for sorting the enum fields. Task.statuses is sorted by position. Default is id.
* default - is this the default status?

You can now...

* get the status by id or by name

    >> Task.status(1)
    => EnumField(id: 1, name: :new, title: "New", position: 1, :default? => false)

    >> Task.status(:completed)
    => EnumField(id: 3, name: :completed, title: "Completed", position: 3, :default? => false)

* set the status of a task by enum_field or by name

    >> task.status = Task.status(:new)
    >> task.status = :completed

* check the status of a task

    >> task.completed?

* set the title or position of the enum fields

    >> belongs_to_enum :status, { 1 => :new, 2 => {:name => :in_progress, :title => 'Continuing', :position => 100}}

* specify the default status

    >> belongs_to_enum :status, { 1 => :new, 2 => {:name => :in_progress, :title => 'Continuing', :position => 100, :default => true}}
    >> Task.status(:in_progress).default?
    => true
    >> Task.default_status
    => EnumField(id: 2, name: :in_progress, title: "Continuing", position: 100, :default? => true)

== validates_inclusion_of_enum

To validate that the value of status is in the enum field list, you can use validates_inclusion_of_enum macro

    class Task < ActiveRecord::Base
      belongs_to_enum :status, { 1 => :new, 2 => :in_progress, 3 => :completed, 4 => :cancelled}
      validates_inclusion_of_enum :status_id
    end

The default error message of validates_inclusion_of_enum is 'is not valid' but you can pass any validates_inclusion_of options:

    validates_inclusion_of_enum :status_id,
    { :in => [3, :cancelled], :message => "must be completed or ended", :allow_blank => true}

Note that you can pass the id or the name of the enum field in the :in option.

== Saving the enum fields in a table

It's possible to save the enum fields in a database table. The table must have the following fields:

    create_table :statuses do |t|
      t.string :name
      t.string :title
      t.integer :position
      t.boolean :default
    end

You must then call acts_as_enum_field in the class

    class Status < ActiveRecord::Base
      acts_as_enum_field
    end

    class Task < ActiveRecord::Base
      belongs_to_enum :status
    end

Status will now have ActsAsEnumField extensions. For example, if the title of Status.first is nil,
calling <code>Status.first.title</code> will still return the titleized name like the EnumField.

== Sample usage

Here's how I might use belongs_to_enum.

In the model,

    class Task < ActiveRecord::Base
      belongs_to_enum :status,
      { 1 => {:name => :new, :default => true}
        2 => {:name => :in_progress, :title => 'Continuing'},
        3 => :completed,
        4 => {:name => :cancelled, :title => 'Ended', :position => 5}
      }
      validates_inclusion_of_enum :status_id, :allow_blank => true

      # Set the status to the default status
      def after_initialize
        self.status ||= Task.default_status if self.new_record?
      end
    end

Writing a dropdown for the statuses is pretty straightforward

    form_for @task do |f|
      f.select(:status_id, Task.statuses.collect {|p| [ p.title, p.id ] }, { :include_blank => true })
    end

== Similar plugins

* http://www.railslodge.com/plugins/8-acts-as-enumerated
* http://github.com/pluginaweek/acts_as_enumeration
* http://giraffesoft.ca/blog/2009/02/17/floss-week-day-2-the-enum-field-rails-plugin.html
* https://rubyforge.org/projects/enum-column
* http://github.com/zachinglis/magic_enums

== Tested in

* Rails 2.2
* Ruby 1.8.6

== Thanks

Thanks to Kevin Rood of Acceletron Corporation for allowing me to release this plugin.

Copyright (c) 2009 George Mendoza, released under the MIT license. Email: <code>["67736d656e646f7a6140676d61696c2e636f6d"].pack("H*")</code>
Something went wrong with that request. Please try again.