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
  •   objectRequestOperation

    Returns the last object request operation used by the paginator to load a page of objects.

    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
  •   managedObjectContext

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

    property
  •   managedObjectCache

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

    property
  •   fetchRequestBlocks

    An array of fetch request blocks.

    property

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.

    property
  •   hasObjectCount

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

    property
  •   hasNextPage

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

    property
  •   hasPreviousPage

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

    property

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

@property (nonatomic, readonly) NSURL *URL
Discussion

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

Declared In

RKPaginator.h

currentPage

@property (nonatomic, readonly) NSUInteger currentPage
Discussion

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

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

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

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

Declared In

RKPaginator.h

fetchRequestBlocks

@property (nonatomic, copy) NSArray *fetchRequestBlocks
Discussion

An array of fetch request blocks.

Declared In

RKPaginator.h

hasNextPage

@property (nonatomic, readonly) BOOL hasNextPage
Discussion

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

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

@property (nonatomic, readonly) BOOL hasObjectCount
Discussion

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

Return Value

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

Declared In

RKPaginator.h

hasPageCount

@property (nonatomic, readonly) BOOL hasPageCount
Discussion

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

Return Value

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

Declared In

RKPaginator.h

hasPreviousPage

@property (nonatomic, readonly) BOOL hasPreviousPage
Discussion

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

Return Value

YES if there is a previous page, otherwise NO.

Exceptions

NSInternalInconsistencyException

Raised if isLoaded is NO.

Declared In

RKPaginator.h

loaded

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

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

Return Value

YES when the paginator has loaded a page of objects

Declared In

RKPaginator.h

managedObjectCache

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

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

Declared In

RKPaginator.h

managedObjectContext

@property (nonatomic, strong) NSManagedObjectContext *managedObjectContext
Discussion

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

Declared In

RKPaginator.h

mappingResult

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

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

Declared In

RKPaginator.h

objectCount

@property (nonatomic, readonly) NSUInteger objectCount
Discussion

Returns the total number of objects in the collection

Return Value

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

Exceptions

NSInternalInconsistencyException

Raised if hasObjectCount is NO.

Declared In

RKPaginator.h

objectRequestOperation

@property (nonatomic, strong, readonly) RKObjectRequestOperation *objectRequestOperation
Discussion

Returns the last object request operation used by the paginator to load a page of objects.

Declared In

RKPaginator.h

offset

@property (nonatomic, readonly) NSUInteger offset
Discussion

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

Return Value

The offset for the current page of objects.

Exceptions

NSInternalInconsistencyException

Raised if isLoaded is equal to NO.

Declared In

RKPaginator.h

operationQueue

@property (nonatomic, strong) NSOperationQueue *operationQueue
Discussion

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

Declared In

RKPaginator.h

pageCount

@property (nonatomic, readonly) NSUInteger pageCount
Discussion

Returns the number of pages in the total resource collection.

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

@property (nonatomic, strong) RKObjectMapping *paginationMapping
Discussion

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

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

@property (nonatomic, readonly) NSURL *patternURL
Discussion

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.

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

@property (nonatomic, assign) NSUInteger perPage
Discussion

The number of objects to load per page

Declared In

RKPaginator.h

Instance Methods

cancel

- (void)cancel
Discussion

Cancels an in-progress pagination request.

Declared In

RKPaginator.h

initWithRequest:paginationMapping:responseDescriptors:

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

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

Parameters

request

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

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

- (void)loadNextPage
Discussion

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

Declared In

RKPaginator.h

loadPage:

- (void)loadPage:(NSUInteger)pageNumber
Discussion

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

Parameters

pageNumber

The page of objects to load from the remote backend

Declared In

RKPaginator.h

loadPreviousPage

- (void)loadPreviousPage
Discussion

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

Declared In

RKPaginator.h

setCompletionBlockWithSuccess:failure:

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

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

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:

- (void)setHTTPOperationClass:(Class)operationClass
Discussion

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

Default: [RKHTTPRequestOperation class]

Declared In

RKPaginator.h