Custom Choosers

Hakawai supports custom chooser views, currently for Mentions but possibly for other plug-ins in the future. This page describes the specification for custom chooser views.

IMPORTANT: The information on this page is correct only for versions 3.*.* and up. It is not recommended that you attempt to create custom chooser views using older versions.

Custom Choosers

Custom chooser views must be subclasses of UIView, and implement the HKWChooserViewProtocol protocol.

You can implement a chooser view in one of two ways: Type A and Type B.

• A Type A chooser view implements the UI that shows options to the user using a UITableView. This sort of chooser view should implement the chooserViewWithFrame:delegate:dataSource: protocol factory method.

  If you are using chooser views in the context of the Mentions plug-in, this sort of chooser view relies upon the mentions delegate's cellForMentionsEntity:withMatchString:tableView: method (and other similar methods) for sourcing its cells. In this regard it functions much like the default chooser view.

• A Type B chooser view is completely responsible for its UI, and can be implemented in any way you see fit. This sort of chooser view should implement the chooserViewWithFrame:delegate: protocol factory method.

  If you are using chooser views in the context of the Mentions plug-in, you can set the mentions delegate's table view cell related methods to return nil or 0, since they will not be called at all.

Best Practices

Your custom chooser should use Auto Layout. If you are using Auto Layout and your custom chooser is defined programmatically, make sure to set translatesAutoresizingMaskIntoConstraints to NO for your chooser view and all its subviews.

If possible, avoid defining a fixed height and/or width for your custom chooser through constraints. Your chooser's height and width should be flexible; this is especially important if consumers want to use the Enclosed positioning modes, since the chooser view's constrained size will be determined by the size of its enclosing text view. If you are using the Custom positioning mode, your chooser view's final size will be determined by its constraints relative to its superview.

Chooser View Protocol

The HKWChooserViewProtocol is described below.

becomeVisible should show the chooser view, usually by setting its hidden property to NO. It should also perform any other work necessary to prepare the chooser view to be shown.

resetScrollPositionAndHide should hide the chooser view. If the chooser view is backed by a scrolling list, this method should also reset the scroll position. It should also perform any other work necessary before hiding the chooser view.

reloadData should cause the chooser view to assess whether or not the plug-in is loading data, and/or cause the UI that displays results to update itself. For example, a chooser view backed by a table view should call reloadData on its table view in turn.

NOTE that although both static factory methods are marked as optional, one of them must be implemented for the plug-in to work. Type A chooser views should implement chooserViewWithFrame:delegate:dataSource:; Type B chooser views should implement chooserViewWithFrame:delegate:.

borderMode is an optional property. It allows the plug-in to tell the chooser view whether any UI element that separates the chooser view from the section of the text view in question should be located at the top or the bottom of the chooser view.

chooserBackgroundColor is an optional property. It allows the application to set the background color of the chooser view (in a way that makes sense) through a plug-in API.

Custom Chooser View Delegate

Only for Type B chooser views, the HKWCustomChooserViewDelegate protocol provides your custom chooser view with an interface for retrieving data from the plug-in that created it.

shouldDisplayLoadingIndicator allows your chooser view to determine whether or not it is appropriate to display a loading indicator. Whenever reloadData is called on your chooser view you should check this property (if you are supporting loading indicators).

numberOfModelObjects returns the number of model objects your chooser view should display UI for.

modelObjectForIndex: returns an id-typed model object for the given 0-based index.

• If you are using your chooser view with Mentions, downcast the object to HKWMentionsEntityProtocol.

Call modelObjectSelectedAtIndex: to indicate to the plug-in that the user selected a UI element corresponding to the model at the specified index.