active_collection 0.2.4 → 0.2.5

data/README.rdoc

@@ -3,6 +3,123 @@
 Lazy-loaded Array-like collections of records.
 Compatible with will_paginate.
 
+== Example
+
+A quick example:
+
+If you have a model
+
+    class Beer < ActiveRecord::Base
+    end
+
+You can make ActiveCollections of Beers like so:
+
+    class BeerCollection < ActiveCollection::Base
+    end
+
+Or a more complex version:
+
+    class BeerCollection < ActiveCollection::Base
+
+      scope :geolocation
+      scope :by_brewery
+      order_by "distance ASC"
+
+      def names
+        map(&:name)
+      end
+
+      protected
+
+      def geolocation
+        if params[:lat] && params[:lng]
+          { :origin => [params[:lat], params[:lng]], :within => params[:radius] || 50 }
+        end
+      end
+
+      def by_brewery
+        if params[:brewery_id]
+          { :conditions => { :brewery_id => params[:brewery_id] } }
+        end
+      end
+    end
+
+And you would use it like so:
+
+    beers = BeerCollection.new(:lat => 38.1234, :lng => -117.6543)
+
+    # All of these are lazy loaded only when they're needed.
+    beers.size # => Beer.count(:origin => [38.1234, -117.6543], :within => 50)
+    beers.each # => Beer.all(:origin => [38.1234, -117.6543], :within => 50, :order => "distance ASC") and yields each record
+
+==== Custom conditions
+
+You can specify anything you want for conditions using the scope, find_scope, and count_scope class methods. Conditions on the fly is on my road map.
+
+    brewery_beers = BeerCollection.new(:brewery_id => 1)
+    brewery_beers.to_a # Beer.all(:conditions => {:brewery_id => 1}) => [Beer, Beer, Beer, ...]
+    brewery_beers.size # Does not load count, just takes the size of the loaded collection.
+    brewery_beers.names # => ["La Folie", "1554", ...]
+
+==== Pagination
+
+ActiveCollections are fully will_paginate compliant.
+
+    paginated_beers = brewery_beers.paginate
+    paginated_beers.size # => size of this page only (doesn't query if already loaded)
+    paginated_beers.total_entries # => size of the entire collection without paging. (performs a database lookup if it can't be inferred by the collection size)
+    paginated_beers.total_pages
+    paginated_beers.next_page_collection # => new BeerCollection for page 2. Again, lazily-loaded.
+
+==== Includes
+
+Specify eager loading for a collection.
+
+    beers.include(:brewery) # => new collection that will eager load Brewery association when it loads.
+
+Includes can also be specified in the class along with order. Anything specified on the class will combine using active record's rules (merge includes, overwrite order).
+
+    class BeerCollection < ActiveCollection::Base
+      includes :brewery => :owner
+      order_by "name asc"
+
+      # ...
+    end
+
+== Usage
+
+I tend to use this in my index action in a controller by just passing in params.
+
+    def index
+      @beers = BeerCollection.new(params)
+    end
+
+It will automatically take care of paging. You can also pass the collection itself to the index named route to pass along the params necessary to link to the collection.
+
+    beers_path(@beers) # => Includes the right options for paging and any specified order or search query.
+
+== Coming Soon
+
+==== Search Integration
+
+This can already be done by overloading load_collection and load_count in your collection.
+
+I have sphinx and solr searching integrated on another project but I've yet to abstract it. Probably will work something like this:
+
+    BeerCollection.new(:q => "search term")
+
+and then you specify searchability like so:
+
+    class BeerCollection < ActiveCollection::Base
+      # It could possibly auto-configure by looking at what search libraries are loaded.
+      # Note: this doesn't exist yet.
+      search_on :q, :using => :thinking_sphinx
+    end
+
+==== Geolocation Integration
+
+This can already be done as shown above, but I'd like it to be knowledgeable of the available geolocation libraries like Geokit and also support local search with solr and sphinx. 
+
 == Copyright
 
 Copyright (c) 2009 Martin Emde. See LICENSE for details.

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:patch: 4
+:patch: 5
 :major: 0
 :minor: 2

data/active_collection.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{active_collection}
-  s.version = "0.2.4"
+  s.version = "0.2.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Martin Emde"]
-  s.date = %q{2009-10-12}
+  s.date = %q{2009-10-13}
   s.description = %q{A lazy-loading, Array-like collection proxy for ActiveRecord that understands conditions and paging.}
   s.email = %q{martin.emde@gmail.com}
   s.extra_rdoc_files = [
@@ -35,7 +35,9 @@ Gem::Specification.new do |s|
      "lib/active_collection/scope.rb",
      "lib/active_collection/serialization.rb",
      "spec/base_spec.rb",
+     "spec/includes_spec.rb",
      "spec/member_class_spec.rb",
+     "spec/order_spec.rb",
      "spec/pagination_spec.rb",
      "spec/proxy_spec.rb",
      "spec/spec.opts",
@@ -49,7 +51,9 @@ Gem::Specification.new do |s|
   s.summary = %q{A lazy-loading, Array-like collection proxy for ActiveRecord that understands conditions and paging.}
   s.test_files = [
     "spec/base_spec.rb",
+     "spec/includes_spec.rb",
      "spec/member_class_spec.rb",
+     "spec/order_spec.rb",
      "spec/pagination_spec.rb",
      "spec/proxy_spec.rb",
      "spec/spec_helper.rb"

data/lib/active_collection/base.rb

@@ -53,7 +53,7 @@ module ActiveCollection
 
     # dup that doesn't include the collection if it's loaded
     def unloading_dup
-      d = super
+      d = dup
       d.unload!
       yield d if block_given?
       d

data/lib/active_collection/includes.rb

@@ -8,49 +8,77 @@ module ActiveCollection
       end
     end
 
+    # def self.before_save(*methods, &block)
+    #   callbacks = CallbackChain.build(:before_save, *methods, &block)
+    #   @before_save_callbacks ||= CallbackChain.new
+    #   @before_save_callbacks.concat callbacks
+    # end
+    #
+    # def self.before_save_callback_chain
+    #   @before_save_callbacks ||= CallbackChain.new
+    #
+    #   if superclass.respond_to?(:before_save_callback_chain)
+    #     CallbackChain.new(
+    #       superclass.before_save_callback_chain +
+    #       @before_save_callbacks
+    #     )
+    #   else
+    #     @before_save_callbacks
+    #   end
+    # end
+
     module ClassMethods
-      def includes(*includes)
-        write_inheritable_attribute(:default_includes, includes)
+      def includes(*new_includes)
+        @default_includes = merge_includes(@default_includes || [], new_includes)
       end
 
       def default_includes
-        read_inheritable_attribute(:default_includes) || []
+        @default_includes ||= []
+        if superclass != ActiveCollection::Base
+          merge_includes(superclass.default_includes, @default_includes)
+        else
+          @default_includes
+        end
+      end
+
+      def merge_includes(a, b)
+        (safe_to_array(a) + safe_to_array(b)).flatten.uniq
+      end
+
+      protected
+
+      # Taken from ActiveRecord::Base
+      #
+      # Object#to_a is deprecated, though it does have the desired behavior
+      def safe_to_array(o)
+        case o
+        when NilClass
+          []
+        when Array
+          o
+        else
+          [o]
+        end
       end
     end
 
     def includes
-      @includes ||= self.class.default_includes
+      @includes ||= []
     end
 
     def include(*new_includes)
-      ac = unloading_dup
-      ac.include! *new_includes
-      ac
+      unloading_dup { |ac| ac.include! *new_includes }
     end
 
     def include!(*new_includes)
       raise_if_loaded
-      @includes = (safe_to_array(new_includes) + safe_to_array(includes)).uniq
+      @includes = self.class.merge_includes(includes, new_includes)
     end
 
     def include_options
-      { :include => @includes } unless @includes.blank?
+      incs = self.class.merge_includes(self.class.default_includes, includes)
+      { :include => incs } unless incs.blank?
     end
 
-    protected
-
-    # Taken from ActiveRecord::Base
-    #
-    # Object#to_a is deprecated, though it does have the desired behavior
-    def safe_to_array(o)
-      case o
-      when NilClass
-        []
-      when Array
-        o
-      else
-        [o]
-      end
-    end
   end
 end

data/lib/active_collection/member_class.rb

@@ -17,8 +17,8 @@ module ActiveCollection
       #     end
       # 
       # This will use the class Normal to do counts and finds.
-      def model(class_name)
-        (@model_class_name = class_name) && @model_class = nil
+      def model(model_name)
+        (@model_class_name = model_name) && @model_class = nil
       end
 
       # The actual member class.
@@ -42,10 +42,10 @@ module ActiveCollection
         model_class.human_name(*args).pluralize
       end
 
-      protected
-
       def model_class_name
-        @model_class_name || name.sub(/Collection$/,'')
+        @model_class_name ||
+          (superclass != ActiveCollection::Base && superclass.model_class_name) ||
+          name.sub(/Collection$/,'')
       end
     end
 

data/lib/active_collection/order.rb

@@ -8,6 +8,16 @@ module ActiveCollection
       end
     end
 
+    module ClassMethods
+      def order_by(order = "id ASC")
+        @order = order
+      end
+
+      def default_order
+        @order || (superclass != ActiveCollection::Base && superclass.default_order) || nil
+      end
+    end
+
     def order
       @order ||= self.class.default_order
     end
@@ -24,17 +34,8 @@ module ActiveCollection
     end
 
     def order_options
-      { :order => order } if order
-    end
-
-    module ClassMethods
-      def order_by(order = "id ASC")
-        write_inheritable_attribute(:default_order, order)
-      end
-
-      def default_order
-        read_inheritable_attribute(:default_order) || nil
-      end
+      ord = @order || self.class.default_order
+      { :order => ord } if ord
     end
   end
 end

data/lib/active_collection/pagination.rb

@@ -63,6 +63,19 @@ module ActiveCollection
       @current_page = pg
     end
 
+    # return a paginated collection if it isn't already paginated.
+    # returns self if already paginated.
+    def paginate
+      paginated?? self : page(1)
+    end
+
+    # forces pagination of self, raising if already loaded.
+    # returns current_page if the collection is now paginated
+    # returns nil if already paginated
+    def paginate!
+      paginated?? nil : page!(1)
+    end
+
     # Helper method that is true when someone tries to fetch a page with a
     # larger number than the last page. Can be used in combination with flashes
     # and redirecting.
@@ -134,20 +147,6 @@ module ActiveCollection
       (total_entries / per_page.to_f).ceil
     end
 
-    # return a paginated collection if it isn't already paginated.
-    # returns self if already paginated.
-    def paginate
-      paginated?? self : page(current_page || 1)
-    end
-
-    # forces pagination of self, raising if already loaded.
-    # returns current_page if the collection is now paginated
-    # returns nil if already paginated
-    def paginate!
-      raise_if_loaded
-      current_page ? nil : @current_page = 1
-    end
-
     # if the collection has a page parameter
     def paginated?
       current_page && current_page > 0

data/spec/includes_spec.rb

@@ -0,0 +1,143 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+class Beer
+end
+
+class IncludedBeerCollection < ActiveCollection::Base
+  model "Beer"
+  includes :brewery
+end
+
+class InheritedNotIncludedBeerCollection < IncludedBeerCollection
+end
+
+class InheritedIncludedBeerCollection < IncludedBeerCollection
+  includes :imbibes => :user
+end
+
+class NotIncludedBeerCollection < ActiveCollection::Base
+  model "Beer"
+end
+
+class MultipleIncludesBeerCollection < ActiveCollection::Base
+  model "Beer"
+  includes :brewery
+  includes :imbibes
+end
+
+describe ActiveCollection, "(includes)" do
+  context "(without class includes)" do
+    subject { NotIncludedBeerCollection.new }
+
+    it "does not have any includes" do
+      Beer.should_receive(:all).with({}).and_return([])
+      subject.to_a
+    end
+
+    it "adds includes added to an instance" do
+      subject.include! :tags
+      Beer.should_receive(:all).with(:include => [:tags]).and_return([])
+      subject.to_a
+    end
+
+    it "creates a new object with the includes on #include" do
+      col = subject.include :tags
+      Beer.should_receive(:all).with(:include => [:tags]).and_return([])
+      col.to_a
+    end
+
+    it "doesn't affect the existing object on #include" do
+      col = subject.include :tags
+      Beer.should_receive(:all).with({}).and_return([])
+      subject.to_a
+    end
+
+    it "doesn't choke on nil include" do
+      col = subject.include nil
+      Beer.should_receive(:all).with({}).and_return([])
+      subject.to_a
+    end
+  end
+
+  context "(with class includes)" do
+    subject { IncludedBeerCollection.new }
+
+    it "includes any class level includes with collection loads" do
+      Beer.should_receive(:all).with(:include => [:brewery]).and_return([])
+      subject.to_a
+    end
+
+    it "does not send includes with count" do
+      Beer.should_receive(:count).with({}).and_return(0)
+      subject.empty?
+    end
+
+    it "merges includes added to an instance with default includes" do
+      subject.include! :tags
+      Beer.should_receive(:all).with(:include => [:brewery, :tags]).and_return([])
+      subject.to_a
+    end
+
+    it "doesn't mind includes being given as an array" do
+      subject.include! [:tags]
+      Beer.should_receive(:all).with(:include => [:brewery, :tags]).and_return([])
+      subject.to_a
+    end
+  end
+
+  context "(inherited from a class with includes)" do
+    subject { InheritedNotIncludedBeerCollection.new }
+
+    it "includes superclass includes with collection loads" do
+      Beer.should_receive(:all).with(:include => [:brewery]).and_return([])
+      subject.to_a
+    end
+
+    it "does not send includes with count" do
+      Beer.should_receive(:count).with({}).and_return(0)
+      subject.empty?
+    end
+
+    it "merges includes added to an instance with default includes" do
+      subject.include! :tags
+      Beer.should_receive(:all).with(:include => [:brewery, :tags]).and_return([])
+      subject.to_a
+    end
+
+    it "creates a new object with the includes on #include" do
+      col = subject.include :tags
+      Beer.should_receive(:all).with(:include => [:brewery, :tags]).and_return([])
+      col.to_a
+    end
+  end
+
+  context "(inherited adding includes)" do
+    subject { InheritedIncludedBeerCollection.new }
+
+    it "merges superclass includes on collection load" do
+      Beer.should_receive(:all).with(:include => [:brewery, {:imbibes => :user}]).and_return([])
+      subject.to_a
+    end
+
+    it "merges includes added to an instance with default includes" do
+      subject.include! :tags
+      Beer.should_receive(:all).with(:include => [:brewery, {:imbibes => :user}, :tags]).and_return([])
+      subject.to_a
+    end
+  end
+
+  context "(multiple includes)" do
+    subject { MultipleIncludesBeerCollection.new }
+
+    it "merges includes on collection load" do
+      Beer.should_receive(:all).with(:include => [:brewery, :imbibes]).and_return([])
+      subject.to_a
+    end
+
+    it "merges includes added to an instance with default includes" do
+      subject.include! :tags
+      Beer.should_receive(:all).with(:include => [:brewery, :imbibes, :tags]).and_return([])
+      subject.to_a
+    end
+  end
+end

data/spec/member_class_spec.rb

@@ -1,30 +1,37 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
-class Beer
+class Model
   def self.human_name(*args)
-    "Beer"
+    "Model"
   end
 
   def self.table_name
-    "beers"
+    "models"
   end
 end
 
-class BeerCollection < ActiveCollection::Base
+class ModelCollection < ActiveCollection::Base
 end
 
-class DunkelBeer
+class SpecialModel
   def self.human_name(*args)
-    "Dunkel Beer"
+    "Special Model"
   end
 
   def self.table_name
-    "dunkel_beers"
+    "special_models"
   end
 end
 
-class DarkBeerCollection < ActiveCollection::Base
-  model "DunkelBeer"
+class SpecialCollection < ActiveCollection::Base
+  model "SpecialModel"
+end
+
+class InheritedSpecialCollection < SpecialCollection
+end
+
+class OverloadedInheritedSpecialCollection < SpecialCollection
+  model "Model"
 end
 
 class BrokenCollection < ActiveCollection::Base
@@ -32,38 +39,54 @@ end
 
 describe ActiveCollection do
   context "(with standard name)" do
-    subject { BeerCollection.new }
+    subject { ModelCollection.new }
 
     it "has the correct model_class" do
-      subject.model_class.should == Beer
+      subject.model_class.should == Model
     end
 
     it "retrieves table_name from member class" do
-      subject.table_name.should == "beers"
+      subject.table_name.should == "models"
     end
 
     it "retrieves human_name from member class and pluralizes" do
-      subject.human_name(:locale => 'en-us').should == "Beers"
+      subject.human_name(:locale => 'en-us').should == "Models"
     end
   end
 
   context "(with model)" do
-    subject { DarkBeerCollection.new }
+    subject { SpecialCollection.new }
 
     it "uses the correct model class" do
-      subject.model_class.should == DunkelBeer
+      subject.model_class.should == SpecialModel
     end
 
     it "doesn't affect other classes" do
-      BeerCollection.new.model_class.should == Beer
+      ModelCollection.new.model_class.should == Model
     end
 
     it "retrieves table_name from member class" do
-      subject.table_name.should == "dunkel_beers"
+      subject.table_name.should == "special_models"
     end
 
     it "retrieves human_name from member class and pluralizes" do
-      subject.human_name(:locale => 'en-us').should == "Dunkel Beers"
+      subject.human_name(:locale => 'en-us').should == "Special Models"
+    end
+  end
+
+  context "(inherited and not overloaded)" do
+    subject { InheritedSpecialCollection.new }
+
+    it "maintains the same model class" do
+      subject.model_class.should == SpecialModel
+    end
+  end
+
+  context "(inherited and overloaded)" do
+    subject { OverloadedInheritedSpecialCollection.new }
+
+    it "maintains the same model class" do
+      subject.model_class.should == Model
     end
   end
 

data/spec/order_spec.rb

@@ -0,0 +1,99 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+class Beer
+end
+
+class OrderedBeerCollection < ActiveCollection::Base
+  model "Beer"
+  order_by "name"
+end
+
+class InheritedOrderedBeerCollection < OrderedBeerCollection
+end
+
+class OverloadedInheritedOrderedBeerCollection < OrderedBeerCollection
+  order_by "created_at DESC"
+end
+
+class NotOrderedBeerCollection < ActiveCollection::Base
+  model "Beer"
+end
+
+describe ActiveCollection, "(order_by)" do
+  context "(without class order_by)" do
+    subject { NotOrderedBeerCollection.new }
+
+    it "does not have any order on load" do
+      Beer.should_receive(:all).with({}).and_return([])
+      subject.to_a
+    end
+
+    it "adds order on instance" do
+      subject.order_by! "id DESC"
+      Beer.should_receive(:all).with(:order => "id DESC").and_return([])
+      subject.to_a
+    end
+
+    it "creates a new object with the order_by on #order_by" do
+      col = subject.order_by "id DESC"
+      Beer.should_receive(:all).with(:order => "id DESC").and_return([])
+      col.to_a
+    end
+
+    it "doesn't affect the existing object on #order_by" do
+      col = subject.order_by "id DESC"
+      Beer.should_receive(:all).with({}).and_return([])
+      subject.to_a
+    end
+  end
+
+  context "(with class order_by)" do
+    subject { OrderedBeerCollection.new }
+
+    it "sends order when collection loads" do
+      Beer.should_receive(:all).with(:order => "name").and_return([])
+      subject.to_a
+    end
+
+    it "does not send order with count" do
+      Beer.should_receive(:count).with({}).and_return(0)
+      subject.empty?
+    end
+
+    it "overloads order when added to instance" do
+      subject.order_by! "id DESC"
+      Beer.should_receive(:all).with(:order => "id DESC").and_return([])
+      subject.to_a
+    end
+  end
+
+  context "(inherited from a class with order_by)" do
+    subject { InheritedOrderedBeerCollection.new }
+
+    it "sends superclass order on collection loads" do
+      Beer.should_receive(:all).with(:order => "name").and_return([])
+      subject.to_a
+    end
+
+    it "overloads order when added to instance" do
+      subject.order_by! "id DESC"
+      Beer.should_receive(:all).with(:order => "id DESC").and_return([])
+      subject.to_a
+    end
+  end
+
+  context "(inherited adding order_by)" do
+    subject { OverloadedInheritedOrderedBeerCollection.new }
+
+    it "overloads superclasses' order" do
+      Beer.should_receive(:all).with(:order => "created_at DESC").and_return([])
+      subject.to_a
+    end
+
+    it "overloads order when added to instance" do
+      subject.order_by! "id DESC"
+      Beer.should_receive(:all).with(:order => "id DESC").and_return([])
+      subject.to_a
+    end
+  end
+end

data/spec/pagination_spec.rb

@@ -113,10 +113,10 @@ describe ActiveCollection do
           subject.total_entries
         end
 
-        it "raises on attempt to force paginate after already loaded" do
+        it "raises on attempt to force a page number after already loaded" do
           subject.to_a
           subject.should be_loaded
-          lambda { subject.paginate! }.should raise_error(ActiveCollection::AlreadyLoadedError)
+          lambda { subject.page!(3) }.should raise_error(ActiveCollection::AlreadyLoadedError)
         end
 
         it "returns the same record on 'soft' paginate when already paginated" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: active_collection
 version: !ruby/object:Gem::Version 
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors: 
 - Martin Emde
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-12 00:00:00 -07:00
+date: 2009-10-13 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -50,7 +50,9 @@ files:
 - lib/active_collection/scope.rb
 - lib/active_collection/serialization.rb
 - spec/base_spec.rb
+- spec/includes_spec.rb
 - spec/member_class_spec.rb
+- spec/order_spec.rb
 - spec/pagination_spec.rb
 - spec/proxy_spec.rb
 - spec/spec.opts
@@ -85,7 +87,9 @@ specification_version: 3
 summary: A lazy-loading, Array-like collection proxy for ActiveRecord that understands conditions and paging.
 test_files: 
 - spec/base_spec.rb
+- spec/includes_spec.rb
 - spec/member_class_spec.rb
+- spec/order_spec.rb
 - spec/pagination_spec.rb
 - spec/proxy_spec.rb
 - spec/spec_helper.rb