Please turn on JavaScript. To find out how to do this visit the WebWise JavaScript guide.

Create an auto-suggest menu for an input element.

An AutoSuggest widget adds the ability for a text input element to make suggestions whilst the user types. This appears as a list of selectable items below the input element which dynamically updates based on what has been typed so far.

Widgets must be called in a glow.onReady() call.

Further Info & Examples

Constructor

new glow.widgets.AutoSuggest(inputElement, dataSource, opts)

Parameters

inputElement
Type
glow.dom.NodeList | String

A NodeList or css selector that points to a text input element.

dataSource
Type
Object[] | String[] | String | Function

Either an array of objects, an array of strings (referred to as a 'dataSource'), a function that returns a dataSource or a URL that when requested will return a dataSource.

opts
Type
Object

Optional configuration settings.

activeOnShow

Should the first suggestion automatically be active when the suggestion list appears?

Type
Boolean
Default
true
Optional
Yes
anim

Passed into the Overlay constructor for show and hide transitions.

Type
String | Function
Optional
Yes
caseSensitive

Whether case is important when matching suggestions.

Type
Boolean
Default
false
Optional
Yes
complete

Append the completed text of the currently active suggestion to the input text.

Type
Boolean
Default
false
Optional
Yes
delim

When defined, the input text will be treated as multiple values, separated by this string (with surrounding spaces ignored).

Type
String
Optional
Yes
formatItem

Given the matched data item, return HTML or NodeList.

Type
Function
Optional
Yes
height

Height in pixels of the suggestion container.

Type
Number
Optional
Yes
index

When datasource is an array of objects, the property with this string is used as the index, or this function will be used to generate the index.

Type
String[] | Function
Default
["name"]
Optional
Yes
isMatch

Provide a custom function to filter the dataset for results

Type
Function
Optional
Yes

Your function will be passed an indexed term and the term entered by the user, return true to confirm a match.

The default function will check the indexed term begins with the term entered by the user.

maxListLength

Limit the size of the result list to this.

Type
Number
Optional
Yes
onDataAbort

Your own handler for the dataAbort event.

Type
Function
Optional
Yes
onDataError

Your own handler for the dataError event.

Type
Function
Optional
Yes
onDataLoad

Your own handler for the dataLoad event.

Type
Function
Optional
Yes
onInputChange

Your own handler for the inputChange event.

Type
Function
Optional
Yes
onItemSelect

Your own handler for the itemSelect event.

Type
Function
Optional
Yes
parseData

Transform the response from the server into a dataSource object.

Type
Function
Optional
Yes

The server may return XML or even plain text, but your parseData function should convert this data into an array of objects.

Your function will be passed a glow.net.Response object from the server.

theme

Either "light" or "dark".

Type
string
Default
"light"
Optional
Yes
width

Width in pixels of the suggestion container. Default is the width of the inputElement.

Type
Number
Default
inputElement width
Optional
Yes

Examples

new glow.widgets.AutoSuggest(
  "#inputElementId",  // HTML input element to bind the AutoSuggest to
  ["Apple Flan", "Easy Shortbread", "Apple FlapJack", "Flambe of Brandied Apple Ice"] // Data source
);
myOpts = {
  width: 100,
  theme: "dark",
  maxListLength: "10",
  onItemSelect: function(e) {
    this.val(e.selectedItem.name); // Updates the binded HTML input element with the selected value
  }
}

myData = [
    {
        name: "Apple Flan"
    },
    {
        name: "Easy Shortbread"
    },
    {
        name: "Apple FlapJack"
    },
    {
        name: "Flambe of Brandied Apple Ice"
    }
];

myAutoSuggest = new glow.widgets.AutoSuggest(
  "#inputElementId", // HTML input element to bind the AutoSuggest to
  myData,
  myOpts
);
new glow.widgets.AutoSuggest(
  myInputElement,  // HTML input element to bind the AutoSuggest to
  "colornames.js", // URL to data
  myOpts
).loadData(); // load data from URL now

Properties

inputElement

Refers to the input element to which this is attached to.

Type
glow.dom.NodeList

Example

var myAutoSuggest = new glow.widgets.AutoSuggest(
      "input#preferedColour",
      "colornames.js"
);
alert(myAutoSuggest.inputElement); // returns a nodeList referencing input#preferedColour
overlay

Refers to the overlay object that will contain the list of suggestions.

Type
glow.widgets.Overlay

Example

var myAutoSuggest = new glow.widgets.AutoSuggest(
      "input#preferedColour",
      "colornames.js"
);
myAutoSuggest.overlay.show();

Methods

loadData

Cause the dataSource passed to the constructor to be set as the current data.

Synopsis

myAutoSuggest.loadData();

Returns

The instance of the widget.

Example

new glow.widgets.AutoSuggest(
  myInputElement,
  "colornames.js", // URL to data
  myOpts
).loadData(); // load data from URL now
setData

Update the data source

Synopsis

myAutoSuggest.setData(dataSource);

Parameters

dataSource
Type
Object[] | String | Function

New data source

Returns

The instance of the widget.

Description

If the dataSource is a URL it will be reloaded asynchronously.

Example

myAutoSuggest = new glow.widgets.AutoSuggest(
  myInputElement,
  "colornames.js", // URL to data
  myOpts
)
myAutoSuggest.setData("newColornames.js"); // Set data to new URL
myAutoSuggest.loadData(); // load data from new URL now
val

Sets or gets the value of the input element (minus any unaccepted completions).

Synopsis

myAutoSuggest.val(value);

Parameters

value
Type
string
Optional
Yes

If defined this value is set, otherwise the current value is returned.

Returns

The value of the input element when getting, or the instance of the widget when setting.

Example

new glow.widgets.AutoSuggest(
  "input#recipeName",  // refers to an input element on the page
  ["Apple Flan", "Easy Shortbread", "Apple FlapJack", "Flambe of Brandied Apple Ice"], // Data source
  {
    onItemSelect: function(e) {
      this.val(e.selectedItem.name); // Set input#reciptName to the value of the selected item
    }
  }
);

Events

inputChange

Fired whenever new suggestion appears based on changed input.

Synopsis

glow.events.addListener(myAutoSuggest, "inputChange", function(event) {
    // ...
});

Arguments

event
Type
glow.events.Event

Event Object

itemSelect

Fired whenever a suggestion is selected.

Synopsis

glow.events.addListener(myAutoSuggest, "itemSelect", function(event) {
    // ...
});

Arguments

event
Type
glow.events.Event

Event Object

selectedItem

The object in the dataSource that is associated with the selected list item.

Type
Object

The object in the dataSource that is associated with the selected list item.

dataLoad

Fired whenever raw data is loaded from a request to a URL.

Synopsis

glow.events.addListener(myAutoSuggest, "dataLoad", function(event) {
    // ...
});

Arguments

event
Type
glow.events.Event

Event Object

dataError

Fired whenever there is an errored request to a URL.

Synopsis

glow.events.addListener(myAutoSuggest, "dataError", function(event) {
    // ...
});

Arguments

event
Type
glow.events.Event

Event Object

dataAbort

Fired whenever there is an aborted request to a URL.

Synopsis

glow.events.addListener(myAutoSuggest, "dataAbort", function(event) {
    // ...
});

Arguments

event
Type
glow.events.Event

Event Object

Documentation generated by JsDoc Toolkit 2.1.0 on Mon Jul 20 2009 14:55:31 GMT+0100 (BST)

BBC navigation

BBC © 2014 The BBC is not responsible for the content of external sites. Read more.

This page is best viewed in an up-to-date web browser with style sheets (CSS) enabled. While you will be able to view the content of this page in your current browser, you will not be able to get the full visual experience. Please consider upgrading your browser software or enabling style sheets (CSS) if you are able to do so.