README

   1
   2 Has_many_polymorphs
   3
   4 An ActiveRecord plugin for defining self-referential polymorphic associations.
   5
   6 == License
   7
   8 Copyright 2007 Cloudburst, LLC. Licensed under the AFL 3. See the included LICENSE file.
   9
  10 == Description
  11
  12 This plugin gives you the ability to define easy-to-use self-referential polymorphic associations with full array-like behavior in your models. It is an extension of <tt>has_many :through</tt>.
  13
  14 “Polymorphic” means an association can freely point to any of several unrelated model classes, instead of being tied to one particular class.
  15
  16 == Features
  17
  18 * self-references
  19 * double-sided polymorphism
  20 * efficient, merged association SELECT
  21 * STI support
  22 * namespace support
  23 * automatic individual and reverse associations
  24
  25 And a generator for a tagging system, a common use case.
  26
  27 == Requirements
  28
  29 * Rails 1.2.3 or greater
  30
  31 = Usage
  32
  33 == Installation
  34
  35 To install the Rails plugin, run:
  36   script/plugin install svn://rubyforge.org/var/svn/fauna/has_many_polymorphs/trunk
  37
  38 There's also a gem version. To install it instead, run:
  39   sudo gem install has_many_polymorphs
  40
  41 If you are using the gem, make sure to add <tt>require 'has_many_polymorphs'</tt> to <tt>environment.rb</tt>, before Rails::Initializer block.
  42
  43 == Configuration
  44
  45 Setup the parent model as so:
  46
  47   class Petfood < ActiveRecord::Base
  48     has_many_polymorphs :eaters, :from => [:dogs, :cats, :birds]
  49   end
  50
  51 The join model:
  52
  53   class EatersPetfood < ActiveRecord::Base
  54     belongs_to :petfood
  55     belongs_to :eater, :polymorphic => true
  56   end
  57
  58 One of the child models:
  59
  60   class Dog < ActiveRecord::Base
  61     # nothing
  62   end
  63
  64 See ActiveRecord::Associations::PolymorphicClassMethods for more configuration options.
  65
  66 == Helper methods example
  67
  68   petfood = Petfood.find(1)
  69   petfood.eaters.map(&:class) # => [Dog, Cat, Cat, Bird]
  70
  71   petfood.eaters.push(Cat.create)
  72   petfood.eaters << Cat.create
  73   petfood.cats.size # => 4
  74   petfood.eaters.size # => 6
  75
  76   petfood.eaters.delete(petfood.dogs[0])
  77   petfood.dogs.size # => 0
  78   petfood.eaters.size # => 5
  79
  80   # works both ways
  81   petfood.eaters[0].petfoods.include?(petfood) # => true
  82
  83 See ActiveRecord::Associations::PolymorphicAssociation for more helper method details.
  84
  85 = Extras
  86
  87 == Double-sided polymorphism
  88
  89 Double-sided relationships are defined on the join model:
  90
  91   class Devouring < ActiveRecord::Base
  92     belongs_to :eater, :polymorphic => true
  93     belongs_to :eaten, :polymorphic => true
  94
  95     acts_as_double_polymorphic_join(
  96       :eaters =>[:dogs, :cats],
  97       :eatens => [:cats, :birds]
  98     )
  99   end
 100
 101 Now, dogs and cats can eat birds and cats. Birds can't eat anything (they aren't <tt>eaters</tt>) and dogs can't be eaten by anything (since they aren't <tt>eatens</tt>). The keys stand for what the models are, not what they do.
 102
 103 In this case, each eater/eaten relationship is called a Devouring.
 104
 105 See ActiveRecord::Associations::PolymorphicClassMethods for more.
 106
 107 == Tagging generator
 108
 109 Has_many_polymorphs includes a tagging system generator.
 110
 111   ./script/generate tagging TaggableModel1 TaggableModel2 [..]
 112
 113 You can use the flag <tt>--skip-migration</tt> (to avoid generating a migration, for example, if you are converting from <tt>acts_as_taggable)</tt>, as well as the flag <tt>--self-referential</tt> (if you want tags to be able to tag tags).
 114
 115 Tests will be generated, but will not work unless you have at least 2 fixture entries for the first two taggable models. Their ids must be 1 and 2.
 116
 117 == Troubleshooting
 118
 119 Some debugging tools are available in <tt>lib/has_many_polymorphs/debugging_tools.rb</tt>.
 120
 121 If you are having trouble, think very carefully about how your model classes, key columns, and table names relate. You may have to explicitly specify options on your join model such as <tt>:class_name</tt>, <tt>:foreign_key</tt>, or <tt>:as</tt>. The included tests are a good place to look for examples.
 122
 123 Note that because of the way Rails reloads model classes, the plugin can sometimes bog down your development server. Set <tt>config.cache_classes = true</tt> in <tt>config/environments/development.rb</tt> to avoid this.
 124
 125 == Further resources
 126
 127 * http://blog.evanweaver.com/pages/code#polymorphs
 128 * http://rubyforge.org/forum/forum.php?forum_id=8117