Easily code enumerations for your models and expose them as
drop-down lists with the enum_select helper, or use any of enumerated_attribute features to simplify coding enumerations in any Ruby object.
Development
Source
-
git://github.com/jeffp/enumerated_attribute.git
Install
-
sudo gem install enumerated_attribute
-
Rails 3 … dynamic finders working… should be rails3 ready. We are completing form tests.
-
Rails 2.3.8 breaks find_or_create_by_… and find_or_initialize_by_… methods. Write me if you gotta have it… otherwise happy Rails3.
-
Write cleaner code … implement state patterns for your enumerated attributes (enumerated_state)
If something needs fixed, please submit issues to this Github project in the Issues tab and provide a series of FAILING RSPEC tests that I can drop into the current RSpec test framework and run with little to no coersing. Thanks.
-
Lailson Bandeira - Rails 3 updates
Typically, in Ruby, enumerated attributes are implemented with strings, symbols or constants. Often the developer is burdened with repeatedly defining common methods in support of each attribute. enumerated_attribute provides a DRY implementation for enumerations in Rails.
Repetitive code such as initializers, accessors, predicate and enumeration methods are automatically generated along with the following features:
-
ActiveRecord integration
-
ActionView form helpers
-
Scaffold generator integration
-
Definable enumeration labels
-
Enum helper methods
-
Dynamic predicate methods
-
Initialization
-
State pattern support (enumerated_state)
For a Ruby application, install the gem and require it
require 'enumerated_attribute'
or for a rails application configure the gem in the config block of the config/environment.rb file
config.gem "enumerated_attribute"
and run the gem install rake task
rake gems:install
Here’s an example of enumerated_attribute features in a Rails application:
In the migration, declare your enumeration attributes with enum
create_table :users, :force=>true do |t| t.string :first_name t.enum :gender t.enum :degree ... end
Define the enumerations in your models with enum_attr
class User < ActiveRecord::Base enum_attr :gender, %w(male female) enum_attr :degree, %w(^none high_school college graduate) end
Expose the enumeration in your forms with enum_select
<% form_for :user do |f| %> <%= f.label :user %> <%= f.text_field :first_name %><br/> <%= f.label :gender %> <%= f.enum_select :gender %><br/> <%= f.label :degree %> <%= f.enum_select :degree %><br/> <%= submit_tag 'save' %> <% end %>
or generate a scaffold with one of your favorite scaffold generators. Currently supports most scaffold generators including scaffold, wizardly_scaffold, nifty_scaffold, rspec_scaffold, and haml_scaffold. See the section ‘Generating Scaffolds’ below.
The select options text can be customized. See ‘Customizing Labels’ in the Integration section.
Here’s an example of enumerated_attribute features in a Ruby application:
require 'enumerated_attribute' class Tractor enum_attr :gear, %w(reverse ^neutral first second over_drive)
end t = Tractor.new t.gear # => :neutral t.neutral? # => true t.gear_next # => :first t.not_neutral? # => true t.gear_previous # => :neutral t.gear = :second # => :second t.gear_is_not_in_first? # => true
An explanation of the above features and their usage follows.
Defining an enumerated attribute is as simple as this:
require 'enumerated_attribute' class Tractor enumerated_attribute :gear, %w(reverse neutral first second over_drive) def initialize @gear = :neutral end end
Notice the plugin enumerated_attribute is required at the top of the code.
The require line must be added at least once at some point in the code.
It is not included in subsequent examples.
The above code uses enumerated_attribute to define an attribute named ‘gear’ with five enumeration values.
In general, enumerated_attribute takes three parameters: the name of the attribute, an array of enumeration values (either symbols or strings), and an optional hash of options (not shown above). The complete form of enumerated_attribute looks like this:
enumerated_attribute :name, array_of_enumerations, hash_of_options
Defining the attribute :gear has done a number things.
It has generated an instance variable ‘@gear’, read/write accessors for the attribute and support methods for the enumeration, such as incrementor and decrementor methods. These methods are demonstrated below using the Tractor class above:
Tractor.instance_methods(false) # =>["gear", "gear=", "gears", "gear_next", "gear_previous", ... t = Tractor.new t.gear # => :neutral t.gear = :reverse # => :reverse t.gear # => :reverse t.gear = :third # => ArgumentError: 'third' is not an enumerated value for gear attribute t.gears # => [:reverse, :neutral, :first, :second, :over_drive] t.gear_next # => :neutral t.gear_previous # => :reverse t.gear_previous # => :over_drive
The plugin has defined gear and gear= accessors for the attribute. They can be used to set the attribute to one of the defined enumeration values. Attempting to set the attribute to something besides a defined enumeration value raises an ArgumentError.
gear_next and gear_previous are incrementors and decrementors of the attribute.
The increment order is based on the order of the enumeration values in the attribute definition. Both the incrementor and decrementor will wrap when reaching the boundary elements of the enumeration array. For example:
t.gear = :second t.gear_next # => :over_drive t.gear_next # => :reverse
Predicate methods are methods that query the state of the attribute, for instance, gear_is_neutral? is a predicate method that returns ‘true’ if the gear attribute is in the :neutral state.
By default, predicate methods are not predefined, instead, they are dynamically generated.
The plugin will evaluate and respond to methods adhering to a format that it can associate with an attribute name and one of the attribute’s enumeration values.
enumerated_attribute recognizes predicate methods of the following format:
{attribute name}_{anything}_{enumeration value}?
The predicate method must satisfy three requirements: it must begin with the name of the attribute, it must end with a question mark, and the question mark must be preceded with a valid enumeration value (all connected by underscores without colons).
So we can write the following two predicate methods without any prior definition and the plugin will recognize, define and respond to them as demonstrated here:
t.gear= :neutral t.gear_is_in_neutral? # => true t.gear_is_in_reverse? # => false
The ‘is_in’ part of the methods above is merely semantic but enhances readability. The contents of the {anything} portion is completely at the discretion of the developer. However, there is one twist.
The evaluation of a predicate method can be negated by including ‘not’ in the the middle {anything} section, such as here:
t.gear_is_not_in_neutral? # => false t.gear_is_not_in_reverse? # => true
Basically, the shortest acceptable form of a predicate method is:
t.gear_neutral? # => true t.gear_not_neutral? # => false
In the case that an enumeration value is associated with only one attribute, the attribute name can be left out of the predicate method name. The plugin will infer the attribute from the enum value in the method name. The abbreviate format can be written like this:
{anything}{_}{enumeration value}?
And results in the following possibilities:
t.gear = :neutral t.neutral? # => true t.is_neutral? # => true t.not_neutral? # => false t.is_not_neutral? # => false
Calling the abbreviated form of the method containing an enumeration value belonging to two or more attributes throws an AmbiguousMethod error.
The plugin provides a few ways to eliminate setting the initial value of the attribute in the initialize method. Two ways are demonstrated here:
class Tractor enum_attr :gear, %w(reverse ^neutral first second third) enum_attr :front_light, %w(off low high), :init=>:off end t = Tractor.new t.gear # => :neutral t.front_light # => :off
Note enumerated_attribute can be abbreviated to enum_attr. The abbreviated form will be used in subsequent examples.
The first and simplest way involves designating the initial value by prepending a carot ‘^’ to one of the enumeration values in the definition.
The plugin recognizes that the gear attribute is to be initialized to :neutral.
Alternatively, the :init option can be used to indicate the initial value of the attribute.
By default, the attribute setter allows nils unless the :nil option is set to false. When :nil is set to false, the attribute may initialize to nil, but may not be set to nil thereafter.
class Tractor enum_attr :plow, %w(up down), :nil=>false end t = Tractor.new t.plow # => nil t.plow_nil? # => true t.plow = :up # => :up t.plow_is_nil? # => false t.plow_is_not_nil? # => true t.plow = nil # => raises error
Regardless of the :nil option setting, the plugin can dynamically recognize and define predicate methods for testing ‘nil’ values. The setter methods also treat empty strings (or ”) as nil values.
The plugin provides options for changing the method names of the enumeration accessor, incrementor and decrementor (ie, gears, gear_next, gear_previous):
class Tractor enum_attr :lights, %w(^off low high), :plural=>:lights_values, :inc=>'lights_inc', :dec=>'lights_dec' end t = Tractor.new t.lights_values # => [:off, :low, :high] t.lights_inc # => :low t.lights_dec # => :off
By default, the plugin uses the plural of the attribute for the accessor method name of the enumeration values. The pluralization uses a simple algorithm which does not support irregular forms. In the case of ‘lights’ as an attribute, the default pluralization does not work, so the accessor can be changed using the :plural option. Likewise, the decrementor and incrementor have options :decrementor and :incrementor, or :inc and :dec, for changing their method names.
In the case that other methods are required to support the attribute, the plugin provides a short-hand for defining these methods in the enumerated_attribute block.
class Tractor enum_attr :gear, %w(reverse ^neutral first second over_drive) do parked? :neutral driving? [:first, :second, :over_drive] end end t = Tractor.new t.parked? # => true t.driving? # => false
Two predicate methods are defined for the ‘gear’ attribute in the above example using the plugin’s short-hand.
The first method, parked?, defines a method which evaluates the code {@gear == :neutral}. The second method, driving?, evaluates to true if the attribute is set to one of the enumeration values defined in the array [:first, :second, :over_drive].
The same short-hand can be used to define methods where the attribute ‘is not’ equal to the indicated value or ‘is not’ included in the array of values.
class Tractor enum_attr :gear, %w(reverse ^neutral first second over_drive) do not_parked? is_not :neutral not_driving? is_not [:first, :second, :over_drive] end end
For predicate methods requiring fancier logic, a block can be used to define the method body.
class Tractor enum_attr :gear, %w(reverse ^neutral first second over_drive) do parked? :neutral driving? [:first, :second, :over_drive] end enum_attr :plow, %w(^up down), :plural=>:plow_values do plowing? { self.gear_is_in_first? && @plow == :down } end end
Here, a method plowing? is true if the gear attribute equates to :first and the plow attribute is set to :down. There is no short-hand for the block. The code must be complete and evaluate in the context of the instance.
Method definitions are not limited to predicate methods. Other methods can be defined to manipulate the attributes. Here, two methods are defined acting as bounded incrementor and decrementor of the gear attribute.
class Tractor enum_attr :gear, %w(reverse ^neutral first second over_drive) do parked? :neutral driving? [:first, :second, :over_drive] upshift { self.gear_is_in_over_drive? ? self.gear : self.gear_next } downshift { self.driving? ? self.gear_previous : self.gear } end end t = Tractor.new t.gear # => :neutral 10.times { t.upshift } t.gear # => :over_drive 10.times { t.downshift } t.gear # => :neutral
Methods upshift and downshift use the automatically generated incrementor and decrementor as well as a couple predicate methods. upshift increments the gear attribute until it reaches over_drive and does not allow a wrap around. downshift decrements until the attribute reaches neutral.
The plugin can be used with ActiveRecord. Enumerated attributes may be declared on column attributes or as independent enumerations. Declaring an enumerated attribute on a column attribute will enforce the enumeration using symbols. The enumerated column attribute must be declared as a STRING in the database schema.
The enumerated attribute will be stored as a string but retrieved in code as a symbol. The enumeration functionality is consistent across integrations.
require 'enumerated_attribute' require 'active_record'
class Order < ActiveRecord::Base enum_attr :status, %w(^hold, processing, delayed, shipped) enum_attr :billing_status, %w(^unauthorized, authorized, auth_failed, captured, capture_failed, closed) end
o = Order.new o.status # => :hold o.billing_status # => :unauthorized o.save!
o = Order.new(:invoice=>'43556334-W84', :status=>:processing, :billing=>:authorized) o.save! o.status # => :processing o.invoice # => "43556334-W84"
Each enumeration value has a corresponding text label. The defaults are made up from the enumeration symbols. For the Tractor class example:
t=Tractor.new t.enums(:gear) # => [:reverse, :neutral, :first, :second, :over_drive] t.enums(:gear).labels # => ['Reverse', 'Neutral', 'First', 'Second', 'Over drive']
The +enums(:attribute)+ method provides information about the attribute’s enumerations. It is the same as the plural form of the attribute name. There are several kinds of information available from the enums method.
t=Tractor.new e = t.enums(:plow) # => [:up, :down] e.labels # => ['Up', 'Down'] e.hash # => {:up=>'Up', :down=>'Down'} e.select_options # => [['Up', 'up'], ['Down', 'down']] e.label(:up) # => 'Up'
Labels can be customized as shown here:
class User < ActiveRecord::Base enum_attr :contact_options, %w(none phone email mail) do label :none=>'Please do not contact me' label :phone=>'I would like a representative to call me' label :email=>'I would like information via email' label :mail=>'I would like information mailed to me' end end
Likewise, the labels can be provided on the same line
class Tractor enum_attr :gear, %w(reverse ^neutral first second over_drive) do labels :first=>'1st Gear', :second=>'2nd Gear', :over_drive=>'Over Drive' end end
There are two enum_select helpers, one for use with form_for and one for use without it. An example for form_for was given in the examples at the beginning. Here’s an example with the form_tag and a @user object.
<% form_tag :action=>:register do %> <%= label_tag 'First name' %>: <%= text_field :user, :first_name %><br/> <%= label_tag 'Gender' %>: <%= enum_select :user, :gender %><br/> <%= label_tag 'Degree' %>: <%= enum_select :user, :degree %><br/> ... <%= submit_tag 'Register' %> <% end %>
You can generate views with enumerations using your favorite scaffold generator. Currently supports most scaffold generators including scaffold, wizardly_scaffold, nifty_scaffold, rspec_scaffold and haml_scaffold. For most scaffolds there are two steps. First, generate the scaffold views and migrations using the ‘enum’ type for enumerations
./script/generate scaffold contractor name:string gender:enum age:integer status:enum
Second, do not forget to add the enum_attr macro to the generated model and migrate the database
class Contractor < ActiveRecord::Base enum_attr :gender, %w(male female) enum_attr :status, %w(available unavailable) end
You can display the select input in a Formtastic form with a little monkey patching. First, extend Formtastic with an initializer:
require 'formtastic' module Formtastic #:nodoc: module Inputs #:nodoc: class EnumInput < SelectInput #:nodoc: def to_html unless options[:collection] enum = @object.enums(method.to_sym) choices = enum ? enum.select_options : [] options[:collection] = choices end if (value = @object.__send__(method.to_sym)) options[:selected] ||= value.to_s else options[:include_blank] ||= true end super end end end end
Then specify the input type as enum in the forms:
form.input :gear, :as => :enum
The plugin chains both the ‘new’ and the ‘method_missing’ methods. Any ‘new’ and ‘method_missing’ implementations in the same class declaring an enumerated_attribute should come before the declaration; otherwise, the ‘new’ and ‘method_missing’ implementations must chain in order to avoid overwriting the plugin’s methods. The best approach is shown here:
class Soup
def self.new(*args)
...
end
private
def method_missing(methId, *args, &blk)
...
end
enum_attr temp:, %w(cold warm hot boiling) end
ActiveRecord’s write_attribute and read_attribute methods do not support symbols for enumerated attributes.
The plugin uses jeweler, RSpec, and Webrat for testing. Make sure you have these gems installed:
gem install rspec webrat jeweler
To test the plugin for regular ruby objects, run:
rake spec:object
Testing ActiveRecord integration requires the install of Sqlite3 and the sqlite3-ruby gem. To test ActiveRecord, run:
rake spec:ar
And for testing enum_select in form views:
rake spec:forms
To test all specs:
rake spec:all
-
ActiveRecord (but not required)
-
Sqlite3 and sqlite3-ruby gem (for testing)