Inherits from NSObject
Conforms to STAPIClientDelegate
UISearchBarDelegate
UISearchDisplayDelegate
UITableViewDataSource
UITableViewDelegate
Declared in STSearchResultsObject.h
STSearchResultsObject.m

Overview

STSearchResultsObject is an abstract class the provides a generic way to integrate STAPIClient into an iOS application. It provides basic functionality for STAPIClient or at least an example of how one might integrate STAPIClient into an application.

The STSearchResultsObject itself is the delegate or dataSource for the following objects it manages:

  • delegate for the UISearchDisplayController
  • searchResultsDelegate for the UISearchDisplayController
  • searchResultsDataSource for the UISearchDisplayController
  • delegate for the UISearchBar
  • delegate for the STAPIClient

The standard workflow is to create a subclass of STSearchResultsObject and override the following methods:

The STSearchResultsObject provides some basic functionality out of the box. For example, handling the keyboard events for starting a suggest or search query. To support additional functionality the subclass will need to implement or override additional delegate and/or dataSource callbacks.

Another option is to change the delegate or dataSource on the objects managed by STSearchResultsObject to something else. When this approach is taken it is important to keep in mind that the helpful functionality automatically provided will either need to be reimplemented or the new delegate or dataSource will need to callback to STSearchResultsObject methods that already provide the functionality.

In order to provide rendering and click functionality for search result cells the various tableView delegate and dataSource methods will need to be overridden. Since it is likely existing projects already implement these methods in some other view controller the STSearchResultsObject could have its searchDisplayController.searchResultsDelegate and searchDisplayController.searchResultsDataSource pointed at that view controller. And it is always possible to callback to the STSearchResultsObject that are already

Here is a list of the delegate methods that STSearchResultsObject already impements with a short description of what it does and the helpful functionality it provides:

  • searchResultsDataSource for UISearchDisplayController
    • tableView:titleForHeaderInSection: – returns a section title based on the data returned by recordSectionOrder
    • numberOfSectionsInTableView: – returns the number of sections in the table view taking into account the current search scope
    • tableView:numberOfRowsInSection: – returns the number of rows in a given section taking into account the current search scope
    • searchBar:selectedScopeButtonIndexDidChange: –
  • delegate for UISearchDisplayController
    • searchDisplayController:shouldReloadTableForSearchString: – starts a timer that fires after 250ms at which point a suggest query will actually be sent to the server. This helps prevent a request being generated for each keystroke
    • searchDisplayController:didHideSearchResultsTableView: – the table view is dismissed so clear out the searchResultData
  • delegate for UISearchBar
    • searchBarTextDidEndEditing: – clears out the web request cache used to cache API requests
    • searchBarSearchButtonClicked: – sends a search query to the server and cancels any pending suggest timer
    • searchBar:selectedScopeButtonIndexDidChange: – reloads table view since the search scope has changed
  • delegate for STAPIClient

Tasks

Other Methods

Other Methods

Properties

client

The STAPIClient instance created and managed by the STSearchResultsObject.

@property (nonatomic, readonly, strong) STAPIClient *client

Discussion

The STAPIClient instance created and managed by the STSearchResultsObject.

Note: By default the client’s delegate is set to the STSearchResultsObject.

Declared In

STSearchResultsObject.h

controller

The controller passed to the designated initializer. This is the same as the UISearchDisplayControllers searchContentsController.

@property (nonatomic, readonly) UIViewController *controller

Discussion

The controller passed to the designated initializer. This is the same as the UISearchDisplayControllers searchContentsController.

Declared In

STSearchResultsObject.h

query

The query that most recently finished successfully.

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

Discussion

The query that most recently finished successfully.

Declared In

STSearchResultsObject.h

searchBar

The search bar that is managed by STSearchResultsObject.

@property (nonatomic, readonly, strong) UISearchBar *searchBar

Discussion

The search bar that is managed by STSearchResultsObject.

By default the search bar’s delegate is set to the STSearchResultsObject.

Declared In

STSearchResultsObject.h

searchDisplayController

The search display controller that will be managed by the STSearchResultsObject.

@property (nonatomic, readonly, strong) UISearchDisplayController *searchDisplayController

Discussion

The search display controller that will be managed by the STSearchResultsObject.

By default the search display controller’s delegate, searchResultsDelegate and searchResultsDataSource will be set to the STSearchResultsObject.

Declared In

STSearchResultsObject.h

searchResultData

The searched results from the last query that finished successfully.

@property (nonatomic, readonly, strong) NSDictionary *searchResultData

Discussion

The searched results from the last query that finished successfully.

Declared In

STSearchResultsObject.h

searchType

The type of query that recently finished successfully.

@property (nonatomic, readonly, assign) STSearchType searchType

Discussion

The type of query that recently finished successfully.

Declared In

STSearchResultsObject.h

Instance Methods

client:didFinishQuery:withResult:withType:

The client succesfully received the results of query from the server

- (void)client:(STAPIClient *)client didFinishQuery:(NSString *)query withResult:(NSDictionary *)result withType:(STSearchType)type

Parameters

client

Instance of STAPIClient making the request

query

The query string entered by the user

result

The NSDictionary representation of the search results

type

The type of search to be performed. Either a search or a suggest

Discussion

The client succesfully received the results of query from the server

Declared In

STAPIClient.h

clientEngineKey

This method should be overriden by subclasses to return

- (NSString *)clientEngineKey

Return Value

A NSString of the search engine that will be queried against

Discussion

This method should be overriden by subclasses to return

Declared In

STSearchResultsObject.h

clientRequestParameters:forQuery:withType:

Required delegate method that should return the search parameters that will be posted to the server. The possible search parameters can be found here http://swiftype.com/documentation/searching

- (NSDictionary *)clientRequestParameters:(STAPIClient *)client forQuery:(NSString *)query withType:(STSearchType)type

Parameters

client

Instance of STAPIClient making the request

query

The query string entered by the user

type

The type of search to be performed. Either a search or a suggest.

Return Value

dictionary of search parameters that will be JSON encoded and posted to the server

Discussion

Required delegate method that should return the search parameters that will be posted to the server. The possible search parameters can be found here http://swiftype.com/documentation/searching

Declared In

STAPIClient.h

init

This initializer will call initWithViewController: with nil.

- (id)init

Discussion

This initializer will call initWithViewController: with nil.

Declared In

STSearchResultsObject.m

initWithViewController:

This is the designated initilizer for STSearchResultsObject.

- (id)initWithViewController:(UIViewController *)controller

Parameters

controller

The controller that the search results will be presented over. This is the same as the UISearchDisplayControllers searchContentsController.

If nil is passed to controller then STSearchResultsObject will not create a UISearchDisplayController. It is then the responsibility of the subclass to provide UI that renders the search results.

Discussion

This is the designated initilizer for STSearchResultsObject.

Declared In

STSearchResultsObject.h

postClickAnalyticsWithDocumentId:

Posts analytics to the server for a click on a specific document.

- (void)postClickAnalyticsWithDocumentId:(NSString *)documentId

Parameters

documentId

This will be the property id from a search result record.

Discussion

Posts analytics to the server for a click on a specific document.

Declared In

STSearchResultsObject.h

recordForType:atIndex:

Helper for retrieving a record from searchResultData based on document type.

- (id)recordForType:(NSString *)type atIndex:(NSUInteger)index

Parameters

type

Document type which will be a key in the record section of the search results

index

Offset into the array

Return Value

Object of record for a specific document type. The default implementation will be a NSDictionary representation of the parsed response data for the record.

By default this will return a NSDictionary for the record. Subclasses may want to override this method to parse the NSDictionary into a custom Objective-C object.

This method does not require data provided by the method recordSectionOrder. This method will return an empty dictionary if the type couldn’t be found or if the index was out-of-bounds in the search result data.

Discussion

Helper for retrieving a record from searchResultData based on document type.

Declared In

STSearchResultsObject.h

recordSectionOrder

Subclasses override this method to provide an array of document type names and the order the document types should be rendered in the search results table view.

- (NSArray *)recordSectionOrder

Return Value

An array of NSString objects that represent the document type keys.

By default this method will return an empty array. This method is required to return the keys of the document types for various helper aspects of the STSearchResultsObject to work properly. It is required for recordTypeForSection: to return the document type for a particular section index. It is also required for the UITableViewDataSource methods numberOfSectionsInTableView: and tableView:numberOfRowsInSection: which are overridden by STSearchResultsObject to provide the section and row counts based on the search result data. The result of this method is also used when automatically setting up the search scope bar.

Every suggest or search query will contain a dictionary called record. Within record each key will be the name of the document type.

Discussion

Subclasses override this method to provide an array of document type names and the order the document types should be rendered in the search results table view.

Declared In

STSearchResultsObject.h

recordTypeForSection:

Determines the document types being presented in a specfic section of the table view.

- (NSString *)recordTypeForSection:(NSUInteger)index

Parameters

index

The section index being access

Return Value

The string at index

Depends on recordSectionOrder being specified.

This method will also correctly handle the case where the scope bar has been limited to a specfic document type and the table views only have a single section. In that case this method will look at which scope has been selected and look up the document type based on the scope filter.

Discussion

Determines the document types being presented in a specfic section of the table view.

Declared In

STSearchResultsObject.h

recordsForType:

Helper for retrieving an array of records from searchResultData based on document type.

- (NSArray *)recordsForType:(NSString *)type

Parameters

type

Document type which will be a key in the record section of the search results

Return Value

Array of records for a specific document type

By default this will return an array of NSDictionary representation of the parsed response data for the record. Subclasses may want to override this method to parse the NSDictionary objects into custom Objective-C objects.

This method does not require data provided by the method recordSectionOrder. This method will return an empty array if the type couldn’t be found in the search result data.

Discussion

Helper for retrieving an array of records from searchResultData based on document type.

Declared In

STSearchResultsObject.h

searchBarForResultObject

Provides subclasses with the ability to provide their own custom subclass of UISearchBar.

- (UISearchBar *)searchBarForResultObject

Return Value

Instance of UISearchBar used by the STSearchResultsObject and exposed with the searchBar property.

By default the STSearchResultsObject will provide an instance of STSearchBar.

Discussion

Provides subclasses with the ability to provide their own custom subclass of UISearchBar.

Declared In

STSearchResultsObject.h

shouldDisplaySearchScopeButtons

Indicates that the search bar should have the scope indicators set. STSearchResultsObject will automatically creating an “All” section and handling refreshing the table view when switching between sections.

- (BOOL)shouldDisplaySearchScopeButtons

Return Value

Boolean indicating whether or not the search bar’s scope indicators should be enabled.

The default value return is NO

Even if this method returns YES if the result of recordSectionOrder is an empty array or an array containing exactly one document type then the search bar’s scope bar will not be displayed.

Discussion

Indicates that the search bar should have the scope indicators set. STSearchResultsObject will automatically creating an “All” section and handling refreshing the table view when switching between sections.

Declared In

STSearchResultsObject.h