RubyDoc.info: File: README – Documentation for metaskills-grouped_scope (0.5.1)

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 1.2.6, 2.0.4, 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.