Autocomplete with KnockoutJS

Recently I started a new job at a company that is looking to transition away from a customised, unstructured, jQuery module set up to use KnockoutJS and RequireJS for it’s modules. This approach was chosen because the core platform is based on Magento and the forthcoming Megento 2 uses KnockoutJS heavily throughout it’s frontend templates. As a good starting point and proof of concept, we decided to look at converting our existing custom-autocomplete module from a combination of EJS and jQuery to pure KnockoutJS. Luckily for me, I was the one who got to implement it, and thus learn a new skill!

I’m not going to go into the ins and outs of how KnockoutJS works but in short it’s a MVVM system, where you have Models, Views and ViewModels, the latter being the interface between the other 2, the client and the server. This autocomplete was a standard input field, whereby on typing 3 characters, an AJAX call is made to the server looking for strings that matched the search string and displayed a clickable list of results underneath the input field. Additionally, you could use the arrow keys to select items in the menu, as well as the mouse. We also have different instances of the autocomplete, to search for different types of entities (e.g. searching for a product vs. search for a place), so we need the code to work with each.

From this point on I’m going to assume at least a basic knowledge of KnockoutJS, how it uses data-bind etc.

The View Model

So, first up we’ll want an Autocomplete viewModel, to handle the DOM events in the view (e.g. keyup etc.), fetch data from the server and call the correct model to format the received data. It’ll have 2 observable attibutes: suggestions, an array of suggestion objects, and q, the incoming query from the user. As a parameter we’ll pass it the model type to format the suggestions (e.g. LocationSuggestion below) and we’ll have functions to fetch suggestions as JSON from the server (loadSuggestions), add them to our suggestions array (addSuggestion, formatting the data via the model along the way) and clear our array (clearSuggestions), as well a helper function to look for valid character key presses (validKey). None of this is overly complex and it’s well commented, so I’ll just leave the whole class here:

We also store the current AJAX request with the object in the ajaxRequest attribute. By doing this, we can cancel any existing requests as the user types more keys. So, when they type the first 3 characters, a request is fired off; when they type the 4th character, we’ll cancel the existing request if it hasn’t finished and do a new search for the longer string.

The Model(s)

For this example, I mentioned above that the user could be searching for locations or products; let’s go with a location search for this example. Below, we have a class LocationSearch, which takes a JSON object that was returned from our server, formats the matched string by wrapping <strong> tags around the bit of the string that was matched (via the global accentInsensitiveRegex function, which I unfortunately don’t have the code for), generates the URL for the result and translates the type of location found (.e.g city, county etc.).

The View

So, for the HTML side, we need an <input> field for the user’s query and a <ul> for the search results. The <ul> will obviously be hidden if we’ve no results to show. We wrap the whole thing in a <div> with class autocomplete, which we’ll use when binding the whole thing together later.

For the <input> field, we bind our AutoComplete‘s q attribute to Knockout’s textInput data binding (textInput: q), so that every time the value of the <input> changes, q will too. Additionally, we want to fire our loadSuggestions function, which will check the length of q and fetch suggestions from the server if it’s greater than 3 characters; this is achieved by calling loadSuggestions when a Javascript keyup event is fired on the <input> (event: {keyup: loadSuggestions}).

The HTML for the <ul> is also fairly straight-forward. If we have any suggestions to show, we want to add the has-results class to the <ul> (css: {'has-results': suggestions().length > 0}) and of course hide the <ul> when there’s less than 3 characters typed in the <input> (visible: q().length > 2). Assuming we have suggestions to show, we loop through the suggestions array, displaying an <li> for each, containing the suggestion’s labelFormatted and translatedType, as well as adding some attributes to the surrounding <a> (data-bind="attr: {href: url ...).

Binding It All Together

At this point we need to bind our AutoComplete object to our div.autocomplete, passing it the search URL and suggestion type as parameters:

One last bit…

To get all this working nicely, you’ll need CSS for the <ul> and it’s <li> children. Additionally, you might want code to look out for when the up and down arrows are pressed on the keyboard and highlight the next row correctly. The code I have for this isn’t mine, so I’m not going to put it here. However, I will point out that to add any fancy jQuery on your view, i.e. to handle these up/down arrow keypress events, you can use KnockoutJS’s custom binding handlers. This is to keep business and presentation logic separate from each other. So, in JS you’d have something like:

The HTML for your <ul> would change to <ul class="autocomplete-results" data-bind="autoComplete, css: {'has-results': suggestions ... – note the addition of autoComplete on the data-bind.