cti 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NjIzZTIxNmE3NDVkYzRhMjI4ZGRlYWZkYThkYTMyYmJlZmY5YTZkZQ==
+  data.tar.gz: !binary |-
+    ZDlkMzEwYTA5NGI5MjVmNDZkOTEyZDA1Y2IxNmE5MTUzNmMzMjY4ZA==
+SHA512:
+  metadata.gz: !binary |-
+    YWY4MWFmYjE0NTc5YWJkYTJjNDk0MmI4NWZiNjRkOGQyYWY0MzU4YmQ0OWQ4
+    NjEwYWIwOGQ5ZTIzOGIzYWZmMWEwZjAxMDEzY2E4ZThhZDkzZjQ1NjBjMzlk
+    NTJlMzVlZmFiYTA2NTYwM2FkMTI1NDI3NmU2MmJjZGRjMjliYTI=
+  data.tar.gz: !binary |-
+    YTgzOGJkOTUwMTAzZjFiOGEyYzBmZTNlM2VjOWNmNzI4Zjg1YTUyZDZlOWRi
+    NGZlZmM0NTcwZTliNWU5MGJlNWYyMTFhMTVkZWJiMzlhYjlmYjQyMWVlMjNk
+    MGI5ZTgzYzEwYjZlNDA4N2VlZjM3MWY2NTVkMWM3NjI5OWRjYTE=

data/README.textile

@@ -0,0 +1,235 @@
+h1. CTI
+
+CTI is a gem that implements Multiple Table Inheritance for ActiveRecord models.
+
+h2. Compatability
+
+CTI has only been tested with Rails 4
+
+h2. Installation
+
+Simply add CTI to your Gemfile and bundle it up:
+
+<pre>
+  gem 'cti'
+</pre>
+
+h2. Usage
+
+CTI works by assigning one model as your @predecessor@, and one or more other models as it's @heir@.
+The predecessor is the parent of it's heirs, and thereby implicitly gives it's heirs access to it's columns, and optionally exposing methods to them.
+
+To mark a model as predecessor, simply use the @acts_as_predecessor@ class-method:
+
+<pre>
+  class Post < ActiveRecord::Base
+    acts_as_predecessor
+  end
+</pre>
+
+To mark a model as heir, simply use the @acts_as_heir_of@ class-method, passing a symbol to the model that is to be the heirs predecessor.
+
+<pre>
+  class BlogPost < ActiveRecord::Base
+    acts_as_heir_of :post
+  end
+</pre>
+
+This takes care of the model configuration. We however need to add two extra columns to the Posts table.
+We need a @heir_id@ column of type @integer@ and a @heir_type@ column of type @string@.
+
+<pre>
+  class CreatePosts < ActiveRecord::Migration
+    def self.up
+      create_table :posts do |t|
+        t.integer :heir_id
+        t.string :heir_type
+        t.string :title
+        t.timestamps
+      end
+    end
+
+    def self.down
+      drop_table :posts
+    end
+  end
+  
+  class CreateBlogPosts < ActiveRecord::Migration
+    def self.up
+      create_table :blog_posts do |t|
+        t.text :body
+      end
+    end
+
+    def self.down
+      drop_table :blog_posts
+    end
+  end
+</pre>
+  
+When this is done and the database is migrated, we can begin using the models.
+
+h2. Creating new instances
+
+Now we can simply call the following to create a new @BlogPost@
+
+<pre>
+  blog_post = BlogPost.create(:title => "Wow", :body => "That's a nice blog post!")
+</pre>
+
+Notice that the @title@ attribute belongs to the @Post@ model, and the @body@ attribute belongs to the @BlogPost@ model.
+
+h2. Attributes
+
+We can directly access the @title@ attribute through @BlogPost@ and even change it's value
+
+<pre>
+  blog_post.title # "Wow"
+  blog_post.title = "Oh boy!"
+  blog_post.save!
+  blog_post.title # "Oh boy!"
+</pre>
+
+We can also update attributes like normal through @update_attributes@
+
+<pre>
+  blog_post.update_attributes(:title => "Hubba Hubba", :body => "Nice blog post!")
+  blog_post.title # "Hubba Hubba"
+  blog_post.body # "Nice blog post!"
+</pre>
+
+h2. Methods
+
+If we want to expose some methods from our predecessor model to it's heirs, we can do so when calling the @acts_as_predecessor@ class-method
+
+<pre>
+  class Post < ActiveRecord::Base
+
+    acts_as_predecessor :exposes => :hello
+
+    def hello
+      "Hi there!"
+    end
+
+  end
+</pre>
+
+Now all heirs of @Post@ will have a hello-method, which we can call directly on the heir-model:
+
+<pre>
+  blog_post = BlogPost.create(:title => "I am full", :body => "of methods...")
+  blog_post.hello # "Hi there!"
+</pre>
+
+If you for some reason need to override the method in one of your heir-models, you can simply implement the method, and it will override the method from the predecessor.
+
+<pre>
+  class BlogPost < ActiveRecord::Base
+
+    acts_as_heir_of :post
+
+    def hello
+      "Yo!"
+    end
+
+  end
+</pre>
+
+Calling the @hello@ method on BlogPost will now yield another result:
+
+<pre>
+  blog_post = BlogPost.create(:title => "I have", :body => "my own methods...")
+  blog_post.hello # "Yo!"
+</pre>
+
+If we need to combine the local method in the heir, with the method in the predecessor, we can do so through the @predecessor@ method of the heir model, kinda like you would use @super@.
+
+<pre>
+  class BlogPost < ActiveRecord::Base
+
+    acts_as_heir_of :post
+
+    def hello
+      "Yo! #{predecessor.hello}"
+    end
+
+  end
+</pre>
+
+The result would now be a combination of the local method in the heir, and the method in the predecessor:
+
+<pre>
+  blog_post = BlogPost.create(:title => "I have", :body => "my own methods...")
+  blog_post.hello # "Yo! Hi there!"
+</pre>
+
+h2. Listing and filtering
+
+To list all your wonderful heir models you do as you normally would in ActiveRecord, with one single exception.
+
+Normally you would call something like this, to show all @BlogPosts@
+
+<pre>
+  @posts = BlogPost.all
+</pre>
+
+This however will result in 1 + the number of returned records SQL calls, which is hardly good.
+Instead you need to tell ActiveRecord that it should include the predecessors of the heirs, like so:
+
+<pre>
+  @posts = BlogPost.all(:include => :predecessor)
+</pre>
+
+We now only call the database twice; Once for loading the heirs, and once for loading all referenced predecessors.
+
+Another gotcha is when you need to filter the heirs. You can't directly filter by attributes from the predecessor model.
+So in our example where we have the @title@ attribute in the @Post@ model, we can't do the following:
+
+<pre>
+  @posts = BlogPost.where("title = 'test'")
+</pre>
+
+Instead we need to join the predecessor attributes by its association, like so:
+
+<pre>
+  @posts = BlogPost.joins(:predecessor).where("posts.title = 'test'")
+</pre>
+
+Behind the scenes, CTI works just like a simple ActiveRecord association, so it makes sense.
+
+h2. Timestamps
+
+If all of your heir-models needs timestamps, then you can simply add timestamps to the predecessor model, and omit them from the heir-models.
+CTI will make sure, that whenever you update your heir-model, the @updated_at@ timestamp in the predecessor model will be updated.
+
+h2. A note on destruction
+
+CTI depends on the destroy-method of the models, and as such you should always delete predecessor and heir models by calling the @destroy@ method on either, and NEVER by calling the @delete@ or @delete_all@ methods.
+
+If you absolutely need to do a direct delete in the database, then you need to manually remove the counterpart as well.
+
+For instance, if you manually delete a @BlogPost@ that is heir of @Post@, then you need to first find the right @Post@, then delete the heir and finally delete the predecessor.
+
+h2. Advanced usage
+
+It is always possible to traverse between a predecessor and it's associated heir, through the @predecessor@ method of an heir, and the @heir@ method of a predecessor.
+
+h2. Credits
+
+Credits goes out to Thomas Dippel @ Benjamin Media A/S for the predecessor Heritage and Gerry from TechSpry.com for the idea for this implementation:
+http://techspry.com/ruby_and_rails/multiple-table-inheritance-in-rails-3/
+
+h2. Contributing to cti
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+h2. License
+
+<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" href="http://purl.org/dc/dcmitype/InteractiveResource" property="dct:title" rel="dct:type">CTI</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://github.com/seyedrazavi/cti" property="cc:attributionName" rel="cc:attributionURL">Seyed Razavi @ Education Apps</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.<br />Based on a work at <a xmlns:dct="http://purl.org/dc/terms/" href="https://github.com/dipth/Heritage" rel="dct:source">Heritage</a>
+

data/lib/cti.rb

@@ -0,0 +1,5 @@
+require 'rails'
+
+module Cti
+  require 'cti/railtie'
+end

data/lib/cti/active_record/acts_as_heir.rb

@@ -0,0 +1,103 @@
+module Cti
+  module ActiveRecord
+    module ActsAsHeir
+      
+      def child_of(parent_symbol)
+        acts_as_heir_of(parent_symbol)
+      end
+
+      def acts_as_heir_of(predecessor_symbol)
+        extend ClassMethods
+        include InstanceMethods
+
+        if predecessor_symbol.is_a?(String)
+          predecessor_symbol = predecessor_symbol.to_sym
+        end
+
+        class_attribute :_predecessor_klass, :_predecessor_symbol
+        self._predecessor_symbol = predecessor_symbol
+        self._predecessor_klass = predecessor_symbol.to_s.camelize.constantize # Object.const_get(predecessor_symbol.to_s.capitalize)
+
+        has_one :predecessor, :as => :heir, :class_name => predecessor_symbol.to_s.camelize, :autosave => true, :dependent => :destroy
+
+        alias_method_chain :predecessor, :build
+
+        # Expose columns from the predecessor
+        self._predecessor_klass.columns.reject{|c| c.primary || c.name =~ /^heir_/}.map(&:name).each do |att|
+          define_method(att) do
+            predecessor.send(att)
+          end
+          define_method("#{att}=") do |val|
+            predecessor.send("#{att}=",val)
+          end
+        end
+
+        # Expose associations from the predecessor
+        self._predecessor_klass.reflect_on_all_associations.reject{|a| a.name == :heir}.each do |association|
+          define_method(association.name) do
+            predecessor.send(association.name)
+          end
+          define_method("#{association.name}=") do |val|
+            predecessor.send("#{association.name}=",val)
+          end
+        end
+
+        # Include validations from the predecessor
+        self._predecessor_klass.validators.each do |validator|
+          self.validates_with(validator.class, :attributes => validator.attributes, :options => validator.options)
+        end
+
+        # We need to make sure that updated_at values in the predecessor table is updated when the heir is saved.
+        before_update :touch_predecessor, :unless => lambda { predecessor.changed? }
+
+        # Expose methods from predecessor
+        self._predecessor_klass.get_heritage_exposed_methods.each do |method_symbol|
+          define_method(method_symbol.to_s) do |*args|
+            predecessor.send(method_symbol.to_s, *args)
+          end
+        end
+
+        # This piece deals with errors names
+        # and simply strips "predecessor." part from all the predecessor errors.
+        after_validation do
+          new_errors = {}
+          keys_to_delete = []
+          errors.each do |e|
+            if e =~ /^predecessor/
+              new_e = e.to_s.sub("predecessor.", '')
+              new_errors[new_e] = errors[e].first
+              keys_to_delete << e
+            end
+          end
+          keys_to_delete.each { |k|   errors.delete(k) }
+          new_errors.each     { |k,v| errors.add(k, v) }
+        end
+      end
+
+      module ClassMethods
+
+      end
+
+      module InstanceMethods
+        def heritage
+          predecessor
+        end
+
+        def lineage
+          self
+        end
+
+        def predecessor_with_build(attributes = {})
+          predecessor_without_build || build_predecessor(attributes)
+        end
+
+        def touch_predecessor
+          if self.changed?
+            predecessor.touch
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/cti/active_record/acts_as_predecessor.rb

@@ -0,0 +1,49 @@
+module Cti
+  module ActiveRecord
+    module ActsAsPredecessor
+      
+      def parent_model(options = {})
+        acts_as_predecessor(options)
+      end
+
+      def acts_as_predecessor(options = {})
+        extend ClassMethods
+        include InstanceMethods
+
+        options[:exposes] ||= []
+        class_attribute :_acts_as_predecessor_settings
+        self._acts_as_predecessor_settings = options
+
+        belongs_to :heir, :polymorphic => true
+
+        before_update :touch_heir, :unless => lambda { heir.try(:changed?) }
+      end
+
+      module ClassMethods
+
+        def get_heritage_exposed_methods
+          result = self._acts_as_predecessor_settings[:exposes]
+          result.is_a?(Array) ? result : [result]
+        end
+
+      end
+
+      module InstanceMethods
+        def heritage
+          self
+        end
+
+        def lineage
+          heir
+        end
+
+        def touch_heir
+          if self.changed?
+            heir.try(:touch)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/cti/railtie.rb

@@ -0,0 +1,20 @@
+require 'rails'
+
+module Cti
+  
+  class Railtie < Rails::Railtie
+    
+    initializer 'cti' do |app|
+      
+      ActiveSupport.on_load(:active_record) do
+        require 'cti/active_record/acts_as_predecessor'
+        require 'cti/active_record/acts_as_heir'
+        ::ActiveRecord::Base.send(:extend, Cti::ActiveRecord::ActsAsPredecessor)
+        ::ActiveRecord::Base.send(:extend, Cti::ActiveRecord::ActsAsHeir)
+      end
+      
+    end
+    
+  end
+  
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: cti
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Seyed Razavi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A gem for implementing multiple table inheritance in rails 4
+email: seyed@educationapps.co.uk
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.textile
+files:
+- README.textile
+- lib/cti.rb
+- lib/cti/active_record/acts_as_heir.rb
+- lib/cti/active_record/acts_as_predecessor.rb
+- lib/cti/railtie.rb
+homepage: http://github.com/seyedrazavi/cti
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A gem for implementing multiple table inheritance in rails 4
+test_files: []