== GroupedScope: Has Many Associations IN (GROUPS)

GroupedScope aims to make two things easier in your ActiveRecord models. First, provide a 
easy way to group objects, second, to allow the group to share associated object via existing 
has_many relationships. See installation and usage for more details.

By the way, this plugin has been tested with rails 2.3.2, 2.2.2, and 2.1.1


=== Installation & Usage

From your project's RAILS_ROOT, run:

  ./script/plugin install git://github.com/metaskills/grouped_scope.git

To use GroupedScope on a model it must have a :group_id column.

  class AddGroupId < ActiveRecord::Migration
    def self.up
      add_column :employees, :group_id, :integer
    end
    def self.down
      remove_column :employees, :group_id
    end
  end

Assume the following model.

  class Employee < ActiveRecord::Base
    has_many :reports
    grouped_scope :reports
  end
  
By calling grouped_scope on any association you create a new group accessor for each 
instance. The object returned will act just like an array and at least include the 
current object that called it.

  @employee_one.group   # => [#<Employee id: 1, group_id: nil>]
  
To group resources, just assign the same :group_id in the schema. Note that in future 
versions I will be extending the GroupedScope::Grouping that each object belongs to. 
If you do not just want to assign some random integers, then take a look at that model 
and the belongs_to :grouping code, schema needed ofcourse

  @employee_one.update_attribute :group_id, 1
  @employee_two.update_attribute :group_id, 1
  @employee_one.group   # => [#<Employee id: 1, group_id: 1>, #<Employee id: 2, group_id: 1>]

Calling grouped_scope on the :reports association leaves the existing association intact.

  @employee_one.reports  # => [#<Report id: 2, employee_id: 1>]
  @employee_two.reports  # => [#<Report id: 18, employee_id: 2>, #<Report id: 36, employee_id: 2>]

Now the good part, all associations passed to the grouped_scope method can be called 
on the group proxy. The collection will return resources shared by the group.

  @employee_one.group.reports   # => [#<Report id: 2, employee_id: 1>, 
                                      #<Report id: 18, employee_id: 2>, 
                                      #<Report id: 36, employee_id: 2>]

You can even call named scopes defined on the objects in the collection and association 
extensions defined on the original has_many. For instance:

  @employee.group.reports.urgent.assigned_to(user)



=== Todo List

* Go back and start adding some rdocs.
* Add more GroupedScope::Grouping code.
* Add polymorphic support.
* Add/test has_and_belongs_to_many
* Raise errors and/or support :finder_sql/:counter_sql.
* Add a user definable group_id schema.


=== Helping Our & Running Tests

Running the test suite is easy to do. Just make sure you have the following gems installed. 

* shoulda
* quitebacktrace
* mocha
* factory_girl

If you want to run the tests for a specific version of rails in gems (other than the latest), 
then you can set the RAILS_VERSION environment variable. For example `env RAILS_VERSION=1.2.6 autotest`. 
When doing this you also need to make sure that you download version 4.1 of shoulda (not the gem) 
and place its lib contents into `test/lib/shoulda` and `test/lib/shoulda.rb`. The reason is that 
the latest should gem require ActiveSupport greater than 2.0.



Copyright (c) 2008 Ken Collins, Decisiv Inc.
Released under the MIT license.