Inherits from NSObject
Declared in MMServerPageManager.h
MMServerPageManager.m

Overview

MMServerPageManager encapsulates the logic for representing the current page from a given request’s response. Further, it provides access to the next and previous pages via the URN’s to those resources. This class should be treated as an interface and subclassed for a server’s specific implementation of pagination

Pagination Best Practice

The best practice for pagination is considered to be that the server will return the URN’s for the next and previous page. This removes the need for additional logic on the client side to determine the next URN they should call to retrieve more data.

Subclassing Notes

This class is required to be subclassed. There is no default implementation. It is completely up to the user to implement functionality that conforms to the below interface. You are responsible for maintaining the internal structure of this object such that the methods below will function as desired when they are called. You must override the designated initializer.

Tasks

Server Request Properties

  •   requestData

    The data used to make the request which the page manager will represent

         property
  •   requestURN

    The URN used to make the request which the page manager will represent

         property
  •   recordClass

    The record class which started the request which the page manager will represent

         property

Designated Initializer

Defining the Request for the Next Page

  • – canRequestNextPage

    This method should return YES if there is a next page to request and NO if there is not a next page to request. The default implementation of this method returns NO if the nextPageURN is nil or NULL and otherwise returns YES.
  • – nextPageURN

    This method should be implemented one of two ways. In the best case it will simply return the next page URN as returned by the server. Alternatively, if you wish to use request parameters, then you should return the original request URN and then modify the requestData object and return it in nextPageData.
  • – nextPageData

    This method should be implemented one of two ways. If your API gives you the next page URN in the response then simply return nil. Otherwise it may be easier to modify the original request’s requestData object to change the page index parameter to request the next page.

Metadata Describing the Current Page

  • – totalResultsCount

    The total number of results. This should be the same regardless of which page you’re on for a given set of results.
  • – resultsPerPage

    The number of results per page. This should also be the same regardless of which page you’re on, except possibly for the last page.
  • – currentPageIndex

    The index of the current page. The value returned by this method may need to be computed in some cases from the number of results and size per page depending on the values returned by the API.

Next Page Request Convenience

  • – startNextPageRequestWithContext:domain:resultBlock:failureBlock:

    This method starts a request for the next page. This is intended to be used in two ways. MMRecord’s pagination support provides a convenience variable for starting the request for the next page after a given page’s request has finished. If that convenience variable is set then this method will be called. The other common case is that the first page of results are used to populate a list and the list scrolls down and the next set of results need to be fetched. If the caller of the original request holds a reference to this page manager object then it is then simple for them to lazily start the next page request to get the next set of data to populate the list. This method should be implemented by calling the startPagedRequest method on the MMRecord class property of the page manager. The best case implementation would be to pass through the following parameters to the startPagedRequest method as well as the nextPageURN/nextPageData from the page manager.

Properties

recordClass

The record class which started the request which the page manager will represent

@property (nonatomic, strong, readonly) Class recordClass

Discussion

The record class which started the request which the page manager will represent

Declared In

MMServerPageManager.h

requestData

The data used to make the request which the page manager will represent

@property (nonatomic, copy, readonly) NSDictionary *requestData

Discussion

The data used to make the request which the page manager will represent

Declared In

MMServerPageManager.h

requestURN

The URN used to make the request which the page manager will represent

@property (nonatomic, copy, readonly) NSString *requestURN

Discussion

The URN used to make the request which the page manager will represent

Declared In

MMServerPageManager.h

Instance Methods

canRequestNextPage

This method should return YES if there is a next page to request and NO if there is not a next page to request. The default implementation of this method returns NO if the nextPageURN is nil or NULL and otherwise returns YES.

- (BOOL)canRequestNextPage

Return Value

YES if there is a next page

Discussion

This method should return YES if there is a next page to request and NO if there is not a next page to request. The default implementation of this method returns NO if the nextPageURN is nil or NULL and otherwise returns YES.

Declared In

MMServerPageManager.h

currentPageIndex

The index of the current page. The value returned by this method may need to be computed in some cases from the number of results and size per page depending on the values returned by the API.

- (NSInteger)currentPageIndex

Return Value

The current page index.

Discussion

The index of the current page. The value returned by this method may need to be computed in some cases from the number of results and size per page depending on the values returned by the API.

Declared In

MMServerPageManager.h

initWithResponseObject:requestURN:requestData:recordClass:

Initializes a page manager object to represent the current page of a request’s response.

- (instancetype)initWithResponseObject:(NSDictionary *)dict requestURN:(NSString *)requestURN requestData:(NSDictionary *)requestData recordClass:(Class)recordClass

Parameters

dict

The response object dictionary. This will be used to obtain the relevent pagination data.

requestURN

The URN used to make the request.

requestData

The data parameters used to make the request.

recordClass

The MMRecord class which started the request.

Return Value

The newly-initialized MMServerPageManager subclass instance.

Discussion

Initializes a page manager object to represent the current page of a request’s response.

Warning: You must be sure to call super of this initializer to make sure you set the server request properties correctly on initialization.

Warning: You must also override this initializer to implement any custom properties or other data structures that will support your implementation of this class.

Declared In

MMServerPageManager.h

nextPageData

This method should be implemented one of two ways. If your API gives you the next page URN in the response then simply return nil. Otherwise it may be easier to modify the original request’s requestData object to change the page index parameter to request the next page.

- (NSDictionary *)nextPageData

Return Value

the dictionary containing parameters for requesting the next page

Discussion

This method should be implemented one of two ways. If your API gives you the next page URN in the response then simply return nil. Otherwise it may be easier to modify the original request’s requestData object to change the page index parameter to request the next page.

Declared In

MMServerPageManager.h

nextPageURN

This method should be implemented one of two ways. In the best case it will simply return the next page URN as returned by the server. Alternatively, if you wish to use request parameters, then you should return the original request URN and then modify the requestData object and return it in nextPageData.

- (NSString *)nextPageURN

Return Value

the URN for the next page

Discussion

This method should be implemented one of two ways. In the best case it will simply return the next page URN as returned by the server. Alternatively, if you wish to use request parameters, then you should return the original request URN and then modify the requestData object and return it in nextPageData.

Declared In

MMServerPageManager.h

resultsPerPage

The number of results per page. This should also be the same regardless of which page you’re on, except possibly for the last page.

- (NSInteger)resultsPerPage

Return Value

The number of results per page.

Discussion

The number of results per page. This should also be the same regardless of which page you’re on, except possibly for the last page.

Declared In

MMServerPageManager.h

startNextPageRequestWithContext:domain:resultBlock:failureBlock:

This method starts a request for the next page. This is intended to be used in two ways. MMRecord’s pagination support provides a convenience variable for starting the request for the next page after a given page’s request has finished. If that convenience variable is set then this method will be called. The other common case is that the first page of results are used to populate a list and the list scrolls down and the next set of results need to be fetched. If the caller of the original request holds a reference to this page manager object then it is then simple for them to lazily start the next page request to get the next set of data to populate the list. This method should be implemented by calling the startPagedRequest method on the MMRecord class property of the page manager. The best case implementation would be to pass through the following parameters to the startPagedRequest method as well as the nextPageURN/nextPageData from the page manager.

- (void)startNextPageRequestWithContext:(NSManagedObjectContext *)context domain:(id)domain resultBlock:(void ( ^ ) ( NSArray *objects , id pageManager , BOOL *requestNextPage ))resultBlock failureBlock:(void ( ^ ) ( NSError *error ))failureBlock

Parameters

context

The context with which to start the request. This should be passed to MMRecord’s startPagedRequest method.

domain

The domain that this request should be associated with.

resultBlock

A block object to be executed when the request finishes successfully. This should be passed to MMRecord’s startPagedRequest method.

failureBlock

A block object to be executed when the request finishes unsuccessfully. This should be passed to MMRecord’s startPagedRequest method.

Discussion

This method starts a request for the next page. This is intended to be used in two ways. MMRecord’s pagination support provides a convenience variable for starting the request for the next page after a given page’s request has finished. If that convenience variable is set then this method will be called. The other common case is that the first page of results are used to populate a list and the list scrolls down and the next set of results need to be fetched. If the caller of the original request holds a reference to this page manager object then it is then simple for them to lazily start the next page request to get the next set of data to populate the list. This method should be implemented by calling the startPagedRequest method on the MMRecord class property of the page manager. The best case implementation would be to pass through the following parameters to the startPagedRequest method as well as the nextPageURN/nextPageData from the page manager.

Declared In

MMServerPageManager.h

totalResultsCount

The total number of results. This should be the same regardless of which page you’re on for a given set of results.

- (NSInteger)totalResultsCount

Return Value

The total number of results.

Discussion

The total number of results. This should be the same regardless of which page you’re on for a given set of results.

Declared In

MMServerPageManager.h