# Auto Complete 5.0 Documentation

## Note's about autoComplete

Namespaces autoComplete only requires control of 2 namespaces: jQuery.autoComplete & jQuery.fn.autoComplete. The 2 other namespaces(jQuery.expando & jQuery.fn.bgiframe) are used internally and default to their original values if defined. When not defined, jQuery.expando tries to find the expando defined first through jQuery event object, before creating one itself, and the jQuery.fn.bgiframe creates a useless non-chain breaking function.
While jQuery.fn.bgiframe can be redefined at any given time, it is a bad idea to try and redefine the jQuery.expando namespace after autoComplete has been initialized on elements. Doing so may or may not break the application, depending on the timing. Event Namespacing All normal event's are attached with the .autoComplete namespace, and all method's(made up event's) are attached to the autoComplete event namespace. In cases where a manual trigger is required, prefix the method with autoComplete, i.e: .trigger('autoComplete.namespace', args...). Passing array of argument's with method's autoComplete is flexible enough to pass an array of argument's, or list out argument's as needed. So .autoComplete('method', arg1, arg2, arg3) is the same as .autoComplete('method', [arg1, arg2, arg3]), and if needed, .autoComplete('method', arguments). Callback Functions Any callback functions defined through the settings have 3 properties attached to them:
1) The 'this' object reference's the element in focus(losing focus for blur event)
2) The first parameter contains the original event that was triggered.
3) The second parameter contains an object of argument's needed for that function.
This tries to conform to jQuery-ui's standards for callback functions, and allows for new feature's to be added while still being backwards compatible from this point on. For autoComplete versions 4.1 and lower, this new style will completely break those code bases. For those instances, a backwardsCompatible setting has been installed for an easier transition to the new style. Please update all code bases as this will be the new standard going forward.

## jQuery.autoComplete

Type
Key

###
Object
defaults

Contains a global object of the autoComplete settings. Both settings passed into the autoComplete function as a parameter and defined through metadata solution overwrite these global defaults.

###
Integer
length

Number of element's on the page that currently have autoComplete attached to them.

###
Boolean
hasFocus

Boolean key which is true when an input that has autoComplete attached is in focus, false otherwise.

###
Function
getFocus

Returns the element that is currently in focus.

###
Function
getPrevious

Returns the element that was previously in focus.

###
Function
getAll

Returns a jQuery object containing all elements that currently have autoComplete attached to them.

### Other Inner Operation Key's

The jQuery.autoComplete comes with a few more key variables that are operated on internally. Adjusting these value's is generally a bad idea, but if required, here are the docs:
-counter: Index counter. Gives a unique id to each element internally.
-stack: Object containing all element's with autoComplete attached to them, referenced by their unique id.
-order: Array containing list order of each element focus event.
-remove: Function that removes an input from the stack, takes the element's unique id as the parameter.

## Settings

Default
Name - Type

###
false
backwardsCompatible - Boolean

With version 5.0 and going forward, autoComplete will become more jqueryui standards compliant for event driven functions. With that, the parameter's passed to those functions have changed. To respect developers who are currently on 4.1, a backwardsCompatible setting has been implemented to ensure parameters passed to those functions remain constant. This is to ease the transition into 5.0 and beyond.
From 5.0 and on, autoComplete will be using this style so new feature's can easily be implemented while still be compatible with earlier versions.

###
'ajax.php'
ajax - String

URL of the server side script.

Note*: When dataSupply has a length greater than 0, no ajax request is sent.

###
jQuery.ajaxSettings.cache
ajaxCache - Boolean

Whether to allow browsers to cache ajax requests. Default's to jQuery's native settings.

###
false
autoFill - Boolean

Automatically fills the input with the focused list item. Best to use with a delay, as it's prone to quirks with fast typers.

###
50
cacheLimit - Integer

Limit's the number of entries stored in cache.

###
undefined
dataFn - Function(event, ui)

Personal function to use in place of default pattern matching. Return true for correct match, false for incorrect.

- The ui object
- search: Current value to be searching with.
- entry: Value of the entry in the dataSupply array.
- list: Holds the current values that have passed this functions pattern match.
- i: Current index of the array being searched.
- supply: The complete array currently being searched.
- ul: Cached $ul jQuery object of the drop down list.

Note*: with the backwardsCompatible flag enabled, the params are:
Function(search, entry, list, i, supply, ul, event).

###
[]
dataSupply - Array

Array of values/objects to run auto-complete as local instead of ajax requests. Default pattern match is: "/^(input value)/i"

###
100
delay - Integer

Time delay of when to send the ajax requests in milliseconds.

###
undefined
inputControl - Function(event, ui)

inputControl provides access to changing the name for cache storage. When doing pattern matching, or sending requests, the string returned by this function is used.

- The ui object
- val: Current inputval going to be used in search.
- key: The keyCode logged on the keyup event
- ul: Cached $ul jQuery object of the drop down list.

Note*: This function must return a string, which is either the 'val' key of the ui object or a modification of it.
Note2*: with the backwardsCompatible flag enabled, the params are:
Function(val, key, ul, event).

###
'auto-complete-list'
list - String

CSS Class that will be attached to the UL created.

###
-1
maxItems - Number

Limits the number of values added to the drop down list. When -1, no limit is imposed.

###
undefined
maxHeight - Number

Applies the max-height logic programmatically for browser's that don't support that css property.

###
0
maxRequests - Integer

Maximum number of ajax requests allowed within a scripts duration. If 0, no limit is applied

###
1
minChars - Integer

Minimum number of required characters to send a request.

###
false
multiple - Boolean

When true, multiple word inputs and word searching is allowed.

###
' '
multipleSeparator - String

Separator used between multiple words. Default's to an empty space, and is only active when the multiple option is true.

###
false
newList - Boolean

Defines whether to create a new UL drop down list for this instance, or use an existing one.

###
undefined
nonInput - Array

Array of character key codes not allowed. Remember to use keyCode's, not characters.

###
{}
postData - Object

Parameters that get passed to the server. The value defined by postVar will be overridden by the users input.

###
'value'
postVar - String

Name of the users input as it gets posted to the server.

###
true
preventEnterSubmit - Boolean

Prevents form submission when user selects a value from the UL drop down list using the enter key. This setting has been defaulted to true to conform to IE quirkiness. If the application requires form submission on enter, set this value to false to perform like so.

###
'POST'
requestType - String

Type of request during ajax calls. Only use 'GET' or 'POST'.

###
'auto-complete-list-rollover'
rollover - String

CSS Class toggled on li elements when mouseover or up/down events occur.

###
undefined
striped - String

CSS Class toggled on alternating li elements to give a zebra striped look.

###
true
useCache - Boolean

Tells autoComplete whether or not to use script level caching.

###
Input Width
width - Float

Width of the UL drop down list. Default's to the width of the Input field

## Event Callbacks

Note*: The this object references the input field currently in focus.

###
Empty Function
onBlur - Function(event, ui)

Callback function when the user loses focus on the input field.

- The ui object
- val: Last value you stored from the input.
- ul: Cached $ul jQuery object of the drop down list.

Note*: with the backwardsCompatible flag enabled, the params are:
Function(val, ul, event).

###
Empty Function
onFocus - Function(event, ui)

Callback function when the user focuses on the input field.

- The ui object
- ul: Cached $ul jQuery object of the drop down list.

Note*: with the backwardsCompatible flag enabled, the params are:
Function(ul).

###
undefined
onHide - Function(event, ui)

Callback function whenever the drop down list is closed.

- The ui object
- ul: Cached $ul jQuery object of the drop down list.

###
undefined
onLoad - Function(event, ui)

Callback function before the drop down list is loaded.

- The ui object
- list: Current list array that is about to be loaded into the list
- settings: Current settings attached to the input in focus
- cache: Current cache attached to the input in focus
- ul: Cached $ul jQuery object of the drop down list.

Note*: You must return the list array, with or without modifications made.

###
Empty Function
onMaxRequest - Function(event, ui)

Callback function when maximum number of ajax requests is reached. Will only fire if maxRequests is not 0.

- The ui object
- search: Value of the string that was going to be used in the search.
- ul: Cached $ul jQuery object of the drop down list.

Note*: with the backwardsCompatible flag enabled, the params are:
Function(search, ul, event, inputval).

###
Empty Function
onRollover - Function(event, ui)

Callback function when the user focuses one of the options of the UL drop down list.

- The ui object
- data: Data attached to that entry
- li: Cached $li jQuery object of the entry within the drop down list
- ul: Cached $ul jQuery object of the drop down list.

Note*: with the backwardsCompatible flag enabled, the params are:
Function(data, li, ul, event).

###
Empty Function
onSelect - Function(event, ui)

Callback function when the user selects an option from the UL drop down list.

- The ui object
- data: Data attached to that entry
- li: Cached $li jQuery object of the entry within the drop down list
- ul: Cached $ul jQuery object of the drop down list.

Note*: with the backwardsCompatible flag enabled, the params are:
Function(data, li, ul, event).

###
undefined
onShow - Function(event, ui)

Callback function when the drop down list is opened.

- The ui object
- ul: Cached $ul jQuery object of the drop down list.

###
Returns True
onSubmit - Function(event, ui)

Callback function called when form submission occurs. If preventEnterSubmit is enabled, the onSubmit method will only fire when the drop list is not active.

- The ui object
- form: Contains the parent form element of the input in focus.
- ul: Cached $ul jQuery object of the drop down list.

###
undefined
spinner - Function(active)

Callback function used to let developers know when to activate and deactivate any spinner's they want to run during requests.

- The ui object
- active: Current state of activity. True when spinner needs to be activated, false when spinner needs to be deactivated.
- ul: Cached $ul jQuery object of the drop down list.

## Methods (Event Triggers)

Auto-complete comes with a set of predefined method's that operate some common tasks. To trigger these events, use the normal autoComplete function initialization, with the string name of the event as the first parameter, along with any other parameters that are needed. Something like the following:

    	$('selector of input').autoComplete('method name', ...other params...);

### button-ajax - .autoComplete('button-ajax', postData, cacheName)

The button-ajax method allows for sending requests through an external trigger(button). It's required to pass a special cacheName is passed if more than one button-ajax method is used on the same input. If only one is used, an inner string of random characters will be used. This can enable a sort of select drop down functionality, where clicking a button can show the whole list, or users can just use the autoComplete to find their selection.

### button-supply - .autoComplete('button-supply', data, cacheName)

The button-supply method is essentially the same as the button-ajax method, except it works with a localized set of results instead of through ajax requests. Additionally, an optional second data parameter can be passed to supply a different set of results on just this event, instead of the normal set supplied during initialization. Also, if more than one method is in use for the same input, it is required to pass different cacheName's so caching of the data-set's don't override each other.

### destroy - .autoComplete('destroy')

Destroys the autoComplete initiation. Removes all events and data that were attached to the input, form, and document. Also, if the UL drop list was created through the function, and no other input's are using it, that element will be removed as well.

### direct-supply - .autoComplete('direct-supply', data, cacheName)

The direct-supply method bypasses list formatting and request delays, and loads either the data supplied to it, or the dataSupply data. This would be the fastest way to load a list directly into the drop down UL, but is prone to errors if the data passed to formatted incorrectly.

### disable - .autoComplete('disable')

Disables the autoComplete, but doesn't destroy it.

### enable - .autoComplete('enable')

Enables the autoComplete.

### flush - .autoComplete('flush', cacheOnly)

The flush event clears out the inner cache of results, as well as the number of requests made. And optional, second boolean parameter can be passed if only the cache needs to be flushed, not the number of requests made.

### option - .autoComplete('option', name, value)

The option method provides a way to get/set single settings.
-Passing both name and value parameters will set that option into the current settings.
-Passing just the name value returns that settings value. There are four keywords that return special objects: -Passing 'ul' will return the $ul object for the drop down list
-Passing 'cache' will return the current cache object
-Passing 'xhr' will return the last called xhr request
-Passing 'input' will return the current $input object.
-Passing no name or value parameter's will return the entire settings object.

Note*: Not passing the value parameter breaks the chain, as it utilizes jQuery's triggerHandler option to return the value return from the event function.

### search - .autoComplete('search', value)

The search method gives a programmatic way for triggering search with custom input. The 'value' parameter passed should contain a string for the custom search to be triggered.

### settings - .autoComplete('settings', newSettings)

The settings method allows for changes to the settings for that inputs autoComplete at any point of time. This can be very useful if the metadata plugin is not installed, yet separate functionality is needed for each input. Simply initiate the autoComplete on each input, and use the settings method to attach special parameters to each input's autoComplete instance.

Extra Functionality*: If a function is passed as the newSettings var, the inputs current settings and cache are passed to the function as parameters. Just return the array [newSettings, cache]. Here's the format:

    $('input selector').autoComplete('settings', function(settings, cache){
    	// ...Check or make changes to the current settings and cache here...
    	return [settings, cache];
    });