What is Typeahead?

Typeahead.js is a JavaScript library that retrieves data based on what the user is typing, and displays it as a dropdown selection list. KD Typeahead is a small library that easily enables the typeahead feature within Kinetic forms for data that is retrieved from bridges.

Features

• Enable typeahead functionality inside a form through the use of a field's render attributes and a page load event.
• Connect to any bridge.
• Display multiple bridge attributes in the results.
• Set multiple fields when an option is selected.

Requirements

• typeahead.js which must be downloaded separately if it's not already in your bundle
  • kd-typeahead.js
  • kd-typeahead.css
• A bridge that will retrieve the data used to build the typeahead options

Include JavaScript and CSS

The recommended practice for including JavaScript and CSS files, (typeahead.js, kd-typeahead.js, and kd-typeahead.css) is to add them to layout.jsp. Including files here will ensure the are accessible to all Kinetic Request Forms within the Bundle.

Bridged Resources

A Bridged Resource defines the search and data returned from it. One must be added to the Kinetic Request Form on which the typeahead will exist, or on a different form (such as a Shared Resource form) to which we can link.

Page Event Configuration

The form will need to have a load event that will initialize the typeahead functionality. Since the form loads after the document is loaded, we can't do this inside the bundle with the exception of overwriting the bundle.config.ready function. This is not recommended unless you are 100% sure that the bundle.config.ready function isn't used elsewhere, since the bundle can only have one bundle.config.ready function.

Create a Page Event of type Load. Enter any name you like, set the Action to Custom, and enter the following into the Run-If Condition field:
typeof typeAheadSearch === "function"
Leave the Bridged Resource field set to None and enter the following into the Code field:
typeAheadSearch(K('form'));
Save the event.

Search Field Configuration

The form must have a text field to which the typeahead functionality will be attached. We'll refer to this field as the search field from now on.

Required Attributes

The following render attributes are required and must be added to the search field to enable the typeahead.

• uses-typeahead: Set to any value to enable typeahead functionality. Do not leave the value blank.
• typeahead-bridged-resource: The name of the bridged resource which will fetch the data. If the bridged resource lives on another form, the typeahead-bridge-location will also be required.
• typeahead-attributes-to-show: Comma separated list of bridge attributes to show in the selection dropdown. The attributes will display in two columns.
  Ex: Full Name,Email
  The selection dropdown will show the value of Full Name and the value of Email.
• typeahead-attribute-to-set: The attribute from the bridge whose value will be set into the search field when an option is selected. This is the value that will be saved into the field. To set the values of other fields, see typeahead-fields-to-set below.

Optional Attributes

The following render attributes are optional and may be added to the search field to customize the functionality.

• typeahead-bridge-location: If the bridged resource exists on a different from, set the slug of that form into this render attribute.
• typeahead-query-field: If the bridged resource exists on a different from, set the name of the parameter field that the bridged resource is expecting.
• typeahead-additional-params: If the bridged resource requires additional parameters, you can define a comma separated map of bridge parameter fields to field names (prepended with FIELD::) or hard coded values (prepended with STRING::).
  Ex: Country Code=FIELD::Country,Department=STRING::HR
  This will spoof sending a Country Code field parameter to the bridged resource with the value taken from a field with the name Country, and will spoof sending a Department field parameter to the bridged resource with the value set to the string HR.
• typeahead-fields-to-set: Comma separated mapping of field names to bridge attributes. The bridge attribute values will be set into the corresponding fields.
  Ex: Email Address=Email,Phone Number=Telephone
  This will set the bridge attribute Email into the Email Address field of the form, and the bridge attribute Telephone into the Phone Number field of the form.
• typeahead-min-length: The minimum number of characters that need to be entered before the bridge call is performed. If set to 0, will perform the bridge call when the field gets focus with an empty string as the value. Defaults to 3.
• typeahead-fa-class: Font awesome icon class to show next to the search field. Defaults to fa-search.
• typeahead-placeholder: The placeholder text to show in the search field when it is empty. Defaults to "Start typing to begin your search...".
• typeahead-empy-message: The message the appears when no results are returned from the bridge call. Defaults to "No results found".
• typeahead-user-id-attribute: If performing a person search and you'd like to filter out the currently logged in user, set the bridge attribute that contains the username into this render attribute.

Accessibility

At this time, the html rendered by this library is not WCAG 2.1 AA compliant.