About

Autocomplete plugin brings the classic autocomplete functionality to the TextExt ecosystem. The gist of functionality is when user starts typing in, for example a term or a tag, a dropdown would be presented with possible suggestions to complete the input quicker.

Examples

Options

Autocomplete plugin options are grouped under autocomplete when passed to the $().textext() function. For example:

$('textarea').textext({
    plugins: 'autocomplete',
    autocomplete: {
        dropdownPosition: 'above'
    }
})

autocomplete.dropdown.maxHeight ("100px")1.1

This option allows to specify maximum height of the dropdown. Value is taken directly, so if desired height is 200 pixels, value must be 200px.

autocomplete.dropdown.position ("below")

This option allows to specify position of the dropdown. The two possible values are above and below.

autocomplete.enabled (true)

This is a toggle switch to enable or disable the Autucomplete plugin. The value is checked each time at the top level which allows you to toggle this setting on the fly.

autocomplete.render (null)1.1

This option allows to override how a suggestion item is rendered. The value should be a function, the first argument of which is suggestion to be rendered and this context is the current instance of TextExtAutocomplete.

Click here to see a demo.

For example:

$('textarea').textext({
    plugins: 'autocomplete',
    autocomplete: {
        render: function(suggestion)
        {
            return '<b>' + suggestion + '</b>';
        }
    }
})

html.dropdown ('<div class="text-dropdown"><div class="text-list"/></div>')

HTML source that is used to generate the dropdown.

html.suggestion ('<div class="text-suggestion"><span class="text-label"/></div>')

HTML source that is used to generate each suggestion.

Events

Autocomplete plugin triggers or reacts to the following events.

getSuggestions

Autocomplete plugin triggers the getSuggestions event and expects to get results by listening for the setSuggestions event.

hideDropdown

Autocomplete plugin triggers and reacts to the hideDropdown to hide the dropdown if it’s already visible.

setSuggestions

Autocomplete plugin reacts to the setSuggestions event triggered by other plugins which wish to populate the suggestion items. Suggestions should be passed as event argument in the following format: { data : [ ... ] }.

Here’s how another plugin should trigger this event:

this.trigger('setSuggestions', { data : [ "item1", "item2" ] });

showDropdown

Autocomplete plugin triggers and reacts to the showDropdown to show the dropdown if it’s not already visible.

It’s possible to pass a render callback function which will be called instead of the default TextExtAutocomplete.renderSuggestions().

Here’s how another plugin should trigger this event with the optional render callback:

this.trigger('showDropdown', function(autocomplete)
{
    autocomplete.clearItems();
    var node = autocomplete.addDropdownItem('<b>Item</b>');
    node.addClass('new-look');
});

toggleDropdown1.1

Autocomplete plugin reacts to toggleDropdown event and either shows or hides the dropdown depending if it’s currently hidden or visible.

Methods

TextExtAutocomplete.addDropdownItem(html)

  • html {String} HTML to be inserted into the item.

Adds and returns HTML node to the bottom of the dropdown.

TextExtAutocomplete.addSuggestion(suggestion)

  • suggestion {Object} Suggestion item. By default expected to be a string.

Adds single suggestion to the bottom of the dropdown. Uses ItemManager.itemToString() to serialize provided suggestion to string.

TextExtAutocomplete.clearItems()

Removes all HTML suggestion items from the dropdown.

TextExtAutocomplete.clearSelected()

Removes selection highlight from all suggestion elements.

TextExtAutocomplete.containerElement()

Returns top level dropdown container HTML element.

TextExtAutocomplete.getSuggestions()

Prepears for and triggers the getSuggestions event with the { query : {String} } as second argument.

TextExtAutocomplete.init(core)

  • core {TextExt} Instance of the TextExt core class.

Initialization method called by the core during plugin instantiation.

TextExtAutocomplete.initPriority()

Returns initialization priority of the Autocomplete plugin which is expected to be greater than the Tags plugin because of the dependencies. The value is 200.

TextExtAutocomplete.isDropdownVisible()

Returns true if dropdown is currently visible, false otherwise.

TextExtAutocomplete.onAnyKeyUp(e)

  • e {Object} jQuery event.

Reacts to the anyKeyUp event triggered by the TextExt core.

TextExtAutocomplete.onBackspaceKeyPress(e)

  • e {Object} jQuery event.

Reacts to the backspaceKeyPress event triggered by the TextExt core.

TextExtAutocomplete.onBlur(e)

  • e {Object} jQuery event.

Reacts to the blur event triggered by the TextExt core.

TextExtAutocomplete.onClick(e)

  • e {Object} jQuery event.

Reacts to the click event triggered by the TextExt core.

TextExtAutocomplete.onDownKeyDown(e)

  • e {Object} jQuery event.

Reacts to the downKeyDown event triggered by the TextExt core.

TextExtAutocomplete.onEnterKeyPress(e)

  • e {Object} jQuery event.

Reacts to the enterKeyPress event triggered by the TextExt core.

TextExtAutocomplete.onEscapeKeyPress(e)

  • e {Object} jQuery event.

Reacts to the escapeKeyPress event triggered by the TextExt core. Hides the dropdown if it’s currently visible.

TextExtAutocomplete.onGetFormData(e, data, keyCode)

  • e {Object} jQuery event.

  • data {Object} Data object to be populated.

  • keyCode {Number} Key code that triggered the original update request.

Reacts to the getFormData event triggered by the core. Returns data with the weight of 100 to be less than the Tags plugin data weight. The weights system is covered in greater detail in the getFormData event documentation.

TextExtAutocomplete.onHideDropdown(e)

  • e {Object} jQuery event.

Reacts to the hideDropdown event and hides the dropdown if it’s already visible.

TextExtAutocomplete.onMouseOver(e)

  • e {Object} jQuery event.

Reacts to the mouseOver event triggered by the TextExt core.

TextExtAutocomplete.onSetSuggestions(e, data)

  • data {Object} Data payload.

Reacts to the setSuggestions event. Expects to recieve the payload as the second argument in the following structure:

{
    result : [ "item1", "item2" ],
    showHideDropdown : false
}

Notice the optional showHideDropdown option. By default, ie without the showHideDropdown value the method will trigger either showDropdown or hideDropdown depending if there are suggestions. If set to false, no event is triggered.

TextExtAutocomplete.onShowDropdown(e, renderCallback)

  • e {Object} jQuery event.

  • renderCallback {Function} Optional callback function which would be used to render dropdown items. As a first argument, reference to the current instance of Autocomplete plugin will be supplied. It’s assumed, that if this callback is provided rendering will be handled completely manually.

Reacts to the showDropdown event and shows the dropdown if it’s not already visible. It’s possible to pass a render callback function which will be called instead of the default TextExtAutocomplete.renderSuggestions().

If no suggestion were previously loaded, it will fire getSuggestions event and exit.

Here’s how another plugin should trigger this event with the optional render callback:

this.trigger('showDropdown', function(autocomplete)
{
    autocomplete.clearItems();
    var node = autocomplete.addDropdownItem('<b>Item</b>');
    node.addClass('new-look');
});

TextExtAutocomplete.onToggleDropdown(e) 1.1.0

  • e {Object} jQuery event.

Reacts to the ‘toggleDropdown` event and shows or hides the dropdown depending if it’s currently hidden or visible.

TextExtAutocomplete.onUpKeyDown(e)

  • e {Object} jQuery event.

Reacts to the upKeyDown event triggered by the TextExt core.

TextExtAutocomplete.positionDropdown()

Positions dropdown either below or above the input based on the autocomplete.dropdown.position option specified, which could be either above or below.

TextExtAutocomplete.renderSuggestions(suggestions)

  • suggestions {Array} List of suggestions to render.

Clears all and renders passed suggestions.

TextExtAutocomplete.scrollSuggestionIntoView(item)

  • item {HTMLElement} jQuery HTML suggestion element which needs to scrolled into view.

Scrolls specified HTML suggestion element into the view.

TextExtAutocomplete.selectFromDropdown()

Uses the value from the text input to finish autocomplete action. Currently selected suggestion from the dropdown will be used to complete the action. Triggers hideDropdown event.

TextExtAutocomplete.selectedSuggestionElement()

Returns the first suggestion HTML element from the dropdown that is highlighted as selected.

TextExtAutocomplete.setSelectedSuggestion(suggestion)

  • suggestion {Object} Suggestion object. With the default ItemManager this is expected to be a string, anything else with custom implementations.

Highlights specified suggestion as selected in the dropdown.

TextExtAutocomplete.suggestionElements()

Returns list of all the suggestion HTML elements in the dropdown.

TextExtAutocomplete.toggleNextSuggestion()

Selects next suggestion relative to the current one. If there’s no currently selected suggestion, it will select the first one. Selected suggestion will always be scrolled into view.

TextExtAutocomplete.togglePreviousSuggestion()

Selects previous suggestion relative to the current one. Selected suggestion will always be scrolled into view.

TextExtAutocomplete.withinWrapElement(element) 1.3.0

  • element {HTMLElement} element to check if contained by wrap element

Determines if the specified HTML element is within the TextExt core wrap HTML element.

Fork me on GitHub