Examples

Setup

<div class="mk-ac-root">
	<input class="mk-ac" type="text" name="search" aria-label="Search for Stuff" placeholder="Search..." />
</div>

Configuration Options via Data-Attributes

There are two ways to configure Autocomplete, the first of which is by providing data attributes on the root input. Below is a list of all possible data attributes you may add to configure an instance. All data attributes are optional.

<div class="mk-ac-root">
	<input type="text"
		name="search"
		aria-label="Search for Stuff"
		<!-- Number of characters before filtering/requesting data. Default is 1. -->
		data-chars="3"
		<!-- Keeps the list of results open (after selecting) when set to true. Default is false. -->
		data-persistopen="true"
		<!-- time in milliseconds for a data request to kick off after user entry. Default is 300. -->
		data-time="500"
		<!-- total number of possible results a user can select. Default is 1. -->
		data-limit="4"
		<!-- Allow the user to enter, or 'select,' anything they like, including their own input. Default is true. -->
		data-anything="true"
		<!-- Allows commas to seperate user entered values and add them to the selection list. Default is false. -->
		data-comma="true"
		<!-- Allows searching any data fields, or omission of a default. Default is "value,label". -->
		data-searchkeys="label,myOtherField"
		<!-- Remove the tag UI. Default is false. -->
		data-notags="false"
		<!-- Allows delete (when text entry is '') to pop the last selected items from selections. -->
		<!-- Default is false for single select and true for more than one (limit > 1). -->
		data-doubledelete="true"
		placeholder="Search..." />
</div>

Instantiation

Below is an example of instantiating an Autocomplete. Like all other Mk components, the first argument is the root and the second is configuration options. In the example below, we've provided all possible config options, however, all config properties are completely optional.

//get autocomplete object
var Autocomplete = Mk.get('Autocomplete');
//
//create instance
var autocomplete = new Autocomplete('#selector', {
	//number of selections user is allowed. Default is 1
	limit: 1,
	//number of characters typed by user before kicking off a request/search. Default is 1
	chars: 3,
	//keeps the list of results open (after selecting) when set to true. Default is false.
	persistopen: true,
	//delay before trigering request events for data. Default is 300.
	time: 500,
	//allow the user to input/select anything (including anything they enter manually) Default is true.
	anything: true,
	//allows the doubledelete functionality to pop old selections. Default is true.
	doubledelete: false,
	//hide the tag UI. Default is false.
	notags: false,
	//allow comma seperated user input to be split and added to selections. Default is false.
	comma: true,
	//allows searching any data fields, or omission of a default. Default is "value,label".
	searchkeys: "label,myOtherField",
	//data you would like to provide on instantiation (vs. remote requests).
	//you can also do both static and remote data.
	data: [
		..predefined data set..
		{
			label: 'Example Result 1',
			value: 'my-result-key'
		}
	],
	//template overrides/additions
	templates: {
		..template overrides..
	},
	//format overrides/additions
	formats: {
		..format overrides..
	},
	//events you want bound
	events: {
		..you can bind events here or by using on() one() and off()..
	}
});

Dynamic Data and Remote Urls

Autocomplete does not take care of XMLHttpRequests, JSONP, or any other method of retrieving dynamic data to populate a users search. We do, however, provide the proper hooks for you to tie your own custom requests into the Autocomplete. This is actually great news. Now you can use whatever existing tools for remote requests your project is already using. Below is an example of a JSONP call using jQuery, which hooks into the Autocomplete system.

//get the autocomplete object
var Autocomplete = Mk.get('Autocomplete');
//
//create an instance
var autocomplete = new Autocomplete('.mk-ac-root' /*, options */);
//will keep refernece to our ajax request
var xhr;
//
// set the request.send and request.abort events
autocomplete.on('request.send', function (query, requestnum) {
	//notify screen readers and add optional loading indicator
	ac.notify(ac.NOTIFY_STATES.LOADING, query);
	//
	//you can use the 'requestnum'
	//to catch situations where an abort() procedure isn't possible.
	//see the success method for more info
	xhr = $.ajax({
		url: 'http://dev.markitondemand.com/Api/v2/Lookup/jsonp',
		data: {input: query},
		type: 'get',
		dataType: 'jsonp',
		success: function (data) {
			//
			//requests is a number keeping track of the current request count.
			//you can use that to check if a request is 'stale' and leave or abort an old request.
			if (autocomplete.requests > requestnum) {
				//exit, we have a more current request coming
				return;
			}
			//
			//autocomplete expects two properties to function correctly: value and label.
			//our API endpoint does not hand back objects with those properties, but we can set them...
			autocomplete.each(data, function (obj, index) {
				obj.label = obj.Name;
				obj.value = obj.Symbol;
			});
			//
			//We're also going to store the retrieved data in the autocomplete cache.
			//This way if the user searches the same term again, we'll pull it from cache vs. sending another request.
			autocomplete.setCache(query, data);
			//
			//finally, it's time to render out data.
			autocomplete.render(data, query);
		},
		error: function () {
			//autocomplete has events already set up if/when an error occurs.
			//The events notify screen readers and users of what's going on, so it's important to wire them in.
			//you can also add your own handlers to the request.error event.
			autocomplete.emit('request.error');
		}
	});
	//
	// lets also set up an abort events
	autocomplete.on('request.abort', function () {
		//abort our xhr request if possible.
		//we can also use the requests/requestnum logic to do our own aborting.
		if (xhr) xhr.abort();
	})
});

Events

All events are part of the Mk EventEmitter and *not* added to the DOM. Events are also called in context of the component instance so it isn't a great idea to use a proxy function to change context, as you'll loose a lot of beneficial object access.

instance.on('render', function (data) {
	console.info(data);
});
		

instance.on('change', function () {
	console.info('base 64:', this.value);
	console.info('raw objects:', this.selections);
});
		

instance.on('submit', function () {
	console.info('base 64:', this.value);
	console.info('raw objects:', this.selections);
});
		

instance.on('show', function () {
	console.info('Menu has opened!');
});
		

instance.on('hide', function () {
	console.info('Menu has closed!');
});
		

instance.on('activate', function (option, keyboard) {
	console.info('active option:', option);
	console.info('came from keyboard (vs mouse):', keyboard);
});
		

instance.on('disabled', function () {
	console.info('Selectmenu has been diabled.');
});
		

instance.on('enabled', function () {
	console.info('Selectmenu has become enabled.');
});
		

instance.on('update', function () {
	console.info('Changes to the native autocomplete have been applied to the UI.');
});
		

instance.on('capacity', function () {
	console.info('We reached capacity!');
});
		

instance.on('create.tag', function (o) {
	o.label = 'New Label!';
});
		

instance.on('request.send', function (query, requestnumber) {
	console.info('about to search for ', query);
});
		

instance.on('request.error', function () {
	console.info('request failed');
});
		

instance.on('request.abort', function () {
	console.info('my request is being aborted due to new user actions.');
});
		

API

Below are the different public properties and methods accessible to you, the end developer. All of these are accessible on your Autocomplete [ac] instance as well as inside event handlers bound to your instance. Some methods have intentionally been left out due to their difficulty tof use for end developers vs. internal use.