Use cases for the XML format for the task files (see "Creating a New Task") are described in
this document. The reference document is found here. Click here for a split-screen view.
At the moment, most of the task XML customizations are quite
complex, and not yet documented. Here, we focus on the ways that
the user can specify various variations on defining the display of
their content annotations. For examples of how to define the
content annotations themselves, see here.
The simplest way of customizing the UI behavior of your content
annotations is to assign some CSS to distinguish them in the Web
UI. The most appropriate way to do this is to use background
colors; using font weight or style, or text color, as the sole
distinguishing feature will fail in document
alignment, comparison, and
reconciliation for span
annotations, and will always fail for spanless annotations, which
don't cover any text.
<annotation_display>
...
<label name="TAG1" css="background-color: blue"/>
<label name="TAG2" css="background-color: green"/>
...
</annotation_display>
(We assume that TAG1 and TAG2 are defined as true or effective
labels in your task.) We've assigned TAG1 a blue background color,
and TAG2 a red background color. Since you're using CSS, you can
assign colors using hexadecimal designations as well (or, if you
prefer, set a background image, or other wacky things).
One caveat: at the moment, annotation spans are styled on a
token-by-token basis. So if, for instance, you want to have a left
bracket at the left end of an annotation, and a right bracket at
the right end, you can't do that quite yet; you'd end up with each
token bracketed.
The <ui> element also supports the option of having
keyboard accelerators. These are keys that the user can press when
the tagging menu is visible in the UI, which are equivalent to
having selected that menu item. You can add an accelerator using
an attribute on the <label> element:
<annotation_display>
...
<label name="TAG1" accelerator="1" css="background-color: blue"/>
<label name="TAG2" accelerator="2" css="background-color: green"/>
...
</annotation_display>
It's probably a good idea to choose the accelerators mnemonically
(the first letter of the menu item name is always a good mnemonic,
unless of course more than one item starts with the same letter).
Be careful, though; MAT doesn't yet ensure that there are no
clashes among accelerators.
Sometimes the color you choose is too dark to see the text, in
which case you can use CSS to change the text color:
<annotation_display>
...
<label name="TAG1" css="background-color: red; color: white"/>
...
</annotation_display>
Remember, the value of the css attribute is really CSS; it's not
converted or processed in any way before it's inserted into the
CSS rules in the Web UI. The one caveat is that the CSS is applied
to each token in the annotated phrase, not to the phrase as a
whole.
Spanless annotations will pop up an annotation editor immediately
when they're created. If you want this behavior for spanned
annotations, you can specify it in the <label> element:
<annotation_display>
...
<label name="TAG1" css="background-color: red" edit_immediately="yes"/>
...
</annotation_display>
When an annotation is described in the UI (e.g., as an annotation
attribute value in the annotation tables or annotation editors, or
in the title bar of an annotation editor), it has a default
presentation, which, for spanned annotations, is the string the
span covers, and for spanless annotations, is the label and
annotation index. There are many times when you might want a
different default presented name, e.g., if the label tends to
traverse enormous spans. Here's an example of using the
presented_name attribute to truncate the text:
<annotation_display>
...
<label name="TAG1" css="background-color: red" presented_name="$(_text:truncate=20)"/>
...
</annotation_display>
There's a fairly extensive formatting language which is available
for the presented_name attribute; see the task
XML reference for details.
Sometimes string attribute values are expected to be short, and
sometimes long. By default, non-choice string attribute values get
a short typein window in the annotation editor. If you want to
make it a long string, you can do it like this:
<annotation_display>
...
<attribute name="attr1" of_annotation="TAG1" editor_style="long_string"/>
...
</annotation_display>
You may have a string attribute which is actually a date, which
you want to use a calendar widget to populate; or you might want
to look up the annotation text in a database, and use the results
to populate the attribute value. If you're willing to do some
programming, there's a way to associate an arbitrary JavaScript
function with a string, int, or float attribute, to use as its
editor:
<web_customization>
<js>js/yourTaskCustomizations.js</js>
</web_customization>
<annotation_display>
...
<attribute name="attr1" of_annotation="TAG1" custom_editor="yourJavascriptFunction"/>
...
</annotation_display>
You can define your function in your task directory in
js/yourTaskCustomizations.js (or whatever name you choose), and
this file will be loaded when the UI is loaded. Unfortunately, we
don't really have the resources to document the API this function
has to conform to; you can find the code which governs this
capability in the CustomEditorCellDisplay implementation in
MAT_PKG_HOME/web/htdocs/js/mat_doc_display.js.
Let's say that you've defined the following annotations:
<annotation_set_descriptor name="content" category="content">
<annotation label="PERSON"/>
<annotation label="MAN"/>
<annotation label="WOMAN"/>
<annotation label="US-LOCATION"/>
<annotation label="FOREIGN-LOCATION"/>
</annotation_set_descriptor>
Your annotator is instructed to label people, using PERSON as the
annotation if she can't tell which of MAN or WOMAN is applicable.
Your preference is to arrange these in a visual hierarchy for the
annotator's convenience; you wish to do the same with US-LOCATION
and FOREIGN-LOCATION, even though they don't have a common, less
specific annotation. Here's what you do:
<annotation_display>
...
<label_group name="PERSON" children="MAN,WOMAN"/>
<label_group name="LOCATION" children="US-LOCATION,FOREIGN-LOCATION"/>
...
</annotation_display>
The label group can reference an existing annotation (as in the
PERSON case) or create its own group (as in the LOCATION case).
The effect of these groups will be to create submenus in the
annotation popup in the MAT UI.