Glossification is the act of taking a block of HTML markup, analyzing that block to find phrases that exist in the Cancer.gov Dictionary of Cancer Terms, and presenting an editor with a user interface to select which phrases they want to appear on the web site a dictionary popup links.

A post-Drupal migration glossified link has the format:

<a 
  class="definition" 
  data-glossary-id="CDR0000DDDDDD" 
  href="/Common/PopUps/popDefinition.aspx?id=CDR0000DDDDDD&amp;version=Patient&amp;language=en">TERM</a>

There are also legacy definition links

<a 
  class="definition"
  href="/Common/PopUps/popDefinition.aspx?id=DDDDD&amp;version=patient&amp;language=English&amp;dictionary=Cancer.gov" 
  onclick="javascript:popWindow('defbyid','CDR00000DDDDD&amp;version=patient&amp;language=English&amp;dictionary=Cancer.gov'); return(false);">TERM</a>

The following are the backend (Drupal) components that add the glossary links into content. These components all live in the pdq_glossifier module.

The WYSIWYG button is a CK Editor plugin that appears for certain WYSIWYG editor configurations. (a nice non-API generated overview) This can be seen in the following image:

NOTE: The current code only supports glossifying Dictionary of Cancer Term terms. Additionally URLs are hardcoded to the pre-migration path which is being deprecated.

The plugin lives in the pdq_glossifier module. The items related to the plugin are:

• /src
  • /Plugin/CKEditorPlugin/CgovGlossifier.php - This is the CKEditor Plugin. (Implements CKEditorPluginBase) This plugin only really just defines:
    • the button image for the WYSIWYG
    • the javascript code (and really only the path to the js file) to run when the button is clicked
• /js/plugins/cgov_glossifier
  • /plugin.js - This initializes the plugin and defines what JS code to call when they user clicks the button.
  • /dialogs/glossify.js - This IS actually the code that runs when the button is clicked. It takes the HTML, cleans it up for the glossifier API, calls the API, and displays the results to the user in a dialog window.
  • icons/button.png - the button image.
• /css
  • /glossify-dialog.css - The CSS for the dialog window.
  • /images/ - Image files for the dialog

1. dialogSetup is called by the Drupal UI. (Anything else in there is our code.)
   1. uiSetup is called, passing in the editor instance, which just handles class and positioning for the dialog.
   2. requestGlossification is called, passing in the editor instance which:
      1. Gets the HTML out of the editor
         1. Remove (and remember) all the previously glossified terms. What the code does is replace the markup wrapper around the phrase with a span tag. (e.g. <a class="definition" ...id info... >Foo</a> becomes <span rel='glossified' ...id info... >Foo</span>). The glossification API knows not to suggest terms that are in anchor links. (among other HTML elements)
         2. Clean up some special characters
      2. Go to the API to get suggestions
      3. Display the content with checkboxes preceeding the suggestions. Check the checkboxes for the previously selected positions and terms. NOTE: There will be multiple instances of a suggestion and not all instances will, but could, be glossified.
      4. The Editor selects items (and can even UNSELECT previously selected items) and clicks save.
      5. The markup with properly wrapped terms is saved to the editor. (but it is not saved to Drupal until the node is saved)

NOTE: Editors may edit the term name after glossifying through view source. The current JS handles this condition.

The glossifier service scans an HTML fragment and identifies portions of that fragment which match entries in the NCI Dictionary of Cancer Terms. The service, which is available at /pdq/api/glossifier, takes three parameters, each of which is required, though the dictionaries and languages parameters can be empty arrays. The parameters and the returned result are encoded as JSON arrays.

See the glossifier service API documentation for more information.

Information on populating the glossifier API can be found at Populating the glossifier information.

The front-end components are those items that work client-side on the published web pages in order to allow popups to work.

The dictionary popup code lives in the Cancer.gov front-end. The location of the glossary popup code resides in the cgov_common theme.

The popup code supports both:

• the post-Drupal migration glossified link (css selector - a.definition[data-glossary-id])
• the legacy definition links (css selector - 'a.definition[href*="popDefinition.aspx"]:not([data-glossary-id])')

The code:

1. attaches a click handler to each matching element.

On a click the code:

1. Fetches the definition from the API
2. Creates an NCIModal element
3. Displays the definition content in the modal

The glossary API is what the Dictionaries and popups use as the defintion source. See the Glossary API Wiki or the API Swagger page.