@@ -1,4 +1,4 @@ -Copyright (c) 2008 Action Moniker LLC., http://www.actionmoniker.com/ +Copyright (c) 2008 Ken Collins, Decisiv Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the MIT-LICENSE @@ -1,27 +1,78 @@ -GroupedScope -============ +== GroupedScope: Has Many Associations IN (GROUPS) -Introduction goes here. +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. -TODO -==== +=== Installation & Usage -* Raise error if piggy back assoc uses :finder_sql option -* Change these to account for :as option: - GroupedScope::HasManyAssociation -* Turn on some mocha options/warnings. -* Support finder sql +From your project's RAILS_ROOT, run: -Running Tests -============= + script/plugin install git://github.com/metaskills/grouped_scope.git -Make sure to install -require 'shoulda' -require 'mocha' +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 -Copyright (c) 2008 Action Moniker LLC., http://www.actionmoniker.com/ +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 + +* 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. + + +Copyright (c) 2008 Ken Collins, Decisiv Inc. Released under the MIT license. README.rdoc @@ -8,7 +8,7 @@ require 'grouped_scope/has_many_through_association' module GroupedScope - VERSION = '1.0.0' + VERSION = '0.1.0' end lib/grouped_scope.rb f25545ccc75e9a7e3198704d77e394bb54465584 Ken Collins ken@metaskills.net http://github.com/metaskills/grouped_scope/commit/09629a4f4557db4c180e7baf5898c5e93d5670ae 09629a4f4557db4c180e7baf5898c5e93d5670ae 2008-09-25T19:48:04-07:00 2008-09-25T19:48:04-07:00 Adding some docs. a24970fa0cd278bc17bbc299125db029046895fb Ken Collins ken@metaskills.net