During the project I was working on the past month we decided to incorporate jQuery Tokeninput as an autocomplete & token solution. We came across some big +’s and -’s that I wanted to share for anyone considering using it.

Pros:

  • Simple to set up. Michael worked on this with me and we had the basics up and running pretty quickly. We already had an endpoint that served up JSON for autocomplete suggestions, so then we just needed to include the Tokeninput JS and CSS files and add the following javascript:

    $(“#input-selector-to-bind-to”).tokenInput('api/endpoint_serving_json’, {
  queryParam: 'term',
  resultsLimit: 10
})

  • Pretty good out of the box configurability. You can set options like the number of suggestions returned, the value you’d like to pass on submit, if you want suggestion text, and even if you want to format the returned result in special HTML (which is very handy for styling).

  • Pretty good documentation The project’s main page has a lot of good info and there’s also a solid demo page with a lot of additional details.
  • Some handy callbacks & add/remove methods. If you want to trigger something when a token item is added or removed then Tokeninput includes onAdd and onDelete methods (among others). For example, we used the onAdd callback to update a recommendation box based on the token they’d selected. You can also use the tokenInput(“add”, {your_item}) method to populate your input field. For example, if a user wanted to keep track of previous searches in order to refine an earlier search, you could use tokenInput to add in these previous terms.

Cons:

  • ”Hidden” Data Once you start adding items via tokenInput they can be pretty well abstracted away from you. Although the items have an tokenInput id and a name, those attributes aren’t reflected on the page’s source code and they aren’t easy to work with.
  • tokenInput brings its own DOM elements tokenInput muscles it’s own DOM elements into your code. Although you’re attaching the tokenInput action to a DOM element you create, tokenInput stores the items it adds in its own containers and attaches its own slightly-confusing class names. Our personal favorite: ‘token-input-input-token’
  • It’s a little too good We eventually figured out how to use underscore and some DOM tomfoolery to dig into tokenInput’s data stores and do all sorts of things like attach dynamic ratings to search tokens that users could update. It made for some really slick UI- however, this code could start to get ugly and fragile very quickly so we really had to be careful.

Verdict

jQuery tokenInput is a pretty easy and powerful tool and the next time I need an autocomplete/token solution I’ll look into using it again. However, I’ll also be pretty careful with it and be sure to get a lot of acceptance test coverage around it as we learned it can get hairy pretty quickly.