The standalone viewer

A subportion of the MAT Web UI can be used, without additional support, as a viewer for annotated documents in MAT JSON format. An example can be found in $MAT_PKG_HOME/web/htdocs/doc/html/standalone_viewer_example.html; if you're viewing this documentation via the MAT Web server, you can view the example in its own window here. Below, we describe how to use the viewer.

Setup

The following includes are required from $MAT_PKG_HOME/web/htdocs:

js/mat_utils.js
js/mat_core.js
js/core_ui.js
js/mat_doc_display.js
js/mat_standalone_doc_viewer.js
css/mat_core.css

The Javascript files must be loaded in the order given. If you're running the MAT Web server, you can load them in your document head as follows (where "yourserver" is the host where the MAT Web server is running):

<script type="text/javascript" src="http://yourserver:7801/MAT/js/mat_utils.js"></script>
<script type="text/javascript" src="http://yourserver:7801/MAT/js/mat_core.js"></script>
<script type="text/javascript" src="http://yourserver:7801/MAT/js/core_ui.js"></script>
<script type="text/javascript" src="http://yourserver:7801/MAT/js/mat_doc_display.js"></script>
<script type="text/javascript" src="http://yourserver:7801/MAT/js/mat_standalone_doc_viewer.js"></script>
<link rel="stylesheet" type="text/css" href="http://yourserver:7801/MAT/css/mat_core.css">

Alternatively, you can copy these six files to your own Web server.

No other files are required. Although the MAT UI relies heavily on the Yahoo! UI Toolkit, the standalone doc viewer does not, nor does it rely on any other toolkit.

Creating the viewer

In order to create the standalone viewer, you need, minimally, a tag set and a DIV where the viewer will be rendered.

<script type="text/javascript">
var Tags = [{label: "PERSON", css: "background-color: CCFF66"},
            {label: "LOCATION", css: "background-color: FF99CC"},
            {label: "ORGANIZATION", css: "background-color: 99CCFF"}];

var docDiv = document.getElementById("docDiv");

// Set up the viewer.
var viewer = new MAT.DocDisplay.StandaloneViewer({
  tags: Tags,
  div: docDiv
});
</script>

There's a lot more you can do, which we'll return to when we look at the viewer details. For now, let's move on to creating documents.

Creating a document

The documents you provide should be a Javascript object which corresponds to the MAT JSON format. For instance:

<script type="text/javascript">
var Document1 = {
  "signal": "David Asher is a former coordinator of North Korea policy at the State Department.",
  "metadata": {},
  "asets": [{"type": "ORGANIZATION", "attrs": [], "annots": [[65, 81]]}, 
            {"type": "LOCATION", "attrs": [], "annots": [[39, 50]]},
            {"type": "PERSON", "attrs": [], "annots": [[0, 11]]}]
};
</script>

We assume that you'd create these documents automatically somehow, by converting documents in your favorite format into MAT JSON format, or from your previous interactions with MAT. The document you pass can also be a JSON string in this format, rather than the resulting structure, or, alternatively, you can use the MAT Javascript UI to create the appropriate document, e.g.:

<script type="text/javascript">
var Document1 = viewer.newDocument("David Asher is a former coordinator of North Korea policy at the State Department.");
Document1.addAnnotation(new MAT.Annotation.Annotation(Document1.annotTypes.PERSON, 0, 11, null, null));
Document1.addAnnotation(new MAT.Annotation.Annotation(Document1.annotTypes.LOCATION, 39, 50, null, null));
Document1.addAnnotation(new MAT.Annotation.Annotation(Document1.annotTypes.ORGANIZATION, 65, 81, null, null));
</script>

Displaying the documents

If you want to display a single document:

<script type="text/javascript">
viewer.renderSingleDocument(Document1);
</script>

You can reuse the viewer as many times as you want; it will reset itself appropriately with each call to renderSingleDocument().

Details: the tag table

The tag table is a list of annotations which will be recognized and displayed. It is a Javascript array of objects with the following keys and values:

key	value	description
label	a string	an annotation label in the MAT JSON document. Required.
attrs	an array of two-element arrays	if you want to associate a visible label with an annotation label plus some attribute-value pairs (e.g., if you want ENAMEX TYPE="PERSON" to show up as PERSON in your display), you can do this by specifying the attribute-value pairs here as an array of two-element arrays, e.g., [["TYPE", "PERSON"]], and then specifying the effectiveLabel key.
effectiveLabel	a string	see the description of attrs immediately above. The visible label for a combination of an annotation label plus some attribute-value pairs.
css	a string	a CSS specification for your label (e.g., "background-color: blue"). Required.

If you choose to display an annotation legend (see below), the elements in the legend will appear in the same order you listed them in the tag table. Remember, the CSS will apply to every subspan of the marked text, and the text may be divided into subspans if annotations overlap, so using left and right borders is not recommended.

Details: the viewer object

The viewer is instantiated with a single argument, a Javascript object with the following keys and values:

key	value	description
tags	a tag table	see above
div	a Javascript DOM object	the DOM object corresponding to the DIV in which you'd like to view your output
taskName	a string	the name you want to use if the standalone viewer wants to display a task name. Optional. This may not be used anywhere.
textRightToLeft	a boolean	if true, the viewer will display text right to left. Optional. Use this to display documents in, e.g., Arabic or Hebrew.
legendDiv	a Javascript DOM object	the DOM object corresponding to the DIV in which you'd like to have the tag legend rendered. Optional.
callbacks	a Javascript object	Each key is the name of a callback, and each value is a function. Use this object to customize the behavior of the viewer when certain events occur. These function names and their arglists are: uiError(msg): a function which will report an error message string to your UI. If not defined, alert() will be used. uiInform(msg): a function which will report an status message string to your UI. If not defined, alert() will be used. uiclearPane(div): a function which will clear the DOM object argument. The default function removes every child. mouseOverAnnotations(contentList): a function which will display the content description object when the mouse hovers over an annotation. The default does nothing. The contentList is a list of string descriptions of the annotations underneath the mouse. cancelMouseOverAnnotations(): a function which is called when the mouse stops hovering over an annotation. The default does nothing. There are a few more, but you'll never need them. Consult the source code if you're curious.

For instance, let's say that you have a tag table in the variable "Tags", as above; a div with the ID "docDiv", as above; a div with the ID "legDiv", where you want the legend rendered; and a div with the ID "updateDiv", where you want to display the annotation that's being hovered over. You'd instantiate the viewer as follows:

var viewer = new MAT.DocDisplay.StandaloneViewer({
  tags: Tags,
  taskName: "Named Entity",
  div: document.getElementByID("docDiv"),
  legendDiv: document.getElementByID("legDiv"),
  callbacks: {
    mouseOverAnnotations: function(contentList) {
      document.getElementByID("updateDiv").innerHTML = contentList.join(", ");
    },
    cancelMouseOverAnnotations: function() {
      document.getElementByID("updateDiv").innerHTML = "";
    }
  }
});