Easily verify ownership of a model
Ruby
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
README.markdown
Rakefile
ownable.gemspec

README.markdown

INTRODUCTION

Ownable gem helps you verify the "ownership" of a associated models in Rails 3.

The term "ownership" in the contact of Ownable is the association between two models, usually a User Model (though any model can do) and some other Model.

Ownable exposes an instance method on ActiveRecord objects that declare themselves to be acts_as_ownable:

owned_by? (and its alias belongs_to?)

For example, assume the associations:

User has_many Orders has_one Invoice has_many Payments

or in the opposite direction:

Payments belongs_to Invoice belongs_to Orders belongs_to User

Determine if a User "owns" a particular Payment object

Rather than manually defining and then checking the association between User and Payment like:
	@payment.invoice.order.user == current_user # => true/false
	
you can use Ownable for a much shorter and simpler syntax:
   @payment.owned_by? current_user # => true/false

This gem is most helpful when many association steps exist between Models, such as:

A belongs_to B belongs_to ... belongs_to Y belongs_to Z

And the ownership check can be written short hand via Ownable as:

@a.owned_by? @z # => true/false

or

@a.belongs_to? @z # => true/false

INSTALLATION

Ownable is currently available only in Gem form and requires version >= 3.0 of Rails.

You just have to add the 'ownable' gem to your Gemfile

gem 'ownable'

Then tell bundler to update the gems :

$ bundle install

USE

In each Model define the associations from the Model to the "Owner" model (which will be User in this example)

Assuming a set of Model associations as follows:

User has_many Orders has_one Invoice has_many Payments

Ownable is added to the Payment Model using "acts_as_ownable"

class Payment < ActiveRecord::Base  
  acts_as_ownable :through => [:invoice, :order, :user]
	...
end

The "acts_as_ownable" method call takes a hash with key :through with an Array value. The Array is a list of the Model names that define the association path from the current Model back to, and including the "Owner" model. Important note: The last item in the array is always the "Owner" model name.

Now all Payment objects will have the instance methods:

@payment.owned_by?(ActiveRecord Object)
@payment.owned_by?(Fixnum Id)

or using the belongs_to? alias

@payment.belongs_to?(ActiveRecord Object)
@payment.belongs_to?(Fixnum Id)

Note that when declaring acts_as_ownable in the Models, the last Model name in the array must be the "Owner" model name. Also, this only works when each upstream association returns a single object. For example, the following will NOT work:

Publisher has_many Authors has_and_belongs_to_many Books 


class Book < ActiveRecord::Base  
  acts_as_ownable :through => [:author, :publisher]
	...
end


@book.owned_by? Publisher.first

This will not work because several authors may have co-authored a Book so there is multiple paths back to the "Owner" model (the Publisher). At this time this gem does not support these relationships.

THANKS

Thanks to jlecour's (http://github.com/jlecour) geokit-rails project for helping me understand how to build a gem that plays well with Rails 3.