Ö÷²¥´óÐã

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

Version 1.7 glow.widgets.AutoSuggest

API Quick Reference

JavaScript is required to use the quick reference

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.ready() call.

Further Info & Examples

Constructor

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

Parameters

inputElement
Type
glow.dom.NodeList |

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

dataSource
Type
| | |

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

Optional configuration settings.

activeOnShow

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

Type
Default
true
Optional
Yes
anim

Passed into the Overlay constructor for show and hide transitions.

Type
|
Optional
Yes
autoPosition

Automatically position the suggestion list under the input element.

Type
Default
true
Optional
Yes

If you set autoPosition to false, you can position the suggestion list yourself in a handler for the show event of your AutoSuggest object.

caseSensitive

Whether case is important when matching suggestions.

Type
Default
false
Optional
Yes
className

Class names for the AutoSuggest's container element.

Type
Optional
Yes

This (or id) should be used if you're going to restyle the output, to ensure your restyling only changes the autosuggests you want to restyle.

complete

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

Type
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
Optional
Yes
filter

Filter matches found before they're displayed.

Type
Optional
Yes

Provide a callback function that can be used to modify an array of matching results before they are displayed. The callback receives a single argument, an array of objects corresponding to the objects in your data that are considered to match; expects you to return an array of objects modified as you wish.

formatItem

Given the matched data item, return HTML or NodeList.

Type
Optional
Yes
height

Height in pixels of the suggestion container.

Type
Optional
Yes
id

ID for the AutoSuggest's container element.

Type
Optional
Yes

This (or className) should be used if you're going to restyle the output, to ensure your restyling only changes the autosuggests you want to restyle.

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
|
Default
["name"]
Optional
Yes
isMatch

Provide a custom function to filter the dataset for results

Type
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
Optional
Yes
onDataAbort

Your own handler for the dataAbort event.

Type
Optional
Yes
onDataError

Your own handler for the dataError event.

Type
Optional
Yes
onDataLoad

Your own handler for the dataLoad event.

Type
Optional
Yes
onInputChange

Your own handler for the inputChange event.

Type
Optional
Yes
onItemSelect

Your own handler for the itemSelect event.

Type
Optional
Yes
parseData

Transform the response from the server into a dataSource object.

Type
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.

selectCompletedText

Set to false to prevent the widget from highlighting the completed text in the input element by selecting it.

Type
Default
true
Optional
Yes
theme

Either "light" or "dark".

Type
string
Default
"light"
Optional
Yes
useCache

Allow results to cache when using a url dataSource

Type
Default
false
Optional
Yes

If false, a random number will be added to the URL to ensure the results do not come from the browser's cache.

width

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

Type
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
| |

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

show

Fired when the suggestion list is about to open.

Synopsis

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

Arguments

event
Type
glow.events.Event

Event Object

hide

Fired when the suggestion list is about to close.

Synopsis

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

Arguments

event
Type
glow.events.Event

Event Object

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

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 2.1.0 on Thu Jul 07 2011 12:47:29 GMT+0100 (BST)

Ö÷²¥´óÐã iD

Ö÷²¥´óÐã navigation

Ö÷²¥´óÐã © 2014 The Ö÷²¥´óÐã 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.