Inherits from NSObject
Declared in RKPaginator.h

Overview

Instances of RKPaginator retrieve paginated collections of mappable data from remote systems via HTTP. Paginators perform GET requests and use a patterned URL to construct a full URL reflecting the state of the paginator. Paginators rely on an instance of RKObjectMappingProvider to determine how to perform object mapping on the retrieved data. Paginators can load Core Data backed models provided that an instance of RKManagedObjectStore is assigned to the paginator.

Configuring Pagination Mapping

The paginator must be configured with a paginationMapping specifying how configuration metadata is to be mapped out of the response payload. The configured mapping must have an objectClass of RKPaginator and should include attribute mappings for the currentPage, pageCount, perPage, and objectCount. For example, given a paginated resource loaded from ‘/articles?page=1’ with the followibg JSON:

{ "pagination": { "per_page": 10, "total_pages": 25, "total_objects": 250 }, "articles": [ // Array of articles ] }

The pagination mapping would be configured as:

RKObjectMapping *paginationMapping = [RKObjectMapping mappingForClass:[RKPaginator class]];
[paginationMapping addAttributeMappingsFromDictionary:@{
    @"pagination.per_page":        @"perPage",
    @"pagination.total_pages":     @"pageCount",
    @"pagination.total_objects":   @"objectCount",
}];

iOS 5 Compatibility Caveats

The paginator is compatible with iOS 5.x through the use of proxy attributes. In iOS 6.0 and greater, key-value coding supports the automatic boxing and unboxing of primitive values. This enables direct mapping configuration for the currentPage, pageCount, perPage, and objectCount attributes. Under iOS 5, where autoboxing is not available, mapping configuration must target special proxy attributes instead. For each of the above properties, a private NSNumber property is implemented by the class. Each proxy property has ‘Number’ appended as a suffix to the property name: currentPageNumber, pageCountNumber, perPageNumber, and objectCountNumber.

Tasks

Initializing Paginator Objects

Configuring Networking

  •   patternURL

    A URL with a path pattern for building a complete URL from which to load the paginated resource collection. The patterned resource path will be evaluated against the state of the paginator object itself.

         property
  •   URL

    Returns a complete URL to the paginated resource collection by interpolating the state of the paginator object against the patternURL.

         property
  •   operationQueue

    An optional operation queue on which object request operations constructed by the paginator are to be enqueued for processing.

         property
  • – setHTTPOperationClass:

    Sets the RKHTTPRequestOperation subclass to be used when constructing HTTP request operations for requests dispatched by the paginator.

Setting the Completion Block

Accessing Pagination Results

  •   mappingResult

    The mapping result containing the last set of paginated objects or nil if an error was encountered.

         property
  •   error

    The error, if any, that occured during the last load of the paginator.

         property

Object Mapping Configuration

  •   paginationMapping

    The object mapping defining how pagination metadata is to be mapped from a paginated response onto the paginator object.

         property

Core Data Configuration

Accessing Pagination Metadata

  •   perPage

    The number of objects to load per page

         property
  •   loaded

    A Boolean value indicating if the paginator has loaded a page of objects

         property
  •   currentPage

    Returns the page number for the most recently loaded page of objects.

         property
  •   offset

    Returns the offset based off the page for the most recently loaded objects.

         property
  •   pageCount

    Returns the number of pages in the total resource collection.

         property
  •   objectCount

    Returns the total number of objects in the collection

         property
  • – hasPageCount

    Returns a Boolean value indicating if the total number of pages in the collection is known by the paginator.
  • – hasObjectCount

    Returns a Boolean value indicating if the total number of objects in the collection is known by the paginator.
  • – hasNextPage

    Returns a Boolean value indicating if there is a next page in the collection.
  • – hasPreviousPage

    Returns a Boolean value indicating if there is a previous page in the collection.

Paginator Actions

  • – loadNextPage

    Loads the next page of data by incrementing the current page, constructing an object loader to fetch the data, and object mapping the results.
  • – loadPreviousPage

    Loads the previous page of data by decrementing the current page, constructing an object loader to fetch the data, and object mapping the results.
  • – loadPage:

    Loads a specific page of data by mutating the current page, constructing an object loader to fetch the data, and object mapping the results.
  • – cancel

    Cancels an in-progress pagination request.

Properties

URL

Returns a complete URL to the paginated resource collection by interpolating the state of the paginator object against the patternURL.

@property (nonatomic, readonly) NSURL *URL

Declared In

RKPaginator.h

currentPage

Returns the page number for the most recently loaded page of objects.

@property (nonatomic, readonly) NSUInteger currentPage

Return Value

The page number for the current page of objects.

Exceptions

NSInternalInconsistencyException

Raised if isLoaded is equal to NO.

Declared In

RKPaginator.h

error

The error, if any, that occured during the last load of the paginator.

@property (nonatomic, strong, readonly) NSError *error

Declared In

RKPaginator.h

fetchRequestBlocks

An array of fetch request blocks.

@property (nonatomic, copy) NSArray *fetchRequestBlocks

Declared In

RKPaginator.h

loaded

A Boolean value indicating if the paginator has loaded a page of objects

@property (nonatomic, readonly, getter=isLoaded) BOOL loaded

Return Value

YES when the paginator has loaded a page of objects

Declared In

RKPaginator.h

managedObjectCache

The managed object cache used to find existing managed object instances in the persistent store.

@property (nonatomic, strong) id<RKManagedObjectCaching> managedObjectCache

Declared In

RKPaginator.h

managedObjectContext

The managed object context in which paginated managed objects are to be persisted.

@property (nonatomic, strong) NSManagedObjectContext *managedObjectContext

Declared In

RKPaginator.h

mappingResult

The mapping result containing the last set of paginated objects or nil if an error was encountered.

@property (nonatomic, strong, readonly) RKMappingResult *mappingResult

Declared In

RKPaginator.h

objectCount

Returns the total number of objects in the collection

@property (nonatomic, readonly) NSUInteger objectCount

Return Value

A count of the number of objects in the resource collection.

Exceptions

NSInternalInconsistencyException

Raised if hasObjectCount is NO.

Declared In

RKPaginator.h

offset

Returns the offset based off the page for the most recently loaded objects.

@property (nonatomic, readonly) NSUInteger offset

Return Value

The offset for the current page of objects.

Exceptions

NSInternalInconsistencyException

Raised if isLoaded is equal to NO.

Declared In

RKPaginator.h

operationQueue

An optional operation queue on which object request operations constructed by the paginator are to be enqueued for processing.

@property (nonatomic, strong) NSOperationQueue *operationQueue

Declared In

RKPaginator.h

pageCount

Returns the number of pages in the total resource collection.

@property (nonatomic, readonly) NSUInteger pageCount

Return Value

A count of the number of pages in the resource collection.

Exceptions

NSInternalInconsistencyException

Raised if hasPageCount is NO.

Declared In

RKPaginator.h

paginationMapping

The object mapping defining how pagination metadata is to be mapped from a paginated response onto the paginator object.

@property (nonatomic, strong) RKObjectMapping *paginationMapping

Discussion

See the documentation in the “Configuring Pagination Mapping” section for details about the pagination mapping.

Warning: The objectClass of the given mapping must be RKPaginator.

Declared In

RKPaginator.h

patternURL

A URL with a path pattern for building a complete URL from which to load the paginated resource collection. The patterned resource path will be evaluated against the state of the paginator object itself.

@property (nonatomic, readonly) NSURL *patternURL

Discussion

For example, given a paginated collection of data at the /articles path, the path portion of the pattern URL may look like:

/articles?per_page=:perPage&page_number=:currentPage

When the pattern is evaluated against the state of the paginator, this will yield a complete path that can be used to load the specified page. Given a paginator configured with 100 objects per page and a current page number of 3, the path portion of the pagination URL would become:

/articles?per_page=100&page_number=3

Declared In

RKPaginator.h

perPage

The number of objects to load per page

@property (nonatomic, assign) NSUInteger perPage

Declared In

RKPaginator.h

Instance Methods

cancel

Cancels an in-progress pagination request.

- (void)cancel

Declared In

RKPaginator.h

hasNextPage

Returns a Boolean value indicating if there is a next page in the collection.

- (BOOL)hasNextPage

Return Value

YES if there is a next page, otherwise NO.

Exceptions

NSInternalInconsistencyException

Raised if isLoaded or hasPageCount is NO.

Declared In

RKPaginator.h

hasObjectCount

Returns a Boolean value indicating if the total number of objects in the collection is known by the paginator.

- (BOOL)hasObjectCount

Return Value

YES if the paginator knows the number of objects in the paginated collection, otherwise NO.

Declared In

RKPaginator.h

hasPageCount

Returns a Boolean value indicating if the total number of pages in the collection is known by the paginator.

- (BOOL)hasPageCount

Return Value

YES if the paginator knows the page count, otherwise NO.

Declared In

RKPaginator.h

hasPreviousPage

Returns a Boolean value indicating if there is a previous page in the collection.

- (BOOL)hasPreviousPage

Return Value

YES if there is a previous page, otherwise NO.

Exceptions

NSInternalInconsistencyException

Raised if isLoaded is NO.

Declared In

RKPaginator.h

initWithRequest:paginationMapping:responseDescriptors:

Initializes a RKPaginator object with the a provided patternURL and mappingProvider.

- (id)initWithRequest:(NSURLRequest *)request paginationMapping:(RKObjectMapping *)paginationMapping responseDescriptors:(NSArray *)responseDescriptors

Parameters

request

A request with a URL containing a dynamic pattern specifying how paginated resources are to be acessed.

paginationMapping

The pagination mapping specifying how pagination metadata is to be mapped from responses.

responseDescriptors

An array of response descriptors describing how to map object representations loaded by object request operations dispatched by the paginator.

Return Value

The receiver, initialized with the request, pagination mapping, and response descriptors.

Declared In

RKPaginator.h

loadNextPage

Loads the next page of data by incrementing the current page, constructing an object loader to fetch the data, and object mapping the results.

- (void)loadNextPage

Declared In

RKPaginator.h

loadPage:

Loads a specific page of data by mutating the current page, constructing an object loader to fetch the data, and object mapping the results.

- (void)loadPage:(NSUInteger)pageNumber

Parameters

pageNumber

The page of objects to load from the remote backend

Declared In

RKPaginator.h

loadPreviousPage

Loads the previous page of data by decrementing the current page, constructing an object loader to fetch the data, and object mapping the results.

- (void)loadPreviousPage

Declared In

RKPaginator.h

setCompletionBlockWithSuccess:failure:

Sets the completion block to be invoked when the paginator finishes loading a page of results.

- (void)setCompletionBlockWithSuccess:(void ( ^ ) ( RKPaginator *paginator , NSArray *objects , NSUInteger page ))success failure:(void ( ^ ) ( RKPaginator *paginator , NSError *error ))failure

Parameters

success

A block to be executed upon a successful load of a page of objects. The block has no return value and takes three arguments: the paginator object, an array containing the paginated objects, and an integer indicating the page that was loaded.

failure

A block to be exected upon a failed load. The block has no return value and takes two arguments: the paginator object and an error indicating the nature of the failure.

Declared In

RKPaginator.h

setHTTPOperationClass:

Sets the RKHTTPRequestOperation subclass to be used when constructing HTTP request operations for requests dispatched by the paginator.

- (void)setHTTPOperationClass:(Class)operationClass

Discussion

Default: [RKHTTPRequestOperation class]

Declared In

RKPaginator.h