Poppy Rails

A simple and flexible enumeration implementation for ActiveRecord using poppy.

Description

Inspired by enumerate_it, Poppy is a simple implementation of enumerations with minimal goodies. Poppy offers a few nice features:

• Enumeration values are objects and can respond to any defined methods
• Works with postreSQL arrays with validations
• Simple

Installation

Add this line to your application's Gemfile:

gem 'poppy-rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install poppy-rails

optional

Add an initializer that calls

ActiveRecord::Base.include(Poppy::ActiveRecord)

this can be omitted by manually including the adapter in each model that uses Poppy

class Sandwhich < ActiveRecord::Base
  include Poppy::ActiveRecord

  enumeration :bread, of: Bread
  #...
end

Usage

Enumeration

#app/enumerations/bread.rb
class Bread < Poppy::Enum
  values :white, :multigrain, :gluten_free
end

Model

class Sandwhich < ActiveRecord::Base
  enumeration :bread, of: Bread
end

Adding an enumeration to an active_record model will add an inclusion validation. There is no support for nullable enumerations. This is an intended design decision. If you would like this functionality you will need to add a null value E.g. Bread::None

Migrations

Just regular rails migrations, however the because enumerations are objects we can't just persist the enumeration value directly. We need to convert it to the appropriate database value using the EnumType class

> Poppy::ActiveRecord::EnumType.new(enum: Bread).type_cast_for_database(Bread::WHITE)
=> :white

As you can see this code is rather verbose and its pretty obvious what its returning, we can just pass in the symbol associated with the enum value. (This works because there is currently only one way to persist enumerations, as a string. If integer based enumerations are implemented then the more verbose option is required).

class AddJobKindsToJob < ActiveRecord::Migration
  def change
    add_column :sandwhiches, :bread, :string, default: :white
  end
end

Database persistence has been designed to use string based persistence. This gives two main advantages.

1. Its clear what value is used when looking at the database row directly.
2. Integer based enumerations require explicitly setting an integer value, which has no relation to the data itself. Integers can be implicitly assigned to an enumeration but this breaks once an enumeration is deleted or the order that they are defined is changed.

In the wild

> sandwhich = Sandwhich.new(bread: Bread::WHITE, cheeses: [Cheese::CHEDDAR])
> sandwhich.bread
=> Bread::WHITE

HTML forms

Rails form helpers

<%= simple_form_for @bread do |f| %>
  <%= f.select :bread, Bread.collection %>
<% end %>

SimpleForm

<%= simple_form_for @sandwhich do |f| %>
  <%= f.input :bread, collection: Bread.collection %>
<% end %>

Postgres Array Support

#app/enuerations/cheese.rb
class Cheese < Poppy::Enum
  values :cheddar, :swiss, :mozzarella
end

class Sandwhich < ActiveRecord::Base
  enumeration :cheeses, as: :array, of: Cheese
end

If the enumeration is an array then all values in the array must be of that enumeration. If they aren't validation will fail just like any other ActiveModel validation.

class AddJobKindsToJob < ActiveRecord::Migration
  def change
    add_column :sandwhiches, :cheeses, :string, array: true, default: []
  end
end

> sandwhich = Sandwhich.new(cheeses: [Cheese::CHEDDAR])

> sandwhich.cheeses
=> [Cheese::CHEDDAR]

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Specs depend rely on a postgres database running to test the array support.

$ createdb poppy_rails_test

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/damienadermann/poppy-rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

##TODO

• Add AR initializer
• Add docs