CanBe allows you to track the type of your ActiveRecord model in a consistent simple manner. With just a little configuration on your part, each type of record can contain different attributes that are specific to that type of record. From a data modeling perspective this is preferred over ActiveRecord STI since you will not have many columns in your database that have null values. Under the hood, CanBe uses one-to-one Polymorphic Associations to accomplish the different attributes per type.
Here is a blog post that will describe more of the rationale behind the CanBe gem: http://blog.markstarkman.com/blog/2013/01/09/writing-my-first-rubygem-canbe/
I will be following Semantic Versioning as closely as possible. The
master branch will be the latest development version and may not match the version of the code you are using. There is a git tag for each released version. The CHANGELOG.md will contain the correct links to each version.
Add this line to your application's Gemfile:
If you feel like living on the edge, you can add this to your applications' Gemfile:
gem 'can_be', git: "git://github.com/mstarkman/can_be.git"
And then execute:
The documentation for the basic implementation of CanBe can be found in this readme. Here is the documentation for the other features.
- Different Attributes per CanBe Type (details)
- Keeping Details History When Changing CanBe Types
- Custom RSpec Matchers
Database Configuration (via migrations)
In its simplest form, you only need to add a string attribute (column) to the model can be different types. By default, this attribute must be named
can_be_type. However, you can have the attribute be named anything that you would like, you just need to tell CanBe what it is. Indexing this column is your choice.
class AddCanBeTypeToAddresses < ActiveRecord::Migration def change add_column :addresses, :can_be_type, :string add_index :addresses, :can_be_type end end
NOTE: Examples of the database migrations can be found in the
To add CanBe to your model, you simply need to call the
on your model.
class Address < ActiveRecord::Base can_be :home_address, :work_address, :vacation_address end
can_be method will take in a list of valid types that will be used by CanBe. There is an optional last parameter that is a hash of the options. This is a list of valid options.
:default_type- Sets the default value for when a new record is instantiated or created (it is the first value in the list by default)
:field_name- Sets the ActiveRecord field name that is to be used (if not specified, CanBe expects a
can_be_typeattribute to be present)
Here is an example of the options.
class Person < ActiveRecord::Base can_be :male, :female, field_name: :gender, default_type: :female end
Or you can set the options in a block when calling
class Person < ActiveRecord::Base can_be :male, :female do field_name :gender default_type :female end end
NOTE: Examples of the model configurations can be found in the
The CanBe gem will provide you a lot methods to handle your type processing in an easy and consistent manner.
Instantiating New Models
You can continue to instantiate your CanBe models by using the
new method. When you do, CanBe will ensure that the type of the record is assigned the default CanBe type for your model.
There are also some helper methods put on your model to make it easier to instantiate the type of model that you want. These methods will take the form of
new_<CanBe type>. For example, you can call
Address.new_home_address. These methods will take the same parameters as the base
new method provided by ActiveRecord.
Creating New Models
You can continue to create your CanBe models by using the
create method. When you do, CanBe will ensure that the type of the record is assigned the default CanBe type for your model.
There are also some helper methods put on your model to make it easier to create the type of model that you want. These methods will take the form of
create_<CanBe type>. For example, you can call
Address.create_home_address. These methods will take the same parameters as the base
create method provided by ActiveRecord.
Changing CanBe Types (the "change_to" methods)
There are several ways to change the type of record that you are working with. You can access the
can_be_type attribute (or other attribute if you specified the field to be used) and change the value directly.
There are also instance methods provided on your model that allow for changing to a specific CanBe type.
You can change the type of record and not persist it immediately to the database by calling the appropriate
change_to_<CanBe type> method. For example, you can call
Address.new.change_to_work_address method to change the record to be of CanBe type
If you want to change the type of the record and persist it to the database immediately, you can call the appropriate
change_to_<CanBe type>! method. For example, this method call will change the type of record to
:work_address and persist the change to the database:
There is a validator for the CanBe field, that will ensure that the CanBe field is set to one of the CanBe types before persisting the record.
With CanBe, it is easy to determine the type of record that you are working with. This is accomplished by calling the
<CanBe type>? on the instance of your model. For example if you wanted to see if the
Address instance you are working with, you would call
Address.first.home_address? and it would return
false depending on the CanBe type of the record.
There are two ways to find specific types of records. You can use the
find_by_can_be_types method, which takes in a list of the CanBe types that you want to find. For example, if you wanted to find all of the home and work addresses you would call
Address.find_by_can_be_types :home_address, :work_address.
Methods are also defined on your CanBe model that will find all of the records for a specific CanBe type. These methods take the form of
<pluralized CanBe type>. For example,
Address.home_addresses would return all of the records with a type of
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Make sure to include the appropriate specs
- Specs can be run by executing the
rakecommand in the terminal
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request