´óÏó´«Ã½

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