SimpleEnum

Build Status Code Climate

Unobtrusive enum-like fields for ActiveRecord and Ruby, brings enums functionality to ActiveRecord and Mongoid models (built for Rails 4+).

Since version 2.0, simple_enum is no longer compatible with Rails 3.x or Ruby 1.8, use version 1.6 instead: https://github.com/lwe/simple_enum/tree/legacy-1.x

Note: a recent search on github for enum turned out, that there are many, many similar solutions. In fact starting with Rails 4.1, there's ActiveRecord::Enum which provides some of the functionality, but is IMHO pretty limited and too strict in the defaults it provides.

ActiveRecord Quick start

Add this to a model:

class User < ActiveRecord::Base
  as_enum :gender, female: 1, male: 0
end

Then create the required gender_cd column using migrations:

class AddGenderColumnToUser < ActiveRecord::Migration
  def self.up
    add_column :users, :gender_cd, :integer
  end

  def self.down
    remove_column :users, :gender_cd
  end
end

Mongoid Quick start

Due to the dependency on ActiveModel 4.x, the Mongoid integration is only available for mongoid 4.0.0 (which is at beta1 at the moment). If you intend to use simple_enum with another version of mongoid, use version 1.6 instead.

Load mongoid support in the Gemfile:

gem 'simple_enum', '~> 2.0.0' , require: 'simple_enum/mongoid'

Add this to a model:

class User
  include Mongoid::Document
  include SimpleEnum::Mongoid

  as_enum :gender, female: 1, male: 0
end

The primary difference between AR and mongoid is, that additionaly a field is added to mongoid automatically, the field can be customized by setting field: option, or disabled by setting field: false.

Working with enums

Now it's possible to pull some neat tricks on the new column, yet the original db column (gender_cd) is still intact and not touched by anything.

jane = User.new
jane.gender = :female
jane.female?   # => true
jane.male?     # => false
jane.gender    # => :female
jane.gender_cd # => 1

Easily switch to another value using the bang methods, this does not save the record, only switch the value.

joe = User.new
joe.male!     # => :male
joe.gender    # => :male
joe.gender_cd # => 0

Accessing actual enum values is possible at the class level:

User.genders                            # => #<SimpleEnum::Enum:0x0....>
User.genders[:male]                     # => 0
User.genders.values_at(:male, :female)  # => [0, 1]
User.females                            # => #<ActiveRecord::Relation:0x0.....> (WHERE gender_cd = 1)

Wait, there's more!

  class User < ActiveRecord::Base
    as_enum :status, %i{deleted active disabled}
    # translates to: { deleted: 0, active: 1, disabled: 2 }
  end

Disclaimer: if you ever decide to reorder this array, beaware that any previous mapping is lost. So it's recommended to create mappings (that might change) using hashes instead of arrays. For stuff like gender it might be probably perfectly fine to use arrays though. - You can store as string values instead of integer values if your database column has the type string or text:

  class User < ActiveRecord::Base
    as_enum :status, [:deleted, :active, :disabled], map: :string
  end

  User.create!(status: :active) #=> #<User id: 1, status_cd: "active">
  class MyModel
    extend SimpleEnum::Attribute
    attr_accessor :gender_cd
    as_enum :gender, [:male, :female]
  end
  class User < ActiveRecord::Base
    as_enum :gender, [:male, :female], source: :sex
  end

Starting with 2.0 it's possible to use the same source name as column name. - By default ActiveRecord dirty methods are generated:

  user = User.male.first
  user.gender = :female
  user.gender_was
  # => :male
  # skip field generation
  field :gender_cd # <- create field manually (!)
  as_enum :gender, [:male, :female], field: false

  # custom field options (directly passed to Mongoid::Document#field)
  as_enum :gender, [:male, :female], field: { :type => Integer, :default => 1 }

jane = User.new gender: :female jane.genderfemale? # => true User.gender_females # => `` The:prefixoption not only takes a boolean value as an argument, but instead can also be supplied a custom prefix, so withprefix: 'foo'all shortcut methods would look like:foo - To define which methods are generated it's possible to setwith:option, by defaultwith:is set to[:attribute, :dirty, :scope]`.

  1. :attribute - generates the male? and male! accessor methods
  2. :dirty - adds the gender_was and gender_changed? dirty methods
  3. :scope - adds the class level scopes, if the scope method is present

    • By default the value is set to nil when the user sets an invalid value, this behavior can be changed by setting the accessor: option. At the moment there are three different behaviors:
  4. :default - which sets the value simply to nil

  5. :whiny - raises an ArgumentError when trying to set an invalid value

  6. :ignore - keeps the existing value

  class User < ActiveRecord::Base
    as_enum :gender, %w{male female}, accessor: :whiny
  end
  User.new(gender: "dunno") # => raises ArgumentError

See lib/simple_enum/accessors/* for more.

  # See lib/simple_enum.rb for other options
  SimpleEnum.with = [:accessor, :scope]

View Helpers

Require translated enum values? See SimpleEnum::ViewHelpers for more details and functions. Disclaimer: these methods are release candidate quality so expect them to change in future versions of SimpleEnum.

  translate_enum user, :gender # => "Frau" # assuming :de and translations exist
  te user, :gender # translate_enum is also aliased to te
  select :user, :gender, enum_option_pairs(User, :gender)
  select :user, :gender_cd, enum_option_pairs(User, :gender, true)

Best practices

Do not use values named after existing, or well known method names, like new, create etc.

# BAD, conflicts with Rails ActiveRecord Methods (!)
as_enum :handle, [:new, :create, :update]

# GOOD, prefixes all methods
as_enum :handle, [:new, :create, :update], prefix: true

Searching for certain values by using the finder methods:

User.females # => returns an ActiveRecord::Relation

Contributors

License & Copyright

Copyright (c) 2011-2014 by Lukas Westermann, Licensed under MIT License (see LICENSE file)