om-autocomplete

An autocomplete component for Om.

Examples

• Bootstrap (source) demonstrates basic usage of the built-in Twitter Bootstrap components. The suggestions recommended are just variants of the input text.

• Movies (source) uses a remote webservice to fetch suggestions. The service is down, so this demo doesn't currently work. Will update when I can replace it with another one.

Components

Here's a mockup of a basic autocompleter:

The arosequist.om-autocomplete namespace contains a single function, autocomplete, which is an Om component that handles the core autocomplete logic, but does not directly render any DOM elements. Instead, you give it three main components:

1. The container view just holds the other two components. Typically, this will render a simple wrapper div.
2. The input view is responsible for taking user input.
3. The results view displays the suggestions that were generated based on the input.

Some important terms are:

• The input has focus that is either true or false, normally corresponding to the normal HTML focus. You'll often want to hide the results when the input loses focus.
• The input also has a value ("uni" in the example). When this changes, the list of suggestions will be refreshed.
• A suggestion can be anything. Your results view just needs to know how to display it. In the example, each suggestion contains the flag and country name.
• The highlighted suggestion is usually changed by hovering the mouse or pressing the up/down arrow keys. Here, "United States" is the highlighted suggestion.
• A suggestion can be selected, typically by clicking the mouse or pressing enter. This usually signals the end of the autocomplete workflow.

Details

The options for autocomplete are (as keywords):

• result-ch: a channel that will receive an item once it's been selected.
• suggestions-fn: a function that calculates the suggestions for a given input. It takes three arguments: the input value, a channel to place the suggestions (as a single seq), and a channel that, when closed, indicates that the input changed and you should cancel fetching suggestions (when applicable).
• container-view: an Om component that will hold input-component and results-component.
• container-opts: any options that should be passed to the container-view.
• input-view: an Om component that will be responsible for taking user input. The state it receives will contain:
  • focus-ch: a channel that you should put true on whenever the input receives focus, and false when the input loses focus.
  • value-ch: a channel that you should put the user-supplied value onto when it changes.
  • highlight-ch: a channel that you should put the index of the highlighted item onto when it changes.
  • select-ch: a channel that you should put the index of an item onto when it's selected.
  • value: the current user-entered value.
  • highlighted-index: the index of the suggestion that's currently highlighted.
• input-view-opts: any options that should be passed to the input-view.
• results-view: an Om component that will be responsible for displaying autocompleted results. The state it receives will contain:
  • highlight-ch: a channel that you should put the index of an item onto when it's highlighted.
  • select-ch: a channel that you should put the index of an item onto when it's selected.
  • value: the current user-entered value.
  • loading?: a boolean that indicates if the suggestions are currently being loaded.
  • focused?: a boolean that indicates if the input is currently focused.
  • suggestions: the suggestions, as provided by the suggestions-fn.
  • highlighted-index: the index of the suggestion that's currently highlighted.
• results-view-opts: any options that should be passed to the results-view.

Bootstrap

om-autocomplete contains some convenience functions for pages that are using Twitter Boostrap. They are located in the arosequist.om-autocomplete.bootstrap namespace. TODO: More documentation here

Much of the code in this namespace isn't Bootstrap-specific, and I expect to create other helper namespaces for common use cases.