Merge pull request #23 from CambridgeEducation/change_pagination_api

Support for each and each_page

Author: pallymore

README.md

@@ -35,17 +35,21 @@ end
 
 ### Surveys
 
-To paginate all your surveys:
+To enumerate all your surveys:
 
 ```ruby
-surveys = QualtricsAPI.surveys.fetch
-# => #<QualtricsAPI::SurveyCollection:0x007fcb72cce350 ....>
-
-surveys = surveys.next_page # to fetch next page if not on the last page
-# => #<QualtricsAPI::SurveyCollection:0x007fcb72cce350 ....>
+QualtricsAPI.surveys.each do |survey|
+  # => #<QualtricsAPI::Survey:0x007fcb72cce350 ....>
+end
+```
 
-surveys.next_page?
-# => true
+To enumerate individual pages:
+```ruby
+QualtricsAPI.surveys.each_page do |page|
+  page.each do |survey|
+    # => #<QualtricsAPI::Survey:0x007fcb72cce350 ....>
+  end
+end
 ```
 
 You can search for a survey by id:
@@ -137,14 +141,22 @@ export.status
 
 ### Panels
 
-To paginate all the panels:
+To enumerate all the panels:
 
 ```ruby
-panels = QualtricsAPI.panels.fetch
-# => #<QualtricsAPI::PanelCollection:0x007f8769aae2c0 ....>
+QualtricsAPI.panels.each do |panel|
+  # => #<QualtricsAPI::Panel:0x007f8769aae2c0 ....>
+end
+```
+
+To enumerate individual pages:
 
-panels = panels.next_page # get next page if panels.next_page?
-# => #<QualtricsAPI::PanelCollection:0x007f8769aae2c0 ....>
+```ruby
+QualtricsAPI.panels.each_page do |page|
+  page.each do |survey|
+    # => #<QualtricsAPI::Panel:0x007f8769aae2c0 ....>
+  end
+end
 ```
 
 You can search for a panel by id:

fixtures/vcr_cassettes/panel_collection_fetch_fail.yml

@@ -6,24 +6,21 @@ class BaseCollection
     include QualtricsAPI::Extensions::SerializableCollection
     include QualtricsAPI::Connectable
 
-    values do
-      attribute :page, Array, :default => []
-      attribute :fetched, Boolean, :default => false
-      attribute :next_endpoint, String
-    end
-
-    def_delegator :page, :each
-
-    def fetch
-      parse_fetch_response(QualtricsAPI.connection(self).get(list_endpoint))
-      self
+    def each
+      each_page do |page|
+        page.each do |element|
+          yield element
+        end
+      end
     end
 
-    def next_page
-      raise NotFoundError unless next_page?
-      self.class.new.tap do |r|
-        r.parse_fetch_response(QualtricsAPI.connection(self).get(next_endpoint))
-        r.propagate_connection(self)
+    def each_page
+      endpoint = list_endpoint
+      loop do
+        response = QualtricsAPI.connection(self).get(endpoint)
+        endpoint = response.body["result"]["nextPage"]
+        yield parse_page(response)
+        break unless endpoint
       end
     end
 
@@ -33,19 +30,16 @@ def find(id)
       build_result(response.body['result']).propagate_connection(self)
     end
 
-    def next_page?
-      raise NotYetFetchedError unless fetched
-      !next_endpoint.nil?
-    end
-
     protected
 
-    def parse_fetch_response(response)
-      @page = response.body["result"]["elements"].map do |element|
+    def page_endpoint(fetched)
+      fetched ? @next_endpoint : list_endpoint
+    end
+
+    def parse_page(response)
+      response.body["result"]["elements"].map do |element|
         build_result(element).propagate_connection(self)
       end
-      @next_endpoint = response.body["result"]["nextPage"]
-      @fetched = true
     end
   end
 end

fixtures/vcr_cassettes/panel_member_collection_fetch_fail.yml

@@ -1,10 +1,6 @@
 require 'spec_helper'
 
 describe QualtricsAPI::PanelCollection do
-  it "has no @page when initialized" do
-    expect(subject.page).to eq []
-  end
-
   describe "integration" do
     describe "#find" do
       let(:result) do
@@ -29,57 +25,31 @@
         end
       end
     end
-    describe "#fetch" do
+    describe "#each_page" do
       describe "when success" do
-        before do
-          expect(subject.page.size).to eq 0
-        end
-
         let!(:result) do
           VCR.use_cassette("panel_collection_fetch_success") do
-            subject.fetch
+            subject.each_page do |page|
+              return page
+            end
           end
         end
 
         it "populates the collection" do
-          expect(subject.page.size).to eq 1
-          expect(subject.first).to be_a QualtricsAPI::Panel
-        end
-
-        it "returns itself" do
-          expect(result).to eq subject
+          expect(result.size).to eq 1
+          expect(result.first).to be_a QualtricsAPI::Panel
         end
       end
 
       describe "when failed" do
         it "raises error and does not reset panels" do
-          subject.instance_variable_set :@page, [QualtricsAPI::Panel.new({})]
           expect do
             VCR.use_cassette("panel_collection_fetch_fail") do
-              begin
-                subject.fetch
-              rescue
-                nil
-              end
+              subject.each_page
             end
-          end.not_to change { subject.page }
+          end.to raise_error(QualtricsAPI::BadRequestError)
         end
       end
     end
   end
-
-  describe 'equality' do
-    subject { described_class.new(page: [QualtricsAPI::Panel.new("panelId" => "p1"), QualtricsAPI::Panel.new("panelId" => "p2")]) }
-    context 'when same' do
-      it 'returns true' do
-        expect(subject).to eq(described_class.new(page: subject.page))
-      end
-    end
-  
-    context 'when different' do
-      it 'returns false' do
-        expect(subject).not_to eq(described_class.new)
-      end
-    end
-  end
 end

lib/qualtrics_api/base_collection.rb

@@ -1,10 +1,6 @@
 require 'spec_helper'
 
 describe QualtricsAPI::PanelMemberCollection do
-  it "has no @page when initialized" do
-    expect(subject.page).to eq []
-  end
-
   describe "integration" do
     subject { described_class.new(id: 'ABCD') }
 
@@ -34,34 +30,25 @@
 
     describe "#fetch" do
       describe "when success" do
-        before do
-          expect(subject.page.size).to eq 0
-        end
-
         let!(:result) do
           VCR.use_cassette("panel_member_collection_fetch_success") do
-            subject.fetch
+            subject.each_page do |page|
+              return page
+            end
           end
         end
 
         it "populates the collection" do
-          expect(subject.page.size).to eq 1
-          expect(subject.first).to be_a QualtricsAPI::PanelMember
-        end
-
-        it "returns itself" do
-          expect(result).to eq subject
+          expect(result.size).to eq 1
+          expect(result.first).to be_a QualtricsAPI::PanelMember
         end
       end
 
       describe "when failed" do
-        it "raise error and does not change panels" do
-          subject.instance_variable_set :@page, [QualtricsAPI::PanelMember.new({})]
-          expect do
-            VCR.use_cassette("panel_member_collection_fetch_fail") do
-              expect { subject.fetch }.to raise_error
-            end
-          end.not_to change { subject.page }
+        it "raise error" do
+          VCR.use_cassette("panel_member_collection_fetch_fail") do
+            expect { subject.each_page }.to raise_error(QualtricsAPI::BadRequestError)
+          end
         end
       end
     end
@@ -95,24 +82,9 @@
         let(:panel_members) { [QualtricsAPI::PanelMember.new] }
 
         it "returns results" do
-          expect { result }.to raise_error
+          expect { result }.to raise_error(QualtricsAPI::BadRequestError)
         end
       end
     end
   end
-
-  describe 'equality' do
-    subject { described_class.new(page: [QualtricsAPI::PanelMember.new("recipientID" => "p1"), QualtricsAPI::PanelMember.new("recipientID" => "p1")]) }
-    context 'when same' do
-      it 'returns true' do
-        expect(subject).to eq(described_class.new(page: subject.page))
-      end
-    end
-  
-    context 'when different' do
-      it 'returns false' do
-        expect(subject).not_to eq(described_class.new)
-      end
-    end
-  end
 end