To embed Text Highlight session to a web page, you need to load our recorder library.

That’s a script and a stylesheet:

<link rel="stylesheet" href="https://workbench.mercuryanalytics.com/api/recorder.css">
<script src="https://workbench.mercuryanalytics.com/api/recorder.js"></script>

Then, you need to tell it where on the page to put the video.

<div data-hg-recorder="2160_PO_DEMO" data-hg-rid="000000"></div>

The “2160_PO_DEMO” is the id we give you to refer to our Text Highlight tool, and the “000000” should be replaced with the your respondent id.

It’s safe to add the stylesheet and script to your survey’s template, since it does nothing when there’s no marker div to tell it where to put the video.

Events

Using selection “flavors”

The text highlight tool, by default, only applies a single “style” of highlight. The tool does support the use of multiple highlight colors with a bit of extra programming.

The <div data-hg-recorder> DOM element is automatically extended to support an extra property, hgFlavor. When the respondent adds a new highlight, it’s recorded along with whatever value this property has at the time. Please note that flavor names must be a single word without punctuation.

When the control actually highlights the text, the highlighted text is wrapped in a mark tag with a class name derived from the current flavor. If no flavor is set, the class is mark-hg-highlight, otherwise, the class is mark-hg-highlight-<name>, where <name> is replaced with the flavor. You can either provide your own stylesheet that applies the appropriate styles, or you can request that we automatically insert the appropriate stylesheet by telling us what flavor names you will be using, and what foreground and background colors you want used.

The simplest way to use this is to first tell us what flavors you’ll use. As an example, consider an exercise with two flavors, called “positive” and “negative”. We’ll provide radio button controls to let the respondent to switch between flavors.

<form>
  <label>
    <input name="flavor" type="radio" value="positive" checked>
    Positive
  </label>
  <label>
    <input name="flavor" type="radio" value="negative">
    Negative
  </label>
</form>
<div data-hg-recorder="2160_PO_DEMO" data-hg-rid="1"></div>
<script>
  var recorder = document.querySelector("[data-hg-recorder]");
  recorder.hgFlavor = "positive";
  var select = document.querySelector("form");
  select.addEventListener("change", function(event) {
    recorder.hgFlavor = select.flavor.value;
  })
</script>

Here, a small form is created with the radio button group. Each radio button is given a value attribute indicating which flavor should be applied when the button is selected. The “positive” button is marked as initially selected, and the script initializes the hgFlavor property to match. An event handler listens for changes to the form and sets the flavor from the selected button.

If you haven’t arranged for an automatically injected stylesheet, the following stylsheet could work as an example:

.mark-hg-highlight-positive { color: white; background-color: green; }
.mark-hg-highlight-negative { color: black; background-color: red; }

Note that the default colors, unless explicitly changed by a stylesheet, show black text on a yellow background.

Read-only mode

You can present the highlighted text in a “read-only” mode. This often used to show what the respondent highlighted while asking them more questions about their response.

To activate the read-only mode, add an attribute, data-hg-readonly to the <div data-hg-recorder> tag. The value of this attribute should indicate what text is to be highlighted as a list of word-index pairs. For example, to select the first word, and the eighth through the twelfth word, the attribute would be data-hg-readonly=0,0;7,11. Note that words are indexed from zero (the first word is word zero), and the pair indicates the first word and last word of the selection. Pairs are separated by semicolons, and each pair may optionally include a third component indicating the flavor, for example data-hg-readonly="0,0,positive;7,11,negative".

This is the same format that the selection is returned in the data.codedSelection property of the mercury:changed event fired by the control each time the selection changes. By listening for the event and recording the codedSelection property, a survey can easily re-display the respondent’s selection by setting the data-hg-readonly attribute to the saved value.

Sending Demographic Variables

For the later step that sends the demographic variables back to our server, the setup is very similar. You have the same stylesheet and script, but now the marker tag looks like this:

<div data-hg-recorder="2160_PO_DEMO" data-hg-rid="000000" data-hg-mode="demographics" data-hg-demographics="demographic-data"></div>

The data-hg-mode tells it this is demographics only. The “data-hg-demographics” attribute tells it where to find the demographic data, and it should be the HTML id of a <dl> tag somewhere on the page. The <dl> tag might look something like this

<dl id="demographic-data" class="hg-demographic-data">
  <dt>Sex</dt>
  <dd>1/Male</dd>

  <dt data-hg-type="multipunch">Breakfast Cereals</dt>
  <dd>1/Fruit Loops</dd>
  <dd>3/Corn Flakes</dd>
  <dd>6/Cap'n Crunch</dd>

  <dt data-hg-type="text">Breakfast Cereals (other)</dt>
  <dd>That stuff with the Frankenstein monster cartoon</dd>
</dl>

The id attribute has to match the data-hg-demographics attribute on the marker <div>. You can make the “class” anything you like so as to apply some appropriate styles from your stylesheet to the data, but using hg-demographic-data will simply hide it from the page so the panelist won’t see it. I’d suggest you not use hg-demographic-data until everything is working, so you can see exactly what it’s trying to pass, and only add the class in when you’re ready to go into production with it.

Multipunch and Open-Ended Responses

Each variable you want to pass has a <dt>, followed by one or more <dd> tags. The <dt> gives the name of the variable (often just the text of the question). Multipunch categorical variables, like the “Breakfast Cereals” variable above, should use data-hg-type=”multipunch”, and open-ended (text) questions, like “Breakfast Cereals (other)” above, should use data-hg-type=”text”. Each response should have its own <dd>.

Categorical Responses

For categorical responses, the value should have two parts, separated by a slash (/). The part before the slash is what we call the sort indicator, and the part after is the category label. In our viewer, the categories will be sorted so as to include the sort indicator, but only the label is actually displayed.

Sort Indicators

Please note that the sort indicator is part of the value – so 1/Male is treated as a different category from 2/Male. You should pick a specific sort indicator value for each category – 1/Male and 2/Female – and always use the same sort indicator with a given category (within a single question). If the sort indicators aren’t unique, then the viewer will further sort things by the category label, so if you’re satisfied with everything simply being sorted alphabetically, you can use an empty sort indicator for everything. With this, you’d pass /Male and /Female, and they’d show up in the viewer with Female first.