Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/brainspec/enumerize

Enumerated attributes with I18n and ActiveRecord/Mongoid support
https://github.com/brainspec/enumerize

activerecord mongoid ruby

Last synced: about 2 months ago
JSON representation

Enumerated attributes with I18n and ActiveRecord/Mongoid support

Awesome Lists containing this project

README 

        
# Enumerize [![Ruby](https://github.com/brainspec/enumerize/actions/workflows/ruby.yml/badge.svg)](https://github.com/brainspec/enumerize/actions/workflows/ruby.yml)



Enumerated attributes with I18n and ActiveRecord/Mongoid/MongoMapper/Sequel support



## Table of Contents



- [Installation](#installation)

- [Supported Versions](#supported-versions)

- [Usage](#usage)

- [Database support](#database-support)

  - [ActiveRecord](#activerecord)

  - [Mongoid](#mongoid)

  - [MongoMapper](#mongomapper)

- [I18n Support](#i18n-support)

  - [I18n Helper Methods](#i18n-helper-methods)

- [Boolean Helper Methods](#boolean-helper-methods)

  - [Basic](#basic)

  - [Predicate Methods](#predicate-methods)

- [Optimzations and Tips](#optimzations-and-tips)

  - [Extendable Module](#extendable-module)

  - [Customizing Enumerize Value](#customizing-enumerize-value)

  - [ActiveRecord scopes](#activerecord-scopes)

  - [Array-like Attributes](#array-like-attributes)

- [Forms](#forms)

  - [SimpleForm](#simpleform)

  - [Formtastic](#formtastic)

- [Testing](#testing)

  - [RSpec](#rspec)

  - [Minitest with Shoulda](#minitest-with-shoulda)

  - [Other Integrations](#other-integrations)

- [Contributing](#contributing)



## Installation



Add this line to your application's Gemfile:



    gem 'enumerize'



And then execute:



    $ bundle



Or install it yourself as:



    $ gem install enumerize



## Supported Versions



- Ruby 3.0+

- Rails 6.1+



## Usage



Basic:



```ruby

class User

  extend Enumerize



  enumerize :role, in: [:user, :admin]

end

```



Note that enumerized values are just identifiers so if you want to use multi-word, etc. values then you should use `I18n` feature.



---



## Database support



### ActiveRecord



```ruby

class CreateUsers < ActiveRecord::Migration

  def change

    create_table :users do |t|

      t.string :status

      t.string :role



      t.timestamps

    end

  end

end



class User < ActiveRecord::Base

  extend Enumerize



  enumerize :status, in: [:student, :employed, :retired], default: lambda { |user| StatusIdentifier.status_for_age(user.age).to_sym }



  enumerize :role, in: [:user, :admin], default: :user

end

```



:warning: By default, `enumerize` adds `inclusion` validation to the model. You can skip validations by passing `skip_validations` option. :warning:



```ruby

class User < ActiveRecord::Base

  extend Enumerize



  enumerize :status, in: [:student, :employed, :retired], skip_validations: lambda { |user| user.new_record? }



  enumerize :role, in: [:user, :admin], skip_validations: true

end

```



### Mongoid



```ruby

class User

  include Mongoid::Document

  extend Enumerize



  field :role

  enumerize :role, in: [:user, :admin], default: :user

end

```



### MongoMapper



```ruby

class User

  include MongoMapper::Document

  extend Enumerize



  key :role

  enumerize :role, in: [:user, :admin], default: :user

end

```



---



## I18n Support



```ruby

en:

  enumerize:

    user:

      status:

        student: "Student"

        employed: "Employed"

        retired: "Retiree"

```



or if you use `status` attribute across several models you can use `defaults` scope:



```ruby

en:

  enumerize:

    defaults:

      status:

        student: "Student"

        employed: "Employed"

        retired: "Retiree"

```



You can also pass `i18n_scope` option to specify scope (or array of scopes) storing the translations.



```ruby

class Person

  extend Enumerize

  extend ActiveModel::Naming



  enumerize :status, in: %w[student employed retired], i18n_scope: "status"

  enumerize :roles, in: %w[user admin], i18n_scope: ["user.roles", "roles"]

  enumerize :color, in: %w[green blue], i18n_scope: proc { |value| "color" }

end



# localization file

en:

  status:

    student: "Student"

    employed: "Employed"

    retired: "Retiree"

  user:

    roles:

      user: "User"

  roles:

    admin: "Admin"

```



Note that if you want to use I18n feature with plain Ruby object don't forget to extend it with `ActiveModel::Naming`:



```ruby

class User

  extend Enumerize

  extend ActiveModel::Naming

end

```



### I18n Helper Methods



#### \*\_text / .text



Attribute's I18n text value:



```ruby

@user.status_text # or @user.status.text

```



#### values



List of possible values for an enumerized attribute:



```ruby

User.status.values # or User.enumerized_attributes[:status].values

# => ['student', 'employed', 'retired']

```



#### I18n text values



List of possible I18n text values for an enumerized attribute:



```ruby

User.status.values.collect(&:text)

# => ['Student', 'Employed', 'Retiree']

```



#### Form example



Use it with forms (it supports `:only` and `:except` options):



```erb

<%= form_for @user do |f| %>

  <%= f.select :status, User.status.options %>

<% end %>

```



---



## Boolean Helper Methods



### Basic



```ruby

user.status = :student

user.status.student? #=> true

user.status.retired? #=> false

```



### Predicate Methods



```ruby

class User

  extend Enumerize



  enumerize :status, in: %w(student employed retired), predicates: true

end



user = User.new



user.student?  # => false

user.employed? # => false



user.status = :student



user.student?  # => true

user.employed? # => false

```



:warning: If `enumerize` is used with Mongoid, it's not recommended to use `"writer"` as a field value since `writer?` is defined by Mongoid. [See more](https://github.com/brainspec/enumerize/issues/235). :warning:



#### Predicate Prefixes



```ruby

class User

  extend Enumerize



  enumerize :status, in: %w(student employed retired), predicates: { prefix: true }

end



user = User.new

user.status = 'student'

user.status_student? # => true

```



Use `:only` and `:except` options to specify what values create predicate methods for.



---



## Optimzations and Tips



### Extendable Module



To make some attributes shared across different classes it's possible to define them in a separate module and then include it into classes:



```ruby

module RoleEnumerations

  extend Enumerize



  enumerize :roles, in: %w[user admin]

end



class Buyer

  include RoleEnumerations

end



class Seller

  include RoleEnumerations

end

```



### Customizing Enumerize Value



It's also possible to store enumerized attribute value using custom values (e.g. integers). You can pass a hash as `:in` option to achieve this:



```ruby

class User < ActiveRecord::Base

  extend Enumerize



  enumerize :role, in: { user: 1, admin: 2 }

end



user = User.new

user.role = :user

user.role #=> 'user'

user.role_value #=> 1



User.role.find_value(:user).value #=> 1

User.role.find_value(:admin).value #=> 2

```



### ActiveRecord scopes:



#### Basic



```ruby

class User < ActiveRecord::Base

  extend Enumerize

  enumerize :role, in: [:user, :admin], scope: true

  enumerize :status, in: { student: 1, employed: 2, retired: 3 }, scope: :having_status

end



User.with_role(:admin)

# SELECT "users".* FROM "users" WHERE "users"."role" IN ('admin')



User.without_role(:admin)

# SELECT "users".* FROM "users" WHERE "users"."role" NOT IN ('admin')



User.having_status(:employed).with_role(:user, :admin)

# SELECT "users".* FROM "users" WHERE "users"."status" IN (2) AND "users"."role" IN ('user', 'admin')

```



#### Shallow Scopes



Adds named scopes to the class directly.



```ruby

class User < ActiveRecord::Base

  extend Enumerize

  enumerize :status, in: [:student, :employed, :retired], scope: :shallow

  enumerize :role, in: { user: 1, admin: 2 }, scope: :shallow

end



User.student

# SELECT "users".* FROM "users" WHERE "users"."status" = 'student'



User.admin

# SELECT "users".* FROM "users" WHERE "users"."role" = 2

```



:warning: It is not possible to define a scope when using the `:multiple` option. :warning:



### Array-like Attributes



Array-like attributes with plain ruby objects:



```ruby

class User

  extend Enumerize



  enumerize :interests, in: [:music, :sports], multiple: true

end



user = User.new

user.interests << :music

user.interests << :sports

```



and with ActiveRecord:



```ruby

class User < ActiveRecord::Base

  extend Enumerize



  serialize :interests, Array

  enumerize :interests, in: [:music, :sports], multiple: true

end

```



get an array of all text values:



```ruby

@user.interests.texts # shortcut for @user.interests.map(&:text)

```



Also, the reader method can be overridden, referencing the enumerized attribute value using `super`:



```ruby

def status

  if current_user.admin?

    "Super #{super}"

  else

    super

  end

end

```



---



## Forms



### SimpleForm



If you are using SimpleForm gem you don't need to specify input type (`:select` by default) and collection:



```erb

<%= simple_form_for @user do |f| %>

  <%= f.input :status %>

<% end %>

```



and if you want it as radio buttons:



```erb

<%= simple_form_for @user do |f| %>

  <%= f.input :status, as: :radio_buttons %>

<% end %>

```



Please note that Enumerize overwrites the I18n keys of SimpleForm collections. The enumerized keys are used instead of the SimpleForm ones for inputs concerning enumerized attributes. If you don't want this just pass `:collection` option to the `input` call.



### Formtastic



If you are using Formtastic gem you also don't need to specify input type (`:select` by default) and collection:



```erb

<%= semantic_form_for @user do |f| %>

  <%= f.input :status %>

<% end %>

```



and if you want it as radio buttons:



```erb

<%= semantic_form_for @user do |f| %>

  <%= f.input :status, as: :radio %>

<% end %>

```



---



## Testing



### RSpec



Also you can use builtin RSpec matcher:



```ruby

class User

  extend Enumerize



  enumerize :status, in: [:student, :employed, :retired]

end



describe User do

  it { should enumerize(:status) }



  # or with RSpec 3 expect syntax

  it { is_expected.to enumerize(:status) }

end

```



#### Qualifiers



##### in



Use `in` to test usage of the `:in` option.



```ruby

class User

  extend Enumerize



  enumerize :status, in: [:student, :employed, :retired]

end



describe User do

  it { should enumerize(:status).in(:student, :employed, :retired) }

end

```



You can test enumerized attribute value using custom values with the `in`

qualifier.



```ruby

class User

  extend Enumerize



  enumerize :role, in: { user: 0, admin: 1 }

end



describe User do

  it { should enumerize(:role).in(user: 0, admin: 1) }

end

```



##### with_default



Use `with_default` to test usage of the `:default` option.



```ruby

class User

  extend Enumerize



  enumerize :role, in: [:user, :admin], default: :user

end



describe User do

  it { should enumerize(:user).in(:user, :admin).with_default(:user) }

end

```



##### with_i18n_scope



Use `with_i18n_scope` to test usage of the `:i18n_scope` option.



```ruby

class User

  extend Enumerize



  enumerize :status, in: [:student, :employed, :retired], i18n_scope: 'status'

end



describe User do

  it { should enumerize(:status).in(:student, :employed, :retired).with_i18n_scope('status') }

end

```



##### with_predicates



Use `with_predicates` to test usage of the `:predicates` option.



```ruby

class User

  extend Enumerize



  enumerize :status, in: [:student, :employed, :retired], predicates: true

end



describe User do

  it { should enumerize(:status).in(:student, :employed, :retired).with_predicates(true) }

end

```



You can text prefixed predicates with the `with_predicates` qualifiers.



```ruby

class User

  extend Enumerize



  enumerize :status, in: [:student, :employed, :retired], predicates: { prefix: true }

end



describe User do

  it { should enumerize(:status).in(:student, :employed, :retired).with_predicates(prefix: true) }

end

```



##### with_scope



Use `with_scope` to test usage of the `:scope` option.



```ruby

class User

  extend Enumerize



  enumerize :status, in: [:student, :employed, :retired], scope: true

end



describe User do

  it { should enumerize(:status).in(:student, :employed, :retired).with_scope(true) }

end

```



You can test a custom scope with the `with_scope` qualifiers.



```ruby

class User

  extend Enumerize



  enumerize :status, in: [:student, :employed], scope: :employable

end



describe User do

  it { should enumerize(:status).in(:student, :employed, :retired).with_scope(scope: :employable) }

end

```



##### with_multiple



Use `with_multiple` to test usage of the `:multiple` option.



```ruby

class User

  extend Enumerize



  enumerize :status, in: [:student, :employed, :retired], multiple: true

end



describe User do

  it { should enumerize(:status).in(:student, :employed, :retired).with_multiple(true) }

end

```



### Minitest with Shoulda



You can use the RSpec matcher with shoulda in your tests by adding two lines in your `test_helper.rb` inside `class ActiveSupport::TestCase` definition:



```ruby

class ActiveSupport::TestCase

  ActiveRecord::Migration.check_pending!



  require 'enumerize/integrations/rspec'

  extend Enumerize::Integrations::RSpec



  ...

end

```



### Other Integrations



Enumerize integrates with the following automatically:



- [RailsAdmin](https://github.com/sferik/rails_admin/)



---



## Contributing



1. Fork it

2. Create your feature branch (`git checkout -b my-new-feature`)

3. Commit your changes (`git commit -am 'Added some feature'`)

4. Push to the branch (`git push origin my-new-feature`)

5. Create new Pull Request