JavaScript
Article

Marco Polo, a jQuery autocomplete plugin

By Sam Deering

Today, we have a Guest Post by Justin Stayton. He talks about his new developments including Marco Polo, a jQuery autocomplete plugin and Manifest, a jQuery plugin that adds delight to selecting multiple values for an input.

Let me Google something for you: “jQuery autocomplete plugin”. Over the past four years, I’ve Googled this exact phrase north of a dozen times. The results, however, really haven’t changed that much: there are a lot of options, but none that spark enough confidence in me to rely upon in a production web app.

I’m very picky when it comes to the jQuery plugins I choose. If my users have issues with a plugin, that falls on my plate. I really don’t want to worry about third-party code in my system, so I’ve developed something of a litmus test that a jQuery plugin must pass to garner my consideration. In no specific order: the plugin must be well documented and code-commented, maintained with an update in the past six months, have very few (if any) known issues, follow modern jQuery coding patterns, and be flexible enough to fit 80% of my needs without a myriad of additional features that I’ll never use. None of the jQuery autocomplete plugins I’ve tried over the past four years have ever passed this test.

Marco Polo

marco-polo

So, I decided to write my own. Meet Marco Polo, a jQuery autocomplete plugin for the discerning developer. I think you’ll like it, especially if you’re as selective as I am in choosing jQuery plugins. But, don’t just take my word for it: play with the live examples, read through the documentation, and try implementing Marco Polo within your own system. Here’s a quick overview of how that’s done.

Demos

Getting Started

To start, make sure both jQuery and Marco Polo are included in your HTML:



Next, add a text input, if you haven’t already:


Then attach Marco Polo to the text input in your JavaScript:

$('#userSearch').marcoPolo({
  url: '/users/search',
  formatItem: function (data, $item) {
    return data.first_name + ' ' + data.last_name;
  },
  onSelect: function (data, $item) {
    window.location = data.profile_url;
  }
});

When a search happens, a GET request is made to the url with q (the search value) added to the query string. Let’s say a search is made for Butler. A GET request is made to /users/search?q=Butler. Your backend code must then use the q parameter to find and return the matching users in JSON format:

[
  {
    first_name: 'James',
    last_name: 'Butler',
    profile_url: '/users/78749',
    …
  },
  {
    first_name: 'Win',
    last_name: 'Butler',
    profile_url: '/users/41480',
    …
  },
  …
]

Each JSON user object is passed to the formatItem callback option for display in the results list. And when a user is selected from the results list, their JSON object is then passed to the onSelect callback option to complete the browser redirect.

That’s it! While this example demonstrates a number of fundamental concepts, the possibilities extend far beyond the straightforward search, click, redirect setup shown here. Try it out yourself, and I think you’ll be surprised at just how flexible Marco Polo can be.

Manifest

maifest
A jQuery plugin that adds delight to selecting multiple values for an input. The recipients field in an email app is a perfect example. You could just offer a plain text input, requiring the user to manually separate each recipient with a comma. Removing a recipient, however, is a pain: the user has to precisely select just the right amount of text, making sure not to accidentally remove too much or too little. As a discerning developer, you know the user experience should be better. And it can be, with Manifest.
Demos

About the Author

justin-stayton
Justin Stayton is the Lead Developer at Monk Development, Austin, Texas. You can catch him on GitHub and Twitter@jstayton.

  • jquery4u

    Hi Justin,

    Thought I might start by leaving a comment. I have checked out both your plugins and I’m impressed with both the usability and the way you have structured your code. Particularly like the idea behind the Manifest plugin can see this one being really useful. One thing I did see however was the need for a loading image, especially for the ones which are using an AJAX API Call.

    Great job mate.

    Cheers
    Sam

  • http://www.gbin1.com Terry

    I guess demos don’t support IE7, but i did find it work on Firefox. thanks!

  • http://justinstayton.com Justin Stayton

    @Sam: Thanks so much! The Marco Polo examples should have a loading image. (If they’re not showing for you, let me know.) I still need to add one to the Manifest examples, however.

    @Terry: Hmmm, I’ll have to look into that. Thanks for the report.

Recommended

Learn Coding Online
Learn Web Development

Start learning web development and design for free with SitePoint Premium!

Get the latest in JavaScript, once a week, for free.