Page MenuHomeGitPull.it
Diviner Javelin Docs JX.Typeahead

class JX.Typeahead
Javelin Documentation ()

A typeahead is a UI component similar to a text input, except that it suggests some set of results (like friends' names, common searches, or repository paths) as the user types them. Familiar examples of this UI include Google Suggest, the Facebook search box, and OS X's Spotlight feature.

To build a JX.Typeahead, you need to do four things:

  1. Construct it, passing some DOM nodes for it to attach to. See the constructor for more information.
  2. Attach a datasource by calling setDatasource() with a valid datasource, often a JX.TypeaheadPreloadedSource.
  3. Configure any special options that you want.
  4. Call start().

If you do this correctly, a dropdown menu should appear under the input as the user types, suggesting matching results.

Tasks

Builtin Events

  • invoke(type, more) — Invoke a class event, notifying all listeners. You must declare the events your class invokes when you install it; see @{function:JX.install} for documentation. Any arguments you provide will be passed to listener callbacks.
  • static listen(type, callback) — Static listen interface for listening to events produced by any instance of this class. See @{method:listen} for documentation.

Building a Typeahead

  • construct(hardpoint, control) — Construct a new Typeahead on some "hardpoint". At a minimum, the hardpoint should be a ##<div>## with "position: relative;" wrapped around a text ##<input>##. The typeahead's dropdown suggestions will be appended to the hardpoint in the DOM. Basically, this is the bare minimum requirement:

Configuring a Datasource

  • setDatasource(datasource) — Configure a datasource, which is where the Typeahead gets suggestions from. See @{class:JX.TypeaheadDatasource} for more information. You must provide exactly one datasource.

Configuring Options

  • setInputNode(input) — Override the <input /> selected in the constructor with some other input. This is primarily useful when building a control on top of the typeahead, like @{class:JX.Tokenizer}.
  • setPlaceholder(string) — Set a string to display in the control when it is not focused, like "Type a user's name...". This string hints to the user how to use the control.

Activating a Typeahead

  • start() — Activate your properly configured typeahead. It won't do anything until you call this method!

Controlling Typeaheads from Javascript

  • hide() — Hide the typeahead's dropdown suggestion menu.
  • showResults(results, value) — Show a given result set in the typeahead's dropdown suggestion menu. Normally, you don't call this method directly. Usually it gets called in response to events from the datasource you have configured.
  • waitForResults() — Show a "waiting for results" UI. We may be showing a partial result set at this time, if the user is extending a query we already have results for.
  • doneWaitingForResults() — Hide the "waiting for results" UI.
  • clear()
  • enable()
  • disable()
  • submit()

Internal Methods

  • private _onmouse(event)
  • private _changeFocus(d)
  • private _drawFocus()
  • private _choose(target)
  • private _update(event)
  • handleEvent(e) — This method is pretty much internal but @{class:JX.Tokenizer} needs access to it for delegation. You might also need to delegate events here if you build some kind of meta-control.
  • updatePlaceholder() — Update the control to either show or hide the placeholder text as necessary.

Other Methods

Methods

invoke(type, more)
Inherited

JX.Base

Invoke a class event, notifying all listeners. You must declare the events your class invokes when you install it; see JX.install() for documentation. Any arguments you provide will be passed to listener callbacks.

Parameters
stringtypeEvent type, must be declared when class is installed.
...moreZero or more arguments.
Return
JX.EventEvent object which was dispatched.

static listen(type, callback)
Inherited

JX.Base

Listen for events emitted by this object instance. You can also use the static flavor of this method to listen to events emitted by any instance of this object.

See also listen() in JX.Stratcom.

JX.Base

Static listen interface for listening to events produced by any instance of this class. See listen() for documentation.

Parameters
stringtypeType of event to listen for.
functioncallbackFunction to call when this event occurs.
Return
objectA reference to the installed listener. You can later remove the listener by calling this object's remove() method.

construct(hardpoint, control)

Construct a new Typeahead on some "hardpoint". At a minimum, the hardpoint should be a <div> with "position: relative;" wrapped around a text

<input>##. The typeahead's dropdown suggestions will be appended to the

hardpoint in the DOM. Basically, this is the bare minimum requirement:

<div style="position: relative;">
  <input type="text" />
</div>

Then get a reference to the <div> and pass it as 'hardpoint', and pass the <input> as 'control'. This will enhance your boring old

<input />## with amazing typeahead powers.

On the Facebook/Tools stack, <javelin:typeahead-template /> can build this for you.

Parameters
Nodehardpoint"Hardpoint", basically an anchorpoint in the document which the typeahead can append its suggestion menu to.
Node?controlActual ##<input />## to use; if not provided, the typeahead will just look for a (solitary) input inside the hardpoint.

start()

Activate your properly configured typeahead. It won't do anything until you call this method!

Return
void

setDatasource(datasource)

Configure a datasource, which is where the Typeahead gets suggestions from. See JX.TypeaheadDatasource for more information. You must provide exactly one datasource.

Parameters
JX.TypeaheadDatasourcedatasourceThe datasource which the typeahead will draw from.

getDatasource()

This method is not documented.

setInputNode(input)

Override the <input /> selected in the constructor with some other input. This is primarily useful when building a control on top of the typeahead, like JX.Tokenizer.

Parameters
nodeinputAn <input /> node to use as the primary control.

hide()

Hide the typeahead's dropdown suggestion menu.

Return
void

showResults(results, value)

Show a given result set in the typeahead's dropdown suggestion menu. Normally, you don't call this method directly. Usually it gets called in response to events from the datasource you have configured.

Parameters
listresultsList of ##<a />## tags to show as suggestions/results.
stringvalueThe query this result list corresponds to.
Return
void

refresh()

This method is not documented.

waitForResults()

Show a "waiting for results" UI. We may be showing a partial result set at this time, if the user is extending a query we already have results for.

Return
void

doneWaitingForResults()

Hide the "waiting for results" UI.

Return
void

private _onmouse(event)

This method is not documented.
Parameters
event

private _changeFocus(d)

This method is not documented.
Parameters
d

private _drawFocus()

This method is not documented.

private _choose(target)

This method is not documented.
Parameters
target

clear()

This method is not documented.

enable()

This method is not documented.

disable()

This method is not documented.

submit()

This method is not documented.

setValue(value)

This method is not documented.
Parameters
value

getValue()

This method is not documented.

private _update(event)

This method is not documented.
Parameters
event

handleEvent(e)

This method is pretty much internal but JX.Tokenizer needs access to it for delegation. You might also need to delegate events here if you build some kind of meta-control.

Reacts to user events in accordance to configuration.

Parameters
JX.EventeUser event, like a click or keypress.
Return
void

removeListener()

This method is not documented.

setPlaceholder(string)

Set a string to display in the control when it is not focused, like "Type a user's name...". This string hints to the user how to use the control.

When the string is displayed, the input will have class "jx-typeahead-placeholder".

Parameters
stringstringPlaceholder string, or null for no placeholder.
Return
this

updatePlaceholder()

Update the control to either show or hide the placeholder text as necessary.

Return
void
Defined
lib/control/typeahead/Typeahead.js:39
Extends
JX.Base
Public contents are in Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) or GNU Free Documentation License (at your option) unless otherwise noted. · Contact / Register