= vidibus-inheritance

This gem is part of the open source SOA framework Vidibus: http://www.vidibus.org

It allows inheritance of objects and is depends on Rails 3 and Mongoid. It will update all attributes and embedded documents of inheritors when ancestor gets changed. Custom attributes (mutations) of inheritors will not be overridden, unless a :reset option is set.


== Installation

Add the dependency to the Gemfile of your application:

  gem "vidibus-inheritance"

Then call bundle install on your console.


== Usage

Include the Vidibus::Uuid::Inheritance module in your Mongoid model:

  class Model
    include Mongoid::Document
    include Vidibus::Uuid::Mongoid
    include Vidibus::Inheritance::Mongoid
    field :name
  end
  
To establish an inheritance relationship, add ancestor to a model of same class:
  
  ancestor = Model.create(:name => "Anna")
  
  # To establish a relation, call #inherit_from!
  inheritor = Model.new
  inheritor.inherit_from!(ancestor)
  
  # ...or set :ancestor attribute
  inheritor = Model.create(:ancestor => ancestor)


=== Mongoid configuration

When inheriting, the attribute :_reference_id will be set on embedded documents of inherited objects. So make sure this field is available or Mongoid is configured to allow dynamic fields. Add to config/mongoid.yml:

  allow_dynamic_fields: true


=== Acquired attributes

All attributes will be inherited, except these ACQUIRED_ATTRIBUTES:

  _id
  _type
  uuid
  ancestor_uuid
  mutated_attributes
  mutated
  created_at
  updated_at
  version
  versions
  
You may overwrite acquired attributes by defining a method on your inherited document and its embedded documents:

  def acquired_attributes
    Vidibus::Inheritance::Mongoid::ACQUIRED_ATTRIBUTES + %w[my custom values]
  end


=== Manage mutations of embedded documents

All custom changes on inherited objects will be stored in #mutated_attributes. On embedded documents of inherited objects, however, mutations of attributes will not be tracked. But you may flag a document as mutated when applying custom values:

  class Job
    include Mongoid::Document
    field :salary
    field :mutated, :type => Boolean
    embedded_in :model, :inverse_of => :jobs
  
    def set_custom_salary(amount)
      self.salary = amount
      self.mutated = true
    end
  end

To control how inherited data will be updated, you may define a callback method and check #mutated:

  def update_inherited_attributes(attrs)
    attrs.delete("salary") if mutated? # preserve custom salary
    update_attributes(attrs)
  end


== Copyright

Copyright (c) 2010 Andre Pankratz. See LICENSE for details.


== Thank you!

The development of this gem was sponsored by Käuferportal: http://www.kaeuferportal.de