Tuesday, March 30, 2010

Vocabulator – The Nuts and Bolts

Today, I’ll discuss how I built the data dictionary tool I call Vocabulator.  We will explore the challenges of building a tool like this and how the current architecture solves the problems.  And finally, I’ll include the source code and a short description on how to set up and use the tool.
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.
Our users also asked to have a quick definition in a tooltip and so we added a tooltip popup when they hover over a highlighted word that is vocabularized.
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 tool must be able to function without Internet access.  We host the tool on an internal Microsoft web server that serves up a web “handler” and the JavaScript libraries.  We use the JQuery tools which greatly simplify the User Interface and AJAX work.
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 run on any web page hosted on any kind of web server.  The work is primarily handled by the client:  the web browser.  The JavaScript code runs on practically every browser type.  There is a small amount of “heavy lifting” done via AJAX calls to the backend web service to populate the Vocabulary object.
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 handler is simple as well.  It instantiates a new Vocabulary class that populates the values from the XML “database” file which is then serialized for return to the JavaScript caller:
The calling JavaScript function next takes the return object holding the terms with their short and log definitions, searches the content section (marked up in a special <div> section) for any matches, and for those it finds, it wraps the term in an <h ref> link for the full/long definition, and adds a title for the ToolTip.  Here’s the function:
To see this in action, check the previous blog entry
The key source files can be downloaded from here.