Skip to content

Mentions

Jump to bottom
Austin Zheng edited this page Feb 19, 2015 · 8 revisions

Mentions

Mentions is a plug-in for Hakawai. It allows drop-in support for annotations similar in style to social media mentions.

There are a number of ways to use Mentions. The simplest way is to rely upon the included UI elements and simply implement the methods described in HKWMentionsDelegate. However, if you wish you can provide your own UI elements. Both techniques are described below.

Overview

Mentions works in the following manner: as the user types text into the text view, the mentions plug-in listens for a start condition. Start conditions are configurable, and can be one of two things:

  • The user types in a control character such as @; this starts an explicit mention
  • The user types a number of consecutive non-whitespace characters; this starts an implicit mention

Once the start condition is met, Mentions queries a delegate provided by your app with a text string and some other metadata. Your app's responsibility, in broad strokes, is to take that search string and to turn it into an array of result objects. If there are results, Mentions displays a chooser view that allows the user to select an option. If the user does select an option, the chooser view is dismissed and the control character or text they typed is transformed into a mention.

A mention is a specially formatted piece of text. It shows up differently, can be set to 'light up' when the user places the insertion cursor within the mention, and is treated as an atomic unit. Deleting, changing, adding, cutting, pasting, or performing other options within a mention destroys it and changes it back to normal text.

Finally, the host app can query the mentions plug-in for a list of currently extant mentions objects within the text as well as their location.

Basic Setup

This section presumes you want to use the built-in chooser view. In order to set up a HKWTextView for use with mentions:

  1. Create a new mentions plug-in instance using one of the factory methods on HKWMentionsPlugin. The simplest of these is mentionsPluginWithChooserMode:; others are available that take more parameters for customization.

  2. Create an instance of a delegate object that implements the HKWMentionsDelegate protocol.

  3. Set the plug-in's delegate property to the delegate object.

  4. Set the HKWTextView's controlFlowPlugin property to your mentions plug-in instance.

Mentions Delegate

This section describes the HKWMentionsDelegate protocol in full detail. Your app must implement a delegate object; without a delegate the plug-in is useless.

Retrieving entities

asyncRetrieveEntitiesForKeyString:searchType:controlCharacter:completion: is the method the mentions plug-in uses to query your application:

  • keyString is the string that your application should search on. For example, if the key string is "Da", your app might decide to return results like "Danielle", "Darius", "David", "Devon", etc. Note that the key string can be empty; it is up to your app to decide how to handle that case.
  • type is either HKWMentionsSearchTypeImplicit, which means that the user started an implicit mention, or HKWMentionsSearchTypeExplicit, which means the user started an explicit mention.
  • character is only applicable if type is Explicit. If so, it contains the control character used to start the mention (for example, @). Your app can use this to make decisions on what results to fetch.
  • completionBlock is a block your app should call once results are in.

completionBlock

The completion block provided to your delegate is your app's way of giving results back to the plug-in. You can call the block synchronously (returning results within the function call) or asynchronously. You can call the block one time or multiple times; the latter is useful if you wish to collect results from multiple sources.

You do not need to worry about whether the search string has expired or what state the mentions system is in. Simply call the block with the appropriate arguments when your results are in.

The block takes three arguments:

  • An NSArray of objects representing results. Objects in this array must conform to the HKWMentionsEntityProtocol protocol. Objects are presented in the chooser UI in the order in which they are provided in this array, so perform any sorting before calling the block.
  • A boolean that indicates whether the plug-in should dedupe results. This is most useful if you plan on calling the block multiple times with potentially overlapping data from various sources. If set to YES, deduplication will occur based on the entities' uniqueId.
  • A boolean that indicates whether or not this is the last set of results for the search string, meaning that the results should be finalized.

Finalizing results causes two things to happen: it removes any loading UI from the chooser view, if applicable, and it causes the plug-in to ignore any further attempts to call the block. Note that calling the block with an empty array will cause the plug-in to finalize the results, regardless of the value of the third argument.

Displaying UI

cellForMentionsEntity:withMatchString:tableView: is called on your delegate object when the built-in chooser view needs to display a table view cell for a particular result. It allows you to provide whatever UI you want, as long as your UI takes the form of a UITableViewCell.

This function is called with the following argument:

  • entity is the mentions entity the cell should represent. It conforms to HKWMentionsEntityProtocol.
  • matchString is the string the mentions data corresponds to. One possible use for this is highlighting the portion of an entity name that corresponds to the string the user typed in.
  • tableView is the table view the cell will be displayed within. It is provided so that you can call dequeueReusableCellWithIdentifier:.

heightForCellForMentionsEntity:tableView: is called on your delegate object when the built-in chooser view needs the height for a table view cell. If you plan on using a single cell to represent all your results, you can simply set this to return a constant value.

Optional

The following methods are optional, and can be implemented as you desire.

entityCanBeTrimmed: is called on your delegate object when the plug-in wants to know if a given mention can be 'trimmed'. Trimming is a feature of the mentions plug-in that allows the mention to be truncated if and only if the user taps 'Delete' while the cursor is at the end of the mention. For example, a full name can be 'trimmed' to just a first name.

trimmedNameForEntity: is called on your delegate object when the plug-in wants to know what the trimmed name of a mentions entity should be. If not implemented, the default behavior is to trim the entity down to the first word in its name, unless the name already contains no whitespace or newline characters, in which case the entity is not trimmed.

loadingCellForTableView: can be implemented if you want to provide a loading cell to display in the chooser view while results are being fetched. You must also implement heightForLoadingCellInTableView: for the loading cell functionality to be enabled.

heightForLoadingCellInTableView: should return the height for the loading cell. Again, this can be set to return a constant for all but the most esoteric use cases.

Mentions APIs

See [Mentions APIs](Mentions APIs) for more details.

Custom Chooser Views

In addition to the 'basic' use case, in which the application provides table view cells and results, the Mentions plug-in supports custom choosers. See [Custom Choosers](Custom Choosers) for detailed information on creating a custom chooser view for use with Mentions.

Once you have created a custom chooser view, the following step(s) can be used to register it to the plug-in:

  1. After instantiating the plug-in, set its chooserViewClass property to the class of your custom chooser.

Note that if you are planning to use Mentions with a Type B custom chooser view, you only need to provide a complete implementation for asyncRetrieveEntitiesForKeyString:searchType:controlCharacter:completion:. The two 'required' table view cell-related delegate methods in the HKWMentionsDelegate protocol will not be called, and can be implemented through stubs.

State Machine

See [Mentions State Machine](Mentions State Machine) for more information on how the Mentions plug-in state machine works.

Clone this wiki locally