Permalink
Browse files

Update docs and add TravisCI

  • Loading branch information...
1 parent 3bfa890 commit 9fd64a65f3a984b421535166de01481137ef3911 @metaskills committed Dec 1, 2011
Showing with 110 additions and 98 deletions.
  1. +5 −0 .travis.yml
  2. +105 −0 README.md
  3. +0 −98 README.rdoc
View
5 .travis.yml
@@ -0,0 +1,5 @@
+rvm:
+ - 1.8.7
+ - 1.9.2
+ - 1.9.3
+ - ree
View
105 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 # => [#<Employee id: 1, group_id: nil>]
+```
+
+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 # => [#<Employee id: 1, group_id: 1>, #<Employee id: 2, group_id: 1>]
+```
+
+Calling grouped_scope on the :reports association leaves the existing association intact.
+
+```ruby
+@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.
+
+```ruby
+@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 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
+
View
98 README.rdoc
@@ -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 # => [#<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.
-

0 comments on commit 9fd64a6

Please sign in to comment.