Lightweight autocompleter plugin for Mootools
Switch branches/tags
Nothing to show
Pull request Compare This branch is even with weeby:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README.md
mootools-autocompleter-1.2-yc.js
mootools-autocompleter.js

README.md

Mootools Autocompleter

This is a lightweight autocompleter plugin for Mootools. It's designed to be attached to text input fields and provide them with a flexible autocompletion mechanism.

Initialization

In order to attach the widget to an input element you'd use code like this:

window.addEvent('domready', function() {
    var input = $('elementId'); // Or other means of getting a DOM element.
    var options = { 'source': dataSource };
    input.autocompleter(options);
});

While attaching itself to an element the widget will do some DOM operations that allow it operate.

Example HTML before attaching:

<div class="input text">
    <label>Choose a fruit</label>
    <input id="fruitSelect" type="text" name="fruit" />
</div>

Example HTML after attaching:

<div class="input text">
    <label>Choose a fruit</label>
    <input type="text" id="fruitSelect" class="mui-autocompleter-input " autocomplete="off" />
    <input type="hidden" name="fruit" value="134" />
</div>

Menu container is injected into <body> element and its HTML looks like this:

<div id="Autocompleter-fruitSelect" class="mui-autocompleter">
    <div class="mui-autocompleter-menu" style="display: none;">
        <ul></ul>
    </div>
</div>

Styling and positioning of the container is done entirely via CSS. JavaScript code performs no operations other than showing and hiding the menu container.

Default value

Since 1.2 the widget allows setting default value. To set it you need to modify input's markup before attaching the widget:

<input id="fruitSelect" type="text" name="fruit" data-autocompleter-default="<value>" value="<label>" />

Value of data-autocompleter-default attribute corresponds to value field of data source response and will be set as vallue to be sent with form. Value of value attribute will be visible in the text box.

Options

The widget's behavior can be configured using options you can provide when attaching the widget. You can also use option accessors to modify settings at runtime.

Available options:

  • id - ID for autocompleter menu wrapper DIV. If not supplied the widget will use input's attributes (name, id etc.) to create this attribute. Defaults to null.
  • className - HTML class name prefix used to attach classes to elements. Useful for cases where you'd like to have many autompleter widgets with different appearance. Defaults to mui-autocompleter.
  • delay - delay between the last keystroke and invoking the data source. Defaults to 300ms.
  • minLength - minimum length of text to search for. Defaults to 3 characters.
  • allowNewValues - boolean flag defining widget's behavior concerning not found strings. If true then the widget will treat not found text as value. Defaults to false.
  • source - data source for the widget.
  • onCreate, onSearch, onSuggest, onChange - pseudo-events.

Data source

The widget expects data source to be a function. It's invoked with text entered into the input as an argument.

Two behavior scenarios are now implemented:

  1. The function searches synchronously (e.g. in <select> options) and returns result.
  2. The function searches asynchronously (e.g. sends a request via AJAX to the backend) and upon completion calls the widget's suggest method.

Data format

The widget expects data source to respond with an array of objects.

JSON representation of an example response:

[
	{ "value": "apple", "label": "Apple", "html":"<img src=\"images\/apple.png\" \/><span>Apple<\/span>", "data": "arbitrary data to be attached to the item" }
]

Object fields:

  • value - value to be sent in the form,
  • label - text that will be put into the input after the element is selected,
  • html - optional HTML to be used in the menu instead of label text,
  • data - arbitrary data to be attached to the item.

Methods

The widget uses jQuery UI like logic for calling its methods and accessing its options.

Available methods:

  • value - getter for the widget's current value that'll be sent in the form,
  • option - getter and setter for configuration options,
  • suggest - used to pass an array of results to the widget and make it show the menu,
  • menu - returns DOM element of the menu container,
  • data - returns arbitrary data (if any) attached to the last selected item.

Calling methods is simple:

$('elementId').autocompleter('value'); // Returns value.
$('elementId').autocompleter('option', 'minLength'); // Returns minLength option.
$('elementId').autocompleter('option', 'minLength', 1); // Sets minLength option.
$('elementId').autocompleter('suggest', items); // Passes items to widget to show it in menu.

Events

The widget supports a number of pseudo-events that allow further integration with it. Event handlers are invoked with DOM element of the input that the widget wraps. To operate on the widget use methods described above.

Available events:

  • onCreate - executed right after the widget's initialization,
  • onSearch - executed before invoking the data source,
  • onSuggest - executed after the data source and bofore displaying the menu, regardless of search results,
  • onChange - executed after selecting one of suggestions, clearing the input or (if enabled) entering a not found text.

Compatibility

The widget has been tested on IE 7 and 8, Opera 11, Firefox 3.6 and 4, Google Chrome 8 and 10, Safari 5 on Windows and Mac OS X. It requires Mootools version 1.2 or 1.3. In case of 1.3 please use version with compatibility code.

Demo

See the plugin in action at http://weeby.github.com/Mootools-Autocompleter/

License

BSD License