As mentioned before, the New York Times web site that allow readers to double click any word to retrieve its definition was the inspiration for this tool. Unfortunately, the early prototype of Vocabulator showed some limitations to this approach in healthcare. Specifically:
- We frequently need to lookup phrases and not just words – though the New York Times site now allows for phrase lookups as well and I like the newer UI that has a semi-transparent box with a >>more link.
- For our medical use, we have a relatively small set of words or phrases (“terms”) in our vocabulary. Therefore, users would quickly get frustrated if they tried to retrieve the definition of a term by selecting it and then find it was not in our database.
- To address the previous issue, we highlight each term that is in our data dictionary (“vocabularized”). In other words, we send the words in our vocabulary list to the page, in the background, instead of the other way around.
With this design, they can quickly and easily see each term that is defined, and hover over the term to get a quick and simple definition; or, to click the term to get a modal dialog with the full definition.
So let’s look at how this all works behind the scenes with our requirements in mind (see the previous post):
The vocabulary must be easy to create and edit. To meet this requirement, the vocabulary is hosted in an xml file. This makes it easy for anyone to edit; for example, it can be passed around in email for user edits. Plus, this allows us to host multiple vocabularies very easily such as multi-lingual dictionary.
It must not delay the web page. The processing is done on the background and is transparent to the end user. If they quickly move to another page before the processing is complete, they will never know.
OK, so now for the technical deep dive:JSONP. One technical issue I found when I tried to post the sample in the previous blog post was that the security in the browsers would not allow cross-domain calls. Even though the blog was hosted at http://blog.brucejackson.info and the code was on the main site at http://brucejackson.info, it was “cross domain”. To get around that, I took advantage of the simple but powerful JSONP parameter built into JQUERY’s AJAX library.
This snippet is called after the document is fully loaded and creates the hidden modal dialog where we will put the definition if the user clicks the new hyperlink of the term. The URL is the web service handler back at the server and the data type is the special jsonp type.
The key source files can be downloaded from here.