Japan Days

coding keeps me sane...ish

A couple of weeks ago, I began to think about implementing tooltips on Japan-Days.info. Anyone who reads internet content has seen and probably used tooltips. On many sites such as news websites, Wikipedia, etc, you will find words that are highlighted similar to links. Hovering the mouse pointer over one of these words will invoke the presentation of a small information box containing text and/or images that give the reader immediate insight or clarification of the meaning of the highlighted word. These are tooltips.

By the nature of the subject matter of this site, there is a lot of terminology used in the content that might require further clarification for most readers. Some examples are geographic and historical terminology, cultural specific terms, and military terms, both general and specific to the era, locations, and mission pertinent to my service. Therefore, I thought that tooltips, if properly implemented, could be a real asset to this site that would enrich the reading experience of most people visiting.

Given that idea, I had to determine what is "proper implementation" for this website. Wikipedia contains a freely accessible and ever evolving base of excellent information about many things, and the Wikipedia API establishes an extensive array of options for a programmer to access the information, and incorporate extracts into a feature like a tooltip. Not all of the terminology in this site's content needing further clarification is in Wikipedia, however. Some terms, such as my Air Force specialty, MET/ARE are so obscure that it would be difficult to find any reference to it anywhere on the internet. So the best source of information regarding that term would be someone with personal knowledge ... someone like me. Another scenario that I encountered when researching data for tooltips is when the Wikipedia extract, while accurate and current, does not properly fit the context of how a word is used in a specific article. An example of this is a term that I often use when writing about my USAF years on Japan - WC-135. This is a weather aircraft model designation, and while there is good documentation in Wikipedia, the focus of the extract is on the current mission of the few WC-135 aircraft remaining in service and designated "Constant Phoenix". Therefore, I decided that I would write tooltip text for WC-135 that would better fit the context of articles referring to their use by the USAF in the 1970's. These scenarios substantiate the need for being able to call tooltip text from a local database as well as from remote sources like Wikipedia. In summary, I wanted to design this feature in such a way that I could access the data from multiple sources, keeping the content entry and editing as well as the presentation simple, while optimizing contextual relevance.

While the ideas of how to engineer the database structure and PHP coding that would provide that flexibility and that would integrate smoothly into the site's architecture were spinning around in the background of my mind at all hours of the day and night, I also had to decide on how to present the information. Generally, I figured that I would code a jQuery function that on mouseenter would pick up the ID parameter that defined a tooltip in an inline "span" element, then to use AJAX to send the ID to the server and retrieve the applicable content. At the server, upon detecting a query that included a tooltip ID, the ID would be passed to a PHP function that would get the appropriate tooltip record from the database, decide whether to do an API query to Wikipedia or to retrieve text from the site's database, and then form the text, title, media, etc in HTML, and return it to the requestor. How to present the text to the user, whether to use the tooltip class native to CSS or some other method, required some research. That research led me to jQuery UI, an amazing jQuery library of all sorts of really cool widgets, one of which is a tooltip ... the ones that you see on this site.

The inclusion of images in the tooltip content presented another matter of consideration. I had decided that in the initial implementation toolip content text would either come from a dynamic query from Wikipedia or from text that I wrote and stored in the site's database. For image inclusion, I experimented with retrieving image locations using a Wikipedia api query, but my initial experiments received mixed results. In order to make that work, I would need to study the api more thoroughly, and, of course, write more code. After thinking about this for a day or so, I finally decided that instead of automating image inclusion, I would select either an image that I own or one that is public domain, and include those where applicable to a tooltip irrespective of the text source, and then provide proper image attribution separate from the text attribution. That seems to work for now.

So, after that long winded explanation, I just want to say that I hope that anyone reading this site finds the inclusion of tooltips to be of value. Thank you for visiting.

Update 8/9/2019: Okay, I know that it has only been a few days since I deployed this feature, but as I began to add tooltips to existing articles, I realized that it would be great if I could also define some tooltips as media only, i.e. containing only a single image or video. Sooo, after a day of dedicating my spare time to coding ... DONE.