From 9fd64a65f3a984b421535166de01481137ef3911 Mon Sep 17 00:00:00 2001 From: Ken Collins Date: Thu, 1 Dec 2011 10:29:11 -0500 Subject: [PATCH] Update docs and add TravisCI --- .travis.yml | 5 +++ README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.rdoc | 98 ------------------------------------------------ 3 files changed, 110 insertions(+), 98 deletions(-) create mode 100644 .travis.yml create mode 100644 README.md delete mode 100644 README.rdoc diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..0d4604e --- /dev/null +++ b/.travis.yml @@ -0,0 +1,5 @@ +rvm: + - 1.8.7 + - 1.9.2 + - 1.9.3 + - ree \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..26e73b5 --- /dev/null +++ b/README.md @@ -0,0 +1,105 @@ + +# GroupedScope: Has Many Associations IN (GROUPS) + +GroupedScope aims to make two things easier in your ActiveRecord models. First, provide an +easy way to group objects. Second, to allow the group to share association collections via existing +has_many relationships. See installation and usage for more details. + +http://metaskills.net/2008/09/28/jack-has_many-things/ + + + +## Installation & Usage + +Install the gem with bundler. + +```ruby +gem 'grouped_scope' +``` + +To use GroupedScope on a model it must have a `:group_id` column. + +```ruby +class AddGroupId < ActiveRecord::Migration + def up + add_column :employees, :group_id, :integer + end + def down + remove_column :employees, :group_id + end +end +``` + +Assume the following model. + +```ruby +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. + +```ruby +@employee_one.group # => [#] +``` + +To group resources, just assign the same `:group_id` in the schema. + +```ruby +@employee_one.update_attribute :group_id, 1 +@employee_two.update_attribute :group_id, 1 +@employee_one.group # => [#, #] +``` + +Calling grouped_scope on the :reports association leaves the existing association intact. + +```ruby +@employee_one.reports # => [#] +@employee_two.reports # => [#, #] +``` + +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. + +```ruby +@employee_one.group.reports # => [#, + #, + #] +``` + +You can even call scopes or association extensions defined on the objects in the collection +defined on the original has_many. For instance: + +```ruby +@employee.group.reports.urgent.assigned_to(user) +``` + + + +## Todo List + +* Add more GroupedScope::Grouping code. +* Add polymorphic support. +* Add :through support. +* Raise errors and/or support :finder_sql/:counter_sql. +* Add a user definable group_id schema. + + + +## Testing + +Simple! Just clone the repo, then run `bundle install` and `bundle exec rake`. The tests will begin to run. We also use Travis CI to run our tests too. Current build status is: + +[![Build Status](https://secure.travis-ci.org/metaskills/grouped_scope.png)](http://travis-ci.org/metaskills/grouped_scope) + + + +## License + +Released under the MIT license. +Copyright (c) 2011 Ken Collins + diff --git a/README.rdoc b/README.rdoc deleted file mode 100644 index 71ef100..0000000 --- a/README.rdoc +++ /dev/null @@ -1,98 +0,0 @@ - -== 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.x - - -=== 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 # => [#] - -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 # => [#, #] - -Calling grouped_scope on the :reports association leaves the existing association intact. - - @employee_one.reports # => [#] - @employee_two.reports # => [#, #] - -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 # => [#, - #, - #] - -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. -