Version 1.5 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.
glow.onReady() 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
- caseSensitive
-
Whether case is important when matching suggestions.
- Type
- Default
- false
- Optional
- Yes
- 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
- formatItem
-
Given the matched data item, return HTML or NodeList.
- Type
- Optional
- Yes
- height
-
Height in pixels of the suggestion container.
- Type
- 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
- |
- 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.
- 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
- 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
- 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
