ASPaginator Class Reference

Inherits from	NSObject
Declared in	ASPaginator.h

Overview

Used for searching and paging through results of ASObject instances. Example usage:

   ASPaginator *paginator = [[ASPaginator alloc] initWithTargetClass:[ASTrack class]];

   [paginator search:@{@"q" : @"big band"}
             success:^(ASPaginator *paginator) {
                 // ...
             }
             failure:^(NSError *error) {
                 // ...
             }
    ];

See the Audiosocket searching API docs for what are allowable query parameters.

Tasks

Setting up a paginator

– initWithTargetClass:
Initialize this paginator for the class specified.

Accessing paginator state

per
Object per page to include in the result set. Can be specified before any request is performed.
property
page
Most recent page returned.
property
pages
Total number of pages available.
property
total
Total number of objects that are available.
property
isLoaded
YES if the paginator has been loaded.
property
loadedTotal
Total number of objects that have actually been loaded.
property
loading
Return YES if this paginator is currently issuing a request. Multiple simultaneous requests can not be performed.
property
– 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.
– hasLoadedAll
Return YES if all elements in the result set have been loaded.

Paging through results

– loadNextPageWithSuccess:failure:
Loads the next page. At least on load must have been done prior to this call. If there are no more pages this will still make the call and no more records will be retrieved.
– loadPreviousPageWithSuccess:failure:
Loads the previous page. At least on load must have been done prior to this call. If the current page is page 1 this will still make the call but no more records will be retrieved.
– loadPage:success:failure:
Loads the specified page. If a search has not been performed then no query parameters are used. If a search has been prior to calling this the page is loaded using those same parameters.
– cancel
Cancels an in-progress pagination request.

Accessing returned results

– objectAtIndex:
Return the object at the index specified. Must be less then the ‘loadedTotal’.
– objectForID:
Return the object that matches the objectID passed in from within the loaded objects. If no object has been loaded with that ID then nil is returned.

Searching

– search:success:failure:
Search for instances using params specified.
– searchToPage:params:success:failure:
Search for instances using params specified returning the page specified.
– searchWithEndpoint:params:page:success:failure:
Search for instances by issuing a request to the endpoint specified. This method is useful when retrieving nested collections such as [ASAlbum loadTracksWithSuccess:failure:].

Properties

isLoaded

YES if the paginator has been loaded.

@property (nonatomic, readonly) BOOL isLoaded

Declared In

ASPaginator.h

loadedTotal

Total number of objects that have actually been loaded.

@property (nonatomic, readonly) NSUInteger loadedTotal

Declared In

ASPaginator.h

loading

Return YES if this paginator is currently issuing a request. Multiple simultaneous requests can not be performed.

@property (nonatomic, readonly) BOOL loading

Declared In

ASPaginator.h

per

Object per page to include in the result set. Can be specified before any request is performed.

@property (nonatomic) NSUInteger per

Declared In

ASPaginator.h

total

Total number of objects that are available.

@property (nonatomic, readonly) NSUInteger total

Declared In

ASPaginator.h

Instance Methods

cancel

Cancels an in-progress pagination request.

- (void)cancel

Declared In

ASPaginator.h

hasLoadedAll

Return YES if all elements in the result set have been loaded.

- (BOOL)hasLoadedAll

Declared In

ASPaginator.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 the paginator has not loaded or know its current page number.

Declared In

ASPaginator.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 next page, otherwise NO.

Exceptions

NSInternalInconsistencyException: Raised if the paginator has not loaded or know its current page number.

Declared In

ASPaginator.h

initWithTargetClass:

Initialize this paginator for the class specified.

- (ASPaginator *)initWithTargetClass:(Class)objectClass

Parameters

objectClass: Class of objects to search for. Must be a subclass of ASObject.

Declared In

ASPaginator.h

loadNextPageWithSuccess:failure:

Loads the next page. At least on load must have been done prior to this call. If there are no more pages this will still make the call and no more records will be retrieved.

- (void)loadNextPageWithSuccess:(void ( ^ ) ( ASPaginator *paginator ))success failure:(void ( ^ ) ( NSError *error ))failure

Parameters

success: If supplied called when the next page has loaded. ‘self’ is passed to the supplied block.

failure: If supplied called when an error occurs issuing the request.

Declared In

ASPaginator.h

loadPage:success:failure:

Loads the specified page. If a search has not been performed then no query parameters are used. If a search has been prior to calling this the page is loaded using those same parameters.

- (void)loadPage:(NSUInteger)pageNumber success:(void ( ^ ) ( ASPaginator *ASPaginator ))success failure:(void ( ^ ) ( NSError *error ))failure

Parameters

pageNumber: Page to load. 1 is the first page.

success: If supplied called when the page has loaded. ‘self’ is passed to the supplied block.

failure: If supplied called when an error occurs issuing the request.

Declared In

ASPaginator.h

loadPreviousPageWithSuccess:failure:

Loads the previous page. At least on load must have been done prior to this call. If the current page is page 1 this will still make the call but no more records will be retrieved.

- (void)loadPreviousPageWithSuccess:(void ( ^ ) ( ASPaginator *paginator ))success failure:(void ( ^ ) ( NSError *error ))failure

Parameters

success: If supplied called when the previous page has loaded. ‘self’ is passed to the supplied block.

failure: If supplied called when an error occurs issuing the request.

Declared In

ASPaginator.h

objectAtIndex:

Return the object at the index specified. Must be less then the ‘loadedTotal’.

- (ASObject *)objectAtIndex:(NSInteger)index

Parameters

index: position of the object to return.

Declared In

ASPaginator.h

objectForID:

Return the object that matches the objectID passed in from within the loaded objects. If no object has been loaded with that ID then nil is returned.

- (ASObject *)objectForID:(NSInteger)objectID

Parameters

objectID: ID of the object to return.

Declared In

ASPaginator.h

search:success:failure:

Search for instances using params specified.

- (void)search:(NSDictionary *)params success:(void ( ^ ) ( ASPaginator *))success failure:(void ( ^ ) ( NSError *))failure

Parameters

params: Optional query parameters to search for. See the http://develop.audiosocket.com/v5-api docs for info on what valid parameters are for the given target class this ASPaginator is setup for.

success: If supplied invoked when the search successfully returns. The block is passed ‘self’.

failure: If supplied invoked when the search request encounters an error.

Declared In

ASPaginator.h

searchToPage:params:success:failure:

Search for instances using params specified returning the page specified.

- (void)searchToPage:(NSUInteger)page params:(NSDictionary *)params success:(void ( ^ ) ( ASPaginator *))success failure:(void ( ^ ) ( NSError *))failure

Parameters

page: Page of the result set to return.

params: Optional query parameters to search for. See the http://develop.audiosocket.com/v5-api docs for info on what valid parameters are for the given target class this ASPaginator is setup for.

success: If supplied invoked when the search successfully returns. The block is passed ‘self’.

failure: If supplied invoked when the search request encounters an error.

Declared In

ASPaginator.h

searchWithEndpoint:params:page:success:failure:

Search for instances by issuing a request to the endpoint specified. This method is useful when retrieving nested collections such as [ASAlbum loadTracksWithSuccess:failure:].

- (void)searchWithEndpoint:(NSString *)endpointName params:(NSDictionary *)params page:(NSUInteger)page success:(void ( ^ ) ( ASPaginator *))success failure:(void ( ^ ) ( NSError *))failure

Parameters

endpointName: Endpoint to issue request to. It should include the baseURL portion supplied to the [ASApi initWithBaseURL:token:] method.

params: Optional query parameters to search for. See the http://develop.audiosocket.com/v5-api docs for info on what valid parameters are for the given target class this ASPaginator is setup for.

page: Page of the result set to return.

success: If supplied invoked when the search successfully returns. The block is passed ‘self’.

failure: If supplied invoked when the search request encounters an error.

Declared In

ASPaginator.h