HTML Integration - Auto Enabling Alpheios

Submitted by BridgetAlmas on Thu, 10/08/2009 - 09:42
in

Alpheios Basic Functionality

Auto-Enable Alpheios for only a single block of text on the page:

Add the following to the block element (e.g. <div>, <p>) surrounding the text:
  • a class named "alpheios-enabled-text" (in the 'class' attribute)
  • a 'lang' attribute set to the correct language code for the text per the IANA language subtag registry
    • Currently only Latin (la) and Ancient Greek (grc) are supported

Or, Auto-Enable Alpheios for the entire page:

  • Add <meta name="alpheios-pedagogical-text"> tag to the <head> tag of the html document
  • Add a 'lang' attribute to the <html> element, set to the correct language code for the page per the IANA language subtag registry
    • Currently only Latin (la) and Ancient Greek (grc) are supported
  • Enclose any sections on the page for which you don't want the Alpheios tools to be enabled in a block element which has the class 'alpheios-ignore' assigned in the 'class' attribute
For an optimal user experience, avoid hyperlinks on the text for which you want the Alpheios tools to be enabled.

Identify Word Tokens

When identifying the target word for a user selection, the default behavior of the browser is to find the smallest distinct element within the range identified as the target of the mouse event. Alpheios then identifies the word token from within the text content of this range. However, sometimes it may be desirable to have markup within a word, for example to identify fragments of words. To override the default behavior, add a meta tag named "alpheios-word-classes" to the head of a document to identify a list of CSS class names which are applied to elements in the document which represent complete words. Set the content attribute of this meta tag to a comma-separated list of class names used on elements to identify words within the page. It is not necessary to add this class to every word on the page, only those which are fragmented into multiple smaller elements.

For example:

<meta name="alpheios-word-classes" content="word,segmented-word"/>

In this example, if this metadata element is present, when responding to a user selection, the Alpheios tools:

  1. Check if the selected element's class attribute value includes "word" or "segmented-word"
  2. If not, check if a parent element has one of these classes, and if it does, widen the scope of the target range to the parent element
  3. If the metadata element is not present, or if the selection does not have one
    of the listed classes assigned to a parent element, the target range is not changed.

By default, the tools will ignore whitespace within a markup element identified by the alpheios-word-classes meta tag. This behavior can be changed by setting the "alpheios-preserve-whitespace" attribute to "true" on the meta tag. E.g.

<meta name="alpheios-word-classes" content="word,segmented-word" alpheios-preserve-whitespace="true"/>

Add Alpheios Hints to the page

To have the Alpheios tools add a hint about the mouse actions which trigger a lookup (e.g. mousemove or doubleclick) to the page, add an empty HTML block element with the class 'alpheios-trigger-hint' in the location where the hint should be dislayed. When the tools are enabled, they will populate this block with user-friendly instructions about how to trigger the lookup (e.g. "Lookup a Greek word by double-clicking on it")

For example:

<div class="alpheios-trigger-hint"/>

CSS Style rules can be applied to style this element. The Alpheios tools do not impose a style on this text.


Reacting to Alpheios Enabled

If you need to modify the contents of the page when Alpheios has been enabled, add a javascript eventListener to an HTML element on the page, which listens for the custom 'AlpheiosEnabled' event. For example:

<div id="alpheios-enabled-callback" display="none"></div>
<script type="text/javascript">
var alpheios_enabled_called = false;
function on_alpheios_enabled(){
if (alpheios_enabled_called)
{
return;
}
alpheios_enabled_called = true;
// custom code
}
document.getElementById('alpheios-enabled-callback').addEventListener('AlpheiosEnabled',on_alpheios_enabled, false);
</script>

The AlpheiosEnabled event is sent to the client code by the browser when the tools are turned on, that is, when the user loads a page which has been auto-enabled for the Alpheios tools as described above. The user must have the required Alpheios tools for the language installed in their browser for the event to be triggered.

The AlpheiosEnabled event may be issued more than once. It's the responsibility of the client code to handle this scenario appropriately.

Checking for Alpheios Tools

The client code can also check to see if the user has the Alpheios tools required for the page installed in their browser and present them with a link to the Alpheios site to install the tools.

On every page load (the DOMContentLoaded event), the Alpheios tools install the following meta elements into the <head> of the document loaded in the browser:

Alpheios Basic Libraries:
<meta content="{4816253c-3208-49d8-9557-0745a5508299}:1.0alpha4.2135.20091005" name="_alpheios-installed-version"/>

Alpheios Greek Tools:
<meta content="{0f1d7e06-6ce8-40b0-83f0-9783ee65ab9b}:1.0alpha4.2140.20091005" name="_alpheios-installed-version"/>

Alpheios Latin Tools:
<meta content="{7dd2b42f-3db8-4833-88c4-5a9e3788017b}:1.0alpha4.2139.20091005" name="_alpheios-installed-version"/>

The format of the content attribute in the meta element is <Extension GUID>:<version>

You can add a javascript function to be called from an onload handler on the documents <body> element to check for the installed Alpheios and versions and respond as appropriate for your site.

Note that the function which looks for the meta elements should not be called prior to the body load event as the meta elements will not have been inserted in the page until just before the body loads.

Alpheios Enhanced Text Functionality

Treebank

Integrating a block of HTML text with references to treebank XML data for that text enables the Diagram button on the Alpheios popup and enables the morphology displayed in the Alpheios popup to be specific to that particular usage of the selected form.

To enable this integration:

  • An XML document containing the treebanked text must be loaded in the Alpheios repository.
  • Each word (from the treebanked text) in the HTML document displaying the source text must be wrapped in a <span> tag (or other valid HTML element) and be linked to the treebank data via a 'tbrefs' attribute on the wrapping element.
  • The value of the 'tbrefs' attribute should be set to the sentence and word id of the corresponding element in the XML treebank data, separated by a hyphen (e.g. tbrefs="1-1" for the element from sentence id="1" and word id="1"). The 'tbrefs' attribute is multi-valued (i.e. if the word in the HTML document corresponds to more than one element in the treebank data). Multiple values must be space-separated.
  • The <head> element of the document must contain 2 <meta> elements pointing to URLs from which to retrieve the treebank data. For example, to enable disambiguation of the morphology:

    <meta content="http://repos.alpheios.net:8080/exist/rest/xq/treebank-getmorph.xq?f=1999.02.0066&w=WORD" name="alpheios-treebank-url"/>

    and to enable the treebank diagram:

    <meta content="http://repos.alpheios.net:8080/exist/rest/xq/treebank-getsvg.xq?f=1999.02.0066&s=SENTENCE&w=WORD" name="alpheios-treebank-diagram-url"/>

    The WORD and SENTENCE placeholders will be replaced by values from the 'tbrefs' attribute at runtime.
At the moment, only the Alpheios repository is supported for linking treebank data. In the future other repositories may be supported.

Aligned Translation

Integrating a block of HTML text with a word-aligned translation for that text (also in HTML format) enables the Alpheios Translation panel and the Quiz functionality. (Note that the Quiz functionality requires both an aligned translation and treebank data integration).

To enable the aligned translation:

  • The HTML documents containing the source and aligned translations must be aligned at the word level.
  • Alpheios must be enabled for the full page of the source HTML document via the <meta name="alpheios-pedagogical-text"> tag in the head of the document and the lang attribute on the <html> element as described above.
  • Each word in both the source and translated HTML must be wrapped in a <span> or other valid HTML tag with the class "alpheios-aligned-word" assigned in the class attribute.
  • The elements surrounding each word must contain an 'id' attribute which uniquely identifies the word in the document, in the format "s<sentence_number>_w<word_number>" (e.g. s1_w1).
  • the elements surrounding each word must also contain an 'nrefs' attribute which lists the ids of the word or words in the aligned document which are the translation for the source word. This is a multi-valued, space-separated attribute.
    Example:
    In the source document:

    <span class="alpheios-aligned-word" id="s1_w1" nrefs="s1_w3">cepit</span>

    In the aligned document:

    <span class="alpheios-aligned-word" id="s1_w3" nrefs="s1_w1">took</span>

  • The source document must contain an HTML element with the id "alph-trans-url" and the custom attribute, 'url', set to the path of the aligned translation HTML document.
    Example:

    <div id="alph-trans-url" url="http://alpheios.net/alpheios-texts/Perseus.text.1999.01.0021/align/book1_card1.7.1.html"/>

    The aligned translation does have to be on the alpheios server.

    Note - in a future release, this syntax will change so that we can support multiple translations for different chunks of text on each page.

  • Additionally, the css classes listed in the attached file XXXX must be defined in both HTML documents (source and translation)

Add the Alpheios Toolbar to the page

Toolbar elements for more convenient access to the Alpheios functionality can also be enabled directly within the pages of a site. The client html and javascript code is responsible for display of the toolbar, and functionality invoked by the toolbar is bound to the toolbar elements in the page by the installed Alpheios extensions.

Sample Code

See sample HTML and Javascript at http://alpheios.svn.sourceforge.net/viewvc/alpheios/api/trunk/samples/