RKPaginator Class Reference
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
Other Methods
-
– initWithRequest:paginationMapping:responseDescriptors:
Initializes a RKPaginator object with the a provided patternURL and mappingProvider.
-
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
Setting the Completion Block
-
– setCompletionBlockWithSuccess:failure:
Sets the completion block to be invoked when the paginator finishes loading a page of results.
Accessing Pagination Results
-
mappingResult
The mapping result containing the last set of paginated objects or
propertynil
if an error was encountered. -
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
-
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 -
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 toNO
.
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
isNO
.
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
isNO
.
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
Instance Methods
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