belongs_to_one_of

Gem to support activemodel relations where one model can be a child of one of many models. In our examples, we will be targeting a class Competitor which can either belong to a School or a College. We will consider this more general concept an organisation.

The gem provides a simple method to declare this relationship, some validators to enforce the relationships, and some helper functions to safely set and get the associated model.

Unlike rails polymorphic relations, this supports having a separate id column for each parent model type (e.g. school_id and college_id instead of just organisation_id). This is desirable (in some cases) to enable the database to use foreign keys.

The gem will also error if you try to set a resource which isn't one of the specified classes, unlike a rails polymorphic relation which will accept any model class.

Install the package from Rubygems:

gem install belongs_to_one_of

Or add it to your gemfile

gem 'belongs_to_one_of'

For our policy on compatibility with Ruby versions, see COMPATIBILITY.md.

Our code will say:

This model belongs to an organisation, which might be a School or might be a College

This allows us to store the association in the columns school_id and college_id, which can use foreign keys, but for the 99% of your code which doesn't care which is which, they can just call a method organisation or organisation_id to access the resource.

The library adds a new association to ActiveRecord called belongs_to_one_of :organisation, . To use it, simply call this hook in your ActiveRecord class:

class Competitor < ActiveRecord::Base
  belongs_to_one_of :organisation, %i[school college]
end

class School < ActiveRecord::Base
  has_many :competitors
end 

class College < ActiveRecord::Base
  has_many :competitors
end 

school = School.new

my_competitor = Competitor.create(name: 'jack', organisation: school)

my_competitor.organisation
# => school

my_competitor.organisation_id == school.id
# => true 

Note that this helper calls belongs_to :school, optional:true and belongs_to :college, optional:true, so you don't have to.

The hook defines a few methods on your class. The names are dynamic, we will use 'organisation' as our example (as per above):

A validator that can be used to check that a model belongs to exactly one organisation

A validator that can be used to check that a model belongs to either no organisations or one organisation

A validator that can be used to check that the type of model matches the model. Only relevant when include_type_column is true

Allows you to create a new instance of the model with the interface:

Competitor.new(
  organisation: my_school,
  name: "Joe Bloggs"
)

This will raise a ModelNotFound exception if the organisation is not one of the permitted model types

Allows you to get the linked resource via .organisation e.g.:

my_competitor.organisation

Allows you to get the linked resource's id via .organisation_id e.g.:

my_competitor.organisation_id

This is only set when the associations are configured with include_type_column (see below). This allows you to access the resource type via .organisation_type e.g.:

my_competitor.organisation_type
# => 'School'

By default, the library assumes that the underlying table looks like:

however you can set include_type_column: true to explicitly store what type of model is connected, e.g.:

  belongs_to_one_of :organisation, %i[school college], include_type_column: true

if the column is not called [organisation]_type, you can specify the column name e.g.

  belongs_to_one_of :organisation, %i[school college], include_type_column: :type_of_organisation

If you have include_type_column: true set, by default we assume you want to store the classname in the db. However, there may be some logic that you want to apply. If you pass a Proc to type_column_value you can add your own logic to determine what goes into the db.

  belongs_to_one_of :organisation,  %i[school college], include_type_column: true,
                                                       type_column_value: ->(resource) { resource.class.downcase }

• BelongsToOneOf is available as open source under the terms of the MIT License.
• Bug reports and pull requests are welcome on GitHub at https://github.com/gocardless/belongs-to-one-of.

GoCardless ♥ open source. If you do too, come join us.