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 | String
A NodeList or css selector that points to a text input element.
- dataSource
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.
- 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.
- 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.
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.
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
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
Event Object
- itemSelect
Fired whenever a suggestion is selected.
Synopsis
glow.events.addListener(myAutoSuggest, "itemSelect", function(event) { // ... });Arguments
- 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
Event Object
- dataError
Fired whenever there is an errored request to a URL.
Synopsis
glow.events.addListener(myAutoSuggest, "dataError", function(event) { // ... });Arguments
- event
Event Object
- dataAbort
Fired whenever there is an aborted request to a URL.
Synopsis
glow.events.addListener(myAutoSuggest, "dataAbort", function(event) { // ... });Arguments
- event
Event Object
