class Koala::Facebook::API::GraphCollection

A light wrapper for collections returned from the Graph API. It extends Array to allow you to page backward and forward through result sets, and providing easy access to paging information.

Attributes

api[R]

@return [Koala::Facebook::GraphAPI] the api used to make requests.

headers[R]

The headers from the Facebook response

paging[R]

The raw paging information from Facebook (next/previous URLs).

raw_response[R]

The entire raw response from Facebook.

summary[R]

The raw summary information from Facebook (total counts).

Public Class Methods

evaluate(response, api) click to toggle source

@private Turn the response into a GraphCollection if they're pageable; if not, return the data of the original response. The Ads API (uniquely so far) returns a hash rather than an array when queried with get_connections.

   # File lib/koala/api/graph_collection.rb
44 def self.evaluate(response, api)
45   return nil if response.nil?
46 
47   is_pageable?(response) ? self.new(response, api) : response.data
48 end
is_pageable?(response) click to toggle source

response will always be an instance of Koala::HTTPService::Response since that is what we get from Koala::Facebook::API#api

   # File lib/koala/api/graph_collection.rb
52 def self.is_pageable?(response)
53   response.data.is_a?(Hash) && response.data["data"].is_a?(Array)
54 end
new(response, api) click to toggle source

Initialize the array of results and store various additional paging-related information.

@param [Koala::HTTPService::Response] response object wrapping the raw Facebook response @param api the Graph {Koala::Facebook::API API} instance to use to make calls

(usually the API that made the original call).

@return [Koala::Facebook::API::GraphCollection] an initialized GraphCollection

whose paging, summary, raw_response, and api attributes are populated.
Calls superclass method
   # File lib/koala/api/graph_collection.rb
30 def initialize(response, api)
31   super response.data["data"]
32   @paging = response.data["paging"]
33   @summary = response.data["summary"]
34   @raw_response = response.data
35   @api = api
36   @headers = response.headers
37 end
parse_page_url(url) click to toggle source

Parse the previous and next page URLs Facebook provides in pageable results. You'll mainly need to use this when using a non-Rails framework (one without url_for); to store paging information between page loads, pass the URL (from GraphCollection#paging) and use parse_page_url to turn it into parameters useful for {Koala::Facebook::API#get_page}.

@param url the paging URL to turn into graph_call parameters

@return an array of parameters that can be provided via graph_call(*parsed_params)

    # File lib/koala/api/graph_collection.rb
113 def self.parse_page_url(url)
114   uri = Addressable::URI.parse(url)
115 
116   base = uri.path.sub(/^\//, '')
117   params = CGI.parse(uri.query)
118 
119   new_params = {}
120   params.each_pair do |key,value|
121     new_params[key] = value.join ","
122   end
123   [base,new_params]
124 end

Public Instance Methods

next_page(extra_params = {}) click to toggle source

Retrieve the next page of results.

@param [Hash] extra_params Some optional extra parameters for paging. For supported parameters see developers.facebook.com/docs/reference/api/pagination/

@example With optional extra params

wall = api.get_connections("me", "feed", since: 1379593891)
wall.next_page(since: 1379593891)

@return a GraphCollection array of additional results (an empty array if there are no more results)

   # File lib/koala/api/graph_collection.rb
65 def next_page(extra_params = {})
66   base, args = next_page_params
67   base ? @api.get_page([base, args.merge(extra_params)]) : nil
68 end
next_page_params() click to toggle source

Arguments that can be sent to {Koala::Facebook::API#graph_call} to retrieve the next page of results.

@example

@api.graph_call(*collection.next_page_params)

@return an array of arguments, or nil if there are no more pages

   # File lib/koala/api/graph_collection.rb
86 def next_page_params
87   @paging && @paging["next"] ? parse_page_url(@paging["next"]) : nil
88 end
parse_page_url(url) click to toggle source

@private

    # File lib/koala/api/graph_collection.rb
101 def parse_page_url(url)
102   GraphCollection.parse_page_url(url)
103 end
previous_page(extra_params = {}) click to toggle source

Retrieve the previous page of results.

@param [Hash] extra_params Some optional extra parameters for paging. For supported parameters see developers.facebook.com/docs/reference/api/pagination/

@return a GraphCollection array of additional results (an empty array if there are no earlier results)

   # File lib/koala/api/graph_collection.rb
75 def previous_page(extra_params = {})
76   base, args = previous_page_params
77   base ? @api.get_page([base, args.merge(extra_params)]) : nil
78 end
previous_page_params() click to toggle source

Arguments that can be sent to {Koala::Facebook::API#graph_call} to retrieve the previous page of results.

@example

@api.graph_call(*collection.previous_page_params)

@return an array of arguments, or nil if there are no previous pages

   # File lib/koala/api/graph_collection.rb
96 def previous_page_params
97   @paging && @paging["previous"] ? parse_page_url(@paging["previous"]) : nil
98 end