Class: Recurly::Resource::Pager

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/recurly/resource/pager.rb

Overview

Pages through an index resource, yielding records as it goes. It’s rare to instantiate one on its own: use paginate, find_each, and Resource#{has_many_association} instead.

Because pagers handle has_many associations, pagers can also build and create child records.

Examples:

Through a resource class:

Recurly::Account.paginate # => #<Recurly::Resource::Pager...>

Recurly::Account.find_each { |a| p a }

Through an resource instance:

.transactions
# => #<Recurly::Resource::Pager...>

.transactions.new(attributes) # or #create, or #create!
# => #<Recurly::Transaction ...>

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(resource_class, options = {}) ⇒ Pager

A pager for paginating through resource records.

Parameters:

  • resource_class (Resource) —

    The resource to be paginated.

  • options (Hash) (defaults to: {}) —

    A hash of pagination options.

Options Hash (options):

  • :per_page (Integer) —

    The number of records returned per page.

  • :cursor (DateTime, Time, Integer) —

    A timestamp that the pager will skim back to and return records created before it.

  • :etag (String) —

    When set, will raise API::NotModified if the loaded page content has not changed.

  • :uri (String) —

    The default location the pager will request.

Raises:



47
48
49
50
51
52
53
54
 
# File 'lib/recurly/resource/pager.rb', line 47

def initialize resource_class, options = {}
  options[:cursor] &&= options[:cursor].to_i
  @parent = options.delete :parent
  @uri    = options.delete :uri
  @etag   = options.delete :etag
  @resource_class, @options = resource_class, options
  @collection = @count = nil
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args, &block) ⇒ Object (private) 



207
208
209
210
211
212
213
214
215
216
 
# File 'lib/recurly/resource/pager.rb', line 207

def method_missing name, *args, &block
  scope = resource_class.scopes[name] and return paginate scope

  if [].respond_to? name
    load! unless defined? @collection
    return @collection.send name, *args, &block
  end
  
  super
end

Instance Attribute Details

#etag ⇒ String? (readonly)

Returns An ETag for the current page.

Returns:

  • (String, nil) —

    An ETag for the current page.



31
32
33
 
# File 'lib/recurly/resource/pager.rb', line 31

def etag
  @etag
end

#links ⇒ Hash? (readonly)

Returns A hash of links to which the pager can page.

Returns:

  • (Hash, nil) —

    A hash of links to which the pager can page.



28
29
30
 
# File 'lib/recurly/resource/pager.rb', line 28

def links
  @links
end

#resource_class ⇒ Resource (readonly)

Returns The resource class of the pager.

Returns:

  • (Resource) —

    The resource class of the pager.



25
26
27
 
# File 'lib/recurly/resource/pager.rb', line 25

def resource_class
  @resource_class
end

Instance Method Details

#all(options = {}) ⇒ Object 



118
119
120
 
# File 'lib/recurly/resource/pager.rb', line 118

def all options = {}
  paginate(options).to_a
end

#count ⇒ Integer

Returns The total record count of the resource in question.

Returns:

  • (Integer) —

    The total record count of the resource in question.

See Also:



63
64
65
 
# File 'lib/recurly/resource/pager.rb', line 63

def count
  @count ||= API.head(uri, @options)['X-Records'].to_i
end

#create(attributes = {}) ⇒ Resource

Instantiates and saves a record in the scope of the pager.

Examples:

 = Recurly::Account.find 'schrader'
subscription = .subscriptions.create attributes

Returns:

Raises:

See Also:



146
147
148
 
# File 'lib/recurly/resource/pager.rb', line 146

def create attributes = {}
  new(attributes) { |record| record.save }
end

#create!(attributes = {}) ⇒ Resource

Instantiates and saves a record in the scope of the pager.

Examples:

 = Recurly::Account.find 'schrader'
subscription = .subscriptions.create! attributes

Returns:

Raises:

See Also:



159
160
161
 
# File 'lib/recurly/resource/pager.rb', line 159

def create! attributes = {}
  new(attributes) { |record| record.save! }
end

#each {|record| ... } ⇒ Array

Returns Iterates through the current page of records.

Yields:

  • (record)

Returns:

  • (Array) —

    Iterates through the current page of records.



69
70
71
72
73
 
# File 'lib/recurly/resource/pager.rb', line 69

def each
  return enum_for :each unless block_given?
  load! unless @collection
  @collection.each { |record| yield record }
end

#find(uuid) ⇒ Object 



163
164
165
166
167
168
169
170
 
# File 'lib/recurly/resource/pager.rb', line 163

def find uuid
  if resource_class.respond_to? :find
    raise NoMethodError,
      "#find must be called on #{resource_class} directly"
  end

  resource_class.from_response API.get("#{uri}/#{uuid}")
end

#find_each {|record| ... } ⇒ nil

Yields:

  • (record)

Returns:

  • (nil)

See Also:



78
79
80
81
82
83
 
# File 'lib/recurly/resource/pager.rb', line 78

def find_each
  return enum_for :find_each unless block_given?
  begin
    each { |record| yield record }
  end while self.next
end

#load! ⇒ Array? Also known as: reload

Returns Load (or reload) the pager’s collection from the original, supplied options.

Returns:

  • (Array, nil) —

    Load (or reload) the pager’s collection from the original, supplied options.



99
100
101
 
# File 'lib/recurly/resource/pager.rb', line 99

def load!
  load_from uri, @options
end

#new(attributes = {}) {|record| ... } ⇒ Resource

Instantiates a new record in the scope of the pager.

Examples:

 = Recurly::Account.find 'schrader'
subscription = .subscriptions.new attributes

Yields:

  • (record)

Returns:

See Also:

  • Resource.new


129
130
131
132
133
134
135
136
 
# File 'lib/recurly/resource/pager.rb', line 129

def new attributes = {}
  record = resource_class.send(:new, attributes) { |r|
    r.attributes[@parent.class.member_name] ||= @parent if @parent
    r.uri = uri
  }
  yield record if block_given?
  record
end

#next ⇒ Array?

Returns Refreshes the pager’s collection of records with the next page.

Returns:

  • (Array, nil) —

    Refreshes the pager’s collection of records with the next page.



87
88
89
 
# File 'lib/recurly/resource/pager.rb', line 87

def next
  load_from links['next'], nil if links.key? 'next'
end

#paginate(options = {}) ⇒ Pager Also known as: scoped, where

Returns Duplicates the pager, updating it with the options supplied. Useful for resource scopes.

Examples:

Recurly::Account.active.paginate :per_page => 20

Returns:

  • (Pager) —

    Duplicates the pager, updating it with the options supplied. Useful for resource scopes.

See Also:



109
110
111
112
113
114
 
# File 'lib/recurly/resource/pager.rb', line 109

def paginate options = {}
  dup.instance_eval {
    @collection = @count = @etag = nil
    @options.update options and self
  }
end

#respond_to?(method_name, include_private = false) ⇒ true, false

Returns:

  • (true, false)

See Also:

  • Object#respond_to?


174
175
176
 
# File 'lib/recurly/resource/pager.rb', line 174

def respond_to? method_name, include_private = false
  super || [].respond_to?(method_name, include_private)
end

#start ⇒ Array?

Returns Refreshes the pager’s collection of records with the first page.

Returns:

  • (Array, nil) —

    Refreshes the pager’s collection of records with the first page.



93
94
95
 
# File 'lib/recurly/resource/pager.rb', line 93

def start
  load_from links['start'], nil if links.key? 'start'
end

#uri ⇒ String

Returns The URI of the paginated resource.

Returns:

  • (String) —

    The URI of the paginated resource.



57
58
59
 
# File 'lib/recurly/resource/pager.rb', line 57

def uri
  @uri ||= resource_class.collection_path
end