Documentation for autocomplete-lhc

The easiest way to get started is to check the demos. Below each demo is a "show source" link that shows the code needed to construct an autocompleter with the options in the demo. What follows here is detailed documentation for the various constructor options, list events (e.g. item selection) and the AngularJS directive.

Constructing an Autocompleter

Options supported by both "search" (AJAX) and "prefetch" (non-AJAX) lists

• matchListValue - whether the field should validate its value against the list (default: false)
• maxSelect - (default 1) The maximum number of items that can be selected. Use '*' for unlimited.
• twoColumnFlow - (default: true) Whether to allow long lists to flow into two columns to show more of the list on the page.
• suggestionMode - an integer specifying what type of suggestion should be offered based on what the user has typed. The suggestion is placed as the top-most item in the list. If this is not specified, the default is [Def.Autocompleter.]SUGGEST_SHORTEST, which means "pick the shortest match." A value of NO_COMPLETION_SUGGESTIONS means no suggestions, and a value of USE_STATISTICS means that the suggestion is based on statistics, and that we will rely on the server to return the best item as the first item in the list.
• wordBoundaryChars - (default none) For autocompleting based on part of the field's value, this should be an array of the characters that are considered "word" boundaries (e.g. a space, but could be something else). When this option is used, maxSelect is ignored.
• headerBar - If the page has a fixed-position element at the top of the page (e.g. a top navigation bar), the autocompleter needs to know that so that when scrolling to show the list it doesn't scroll the current field under the header bar. This is the element ID for such a header bar.
• scrolledContainer - the element that should be scrolled to bring the list into view if it would otherwise extend below the edge of the window. The default is document.documentElement (i.e. the whole window). This may be null if no scrolling is desired (e.g. if the list field is in a fixed position on the window), but in that case the list element might be unusually short. Note: At present the only tested cases of this parameter are the default value and null.
• caseInsenstiveSelection - (default: true) If the user changes the field but leaves without picking an item, the list will check if what the field contains matches an item in the list and if so, will select it. This controls whether that matching is case-insensitive.

Constructing a "prefetch" (non-AJAX) autocompleter

new Def.Autocompleter.Prefetch(field, [array, of, items], options);

Constructing a "search" (AJAX) autocompleter

new Def.Autocompleter.Search(field, url, options);

Notifications

The autocompleter allows you to register callbacks for certain events. The source file autoCompEvents.js provides the full list; here we'll just document the list selection event, which is the most likely to be useful.

List Selection Events

Sometimes you might need to get notified when the user has picked a value from a list, or has entered a non-list value. In that case you can register a callback like this:

Def.Autocompleter.Event.observeListSelections(fieldKey, callback);

The parameters are as follows:

• fieldKey - This is usually the name (or ID) of the field, unless you have overridden Def.Observer.lookupKey (which you might do if you wanted the same callback to apply to multiple fields). Fields whose lookupKey() value matches fieldKey will trigger the callback for this event. This parameter can be null, in which case the function will be called for every event of this kind, regardless of the field for which it occurred.
• callback - the function to be called when the event occurs. The function will be called with a hash argument with the following keys:
  • val_typed_in (what the user actually typed in)
  • final_val (the final value for the field)
  • used_list (boolean indicating whether or not the final was selected from a list, whether by clicking or by arrows)
  • on_list - boolean indicating whether or not the final value was on the list
  • input_method ('clicked', 'arrows', or 'typed')
  • item_code - the code for the selected item, or null if there isn't a code
  • removed - For multi-select lists, this indicates whether the selection was actual an unselection, removing the named item from the list of selected items. When true, final_val is the removed value (although for multi-select fields the field is blank afterward). (Optional; default false)
  • list - the items that were in the list (which is the full list for a prefetched list, or the portion shown to the user for a search list).
  • field_id - the ID of the list field

Autocompleter APIs

The following sections document functions that can be called on instances of the autocompleter returned by the constructors above.

Getting the selection data

For simple use cases, getting what the user picked is as simple as looking in the field. For more complicated ones, APIs are provided for getting the code for the selected item, for getting selected items for multi-select lists (for which the field itself will be blank), and for getting the extra item data returned for a search list's AJAX call. These APIs are defined on the autocompleter instance, and if you don't have a reference to that, you can access it from the field's DOM element as element.autocomp

getSelectedItems()

Returns the display strings for the currently selected items or an empty array if there are none.

getSelectedCodes()

Returns the codes for the currently selected items or an empty array if there are none. If some of the selected items do not have a code, there will be null in that place in the returned array.

getSelectedItemData()

Returns all information about the currently selected list items, as an array of hashes, each with at least a "text" property for the item's display text. The hashes may also contain (if the data was provided) properties "code", "code_system", and "data" (which for search lists contains the "extra data" fields for that item). The return value will be null if there are no selected items.

getItemCode(itemText)

Returns the code for the given item text, or null if there isn't one. For search lists, itemText must be present in the list retrieved for the last character typed.

getItemData(itemText)

(For search lists only.)Returns a hash of all data about the given item, which must be among the items of the last list retrieved. The returned hash will have "code" and "text" properties for the selected item, and if there is any extra data for the item, that will be under a "data" sub-hash. If the items came with code system data, there will also be a "code_system" property with the code system corresponding to "code". Properties for which there are no values will not be present, except for the "text" property. Note that this data is also collected and returned by the getSelectedItemData() call above, which might be easier to use.

Prefetch list APIs

The following functions are availble on instance of the prefetch autocompleter.

setListAndField

If the prefetch list needs to be changed to a new list, you can do that with setListAndField([array of items], [array of codes]). If there is just one item in the new list, the field will be set to that value; otherwise the field value will be cleared.

setFieldToListValue

After constructing the prefetch list, the field value can be initialized with one of the list values by calling setFieldToListValue(fieldValue) where the "fieldValue" should be one of the list's display values. The autocompleter keeps track of what has been selected, so it is necessary to call this function rather than just assign to the .value attribute of the field.

preventListFromShowing

This is a property on the autocomplete instance. The using application can set this property to true to prevent the list from showing on focus or click.

AngularJS Directive

If you are using AngularJS, you can set up your autocompleters via directive. For example:

<input id="myfield" autocomplete-lhc="opts" ng-model="selectedVal">

The opts object contains the options normally passed into the constructor. (Note: As of version 8.0.0 of the autocompleter, this object is watched for changes, so if you return it via a function call, the function should return the same object unless the options really change.) As mentioned above, there are two types of autocompleters. You can either have a "prefetch" list where all the items are given to the autocompleter at construction time, or a "search" list where the list items are discovered as the user types, via AJAX calls. For both types, opts is a hash, but the keys on the hash differ.

For "prefetched lists", opts can contain:

• listItems - (required) This is the list item data. It should be an array, and each element in the array should have a "text" property which is the display string the user sees. The object containing that text property is what will get stored on the model you have associated via ng-model (selectedVal, in the example above). So, if you wish you can have other properties holding data about each item, and the whole object gets placed in the model when the user selects an item.
• maxSelect - (default: 1) the maximum number of items that can be selected from the list. If this is '*', an unlimited number can be selected. When more than one item can be selected, selected items are stored in an array on the model (e.g., selectedVal in the example above becomes an array).
• defaultValue - The default value for the field. This setting also exists in the non-directive prefetch lists, but there are two differences here:
  • defaultValue can either be one of the list item display strings (the "text" property), or it can be a hash like {code: 'AF-5'}, where "code" is a key on the list item object, and 'AF-5' is the value of that key to select the item as the default. This is to allow the default value to be specified not just by the display string, but by other attributes of the list item object.
  • the default list item is loaded into the field when the autocompletion is set up.
• Any other parameters used by the Def.Autocompleter.Prefetch constructor. (Look also at the options common to both types of autocompleter.

For "search" lists, opts can contain:

• url - (required) The URL to which requests for data should be sent. For details about expected query parameters and response data, see the comments for the url parameter for the Def.Autocompleter.Search constructor
• Any other parameters used by the Def.Autocompleter.Search constructor. (Look also at the options common to both types of autocompleter.