Alpheios Firefox Plugins

Overview of Functionality

The Alpheios browser plugin functionality, as currently implemented, is composed of the following parts:

Event Handlers and Observers

(for interaction with browser content and user selection)

  • identification of page language and available related resources
  • response to text selection (double click, mouseover, touch events)
  • identification of word or words in selection (language-sensitive identification of word boundaries)
  • observers for changes in environment: document load, tab change, app quit
  • triggers for display of grammatical resources (inflection and conjugation tables, grammars)

Linguistic Web Services Interactions

  • morphology
  • morphological disambiguation
  • syntactic structure
  • dictionary/lexicon

Url-specific functionality

  • auto-enable of tools

User data

  • vocabulary
  • sentence diagrams
  • translation alignments
  • user preferences (dictionary order, lookup triggers)

(Note that local storage of sentence diagrams and translation alignments has been deactivated)

UI Components

  • toolbar, menus
  • popups, inline elements, panels and dialogs for morphology, aligned translation, quizzes, diagrams, inflections, grammar
  • interlinear translations
  • interface text, icons, buttons
  • stylesheets

Browser State

  • across browser windows and tabs (currently used for quiz vs reading mode)

Server-based Tools

The translation alignment and sentence diagram features currently just provide the user with access to these as remote web applications in a new window.

General Utilities

  • xslt transformations (beta/buckwalter/unicode)
  • local data file interactions (index lookups, storage of vocabulary)

Extension points

  • languages
  • linguistic services and resources

Code Map

There are JSDocs for the basic libraries and each language extensions.

The main Alpheios Basic Libraries Firefox plugin code is in the basic-reader directory

The individual language tools plugin code is in the language-extensions directory, each under a directory named per language.

The application controller for the plugin code is the alpheios-main.js in the basic-reader/content directory.

The base class for language extensions (Alph.LanguageTool) is alpheios-lang-tool.js in the basic-reader/content directory. Each language specific plugin extends this class.

The general driver/event handler functionality for the popup is in the Alph.Xlate class defined in alpheios-popup.js (also in basic-reader/content).

The quiz code is in alpheios-query.js. Note that the inflection table part of the quiz is driven by the same source as the inflections display in reading mode. The source data for the inflections is in xml files which get bundled with the plugin at build time. These can be found in the /inflections directory at the root of the sourceforge repo, in directories per language (e.g. the greek inflections can be found in ( These are then transformed at runtime using XSLT with a little bit of javascript (the javascript primarily control the entry point into the tables and which transform gets applied). The stylesheets used for transformation can be found in the xml_ctl_files/xslt directory at the root of the sourceforge repo -- transforms specific to inflection tables are all named alph-infl-*. The ones used for the quiz mode are named *-query.xsl

The vocabularly list code is primarily in the WordList.jsm module in the modules/datatypes subdirectory of the basic-reader code. The interface code for the vocabulary list is in the main basic-reader/content directory in alpheios-vocab.js, alpheios-vocab-panel.xul and alpheios-vocab-window.xul.

Currently user data is stored by the Alpheios plugins in the user's local firefox profile directory. We have, up until now, put off development of a centralized user model for the Alpheios tools. There were a variety of reasons for this decision, but having this is clearly an important pre-requisite for the type of functionality we have been most recently discussing.

The Alpheios firefox plugin code was designed so we could add a service-based user model by easily switching to a remote dataservice. The design was at least partially influenced by the idea that different user bases might want to use their own services to manage their data. We defined a DataService interface (at with methods for some basic interactions with a data store. This class can be implemented and extended to provide the necessary business logic for interacting with a particular user data store. The DataManager class (in controls which DataService implementation is used by the tools to interact with the user data. (This decision can be influenced by configuration settings.) So far, we have implemented just a local version of the DataService interface, the DataServiceLocal class, which can be found at

Planning for HTML 5/cross-browser compatibility

Major Firefox Dependencies

The Alpheios tools currently use XUL elements for:

  • the toolbar
  • interface dialogs and panels
  • activation of functionality across all web pages
  • browser state
  • interaction with local file system resources for storage of user data and offline use

The existing javascript should be mostly cross-browser compatible, but it has only been tested under Firefox. Some things will need generalization. XSLT processing in particular currently relies on chrome privileges that might not be available outside of the browser internals.

The tools use an old version of the jQuery library which has been modified slightly to work with XUL. The inflection display uses a jQuery UI plugin.

The morphology popup, which drives most of the rest of the functionality, is actually just an HTML element that gets inserted into the browser page, and is not an XUL element at all (although it can optionally be enabled as one). The facing translation is implemented in a panel. A prototype of how this could be implemented in the HTML of the page directly can be found in the tei-digital-age code. This code also includes morphology and lexicon lookup implemented outside of the Firefox plugin framework.

The user vocabulary list, dictionary lookup, about dialog, inflections and user preferences are all XUL elements, and would need to be moved to windows or inline html elements.

The grammars and indices to the dictionaries are currently downloaded to the local filesystem (in the browser plugin directory). Local versions of the morphology services are also installed locally for Greek and Latin, but the tools currently default to the online web services.

XSLT files are also stored on the file system. These are used in a number of places, but particularly for text encoding transformations and the inflection table functionality.

Spec for porting the code to HTML 5

Bookmarklet Design

A bookmarklet is a javascript library which can be injected into any web page. The user adds a link to the javascript as a bookmark and then clicks on it when they want to activate the functionality. The main drawback to this is that it requires the user to re-click the bookmark on each page they want to use the tools. The ideal cross-browser design would be to have a single source for the bookmarklet code which works on all browsers, and then to add wrap that with browser-specific plugin skeletons which just add the functionality of doing the injection for the user. The structure of the existing Alpheios plugin code should be adaptable to this approach.

Bookmarklet Controller - Alph.Main

The main controller for the tools, the Alph.Main class, is in alpheios-main.js. This would be the likely candidate to serve as the bookmarklet entry point.

Alph.Main also controls the load order of the supporting javascript libraries. It calls the Alph.BrowserUtils.importResource function (modules/alpheios-browser-utils.jsm), which calls the Firefox Component.utils API to import the javascript modules from the extension zip. This should be replaced with a library like require.js.

The Alph.Main.alphInlineToggle function responds to an event which triggers the enabling of the tools. In the Firefox plugin structure, this event is a click on the "Alpheios/Toggle Alpheios On" menu item in the Alpheios toolbar. In a bookmarklet, this function should be triggered upon load of the script in the browser window.

The Alph.Main.alphInlineToggle calls Alph.Main.enable, which reads the configuration and sets up the various browser elements and event handlers.

Alpheios Toolbar

The alpheios toolbar is currently defined as Firefox XUL element in alpheios-overlay.xul. The event handers for the toolbar menu items are mostly functions in Alph.Main (alpheios-main.js), with a few using functions in Alph.Util (alpheios-utils.js) and Alph.BrowserUtils (alph-browser-utils.jsm). The User data menu item handlers are in Alph.DataManager (alpheios-data-manager.jsm).

  • The toolbar should be re-implemented as an HTML 5 menu element as a context (right-click) menu item.
  • Event handlers on the menu items should be made browser/device independent

Default configuration settings for the basic library functionality are all defined in defaults/preferences/alpheios.js. The interface elements for the configuration are in Firefox XUL elements (found in alpheios-prefs.xul and alpheios-*-prefs.xul) and event handlers for the preferences interfaces are defined in the Alph.Prefs class in prefs/alpheios-prefs.js. These handlers in turn are heavily dependent upon Firefox Components.

  • Port the Preferences UI elements from the XUL files into HTML elements, accessed from an HTML 5 menu element
  • Replace use of Firefox Components for user configuration settings to an HTML 5 IndexedDB

Some aspects of the configuration can probably be simplified. E.g. Alph.Main.setLanguages() calculates which language tools are installed, but running the scripts server side will allow us just to make all the languages available by default. (We may still to allow the user to disable certain languages though).

Other configuration options need different implementations. For example, if we want to allow users to get morphology and short definitions while offline, we need to look at alternatives to running a local binary. Maybe using full form databases implemented as HTML5 IndexedDbs.

Morphology Popup

The morphology popup is already activated as an HTML div element (id=alph-window) inserted into the active browser page, which is populated by a call to the alpheios morphology service for the current language. The main handler for the mouse action which inserts and populates the alph-window element is the Alph.Xlate.doMouseMoveOverText function (alpheios-popup.js). This function identifies the target of the click or mouse action, and then calls Alph.Xlate.showPopup to issue the AJAX call the morphology service. showPopup manages the visibility status of the alph-window element, and issues the AJAX call via the language tool implementation of the lexiconLookup function) to the morphology service, passing it the Alph.Xlate.showTranslation function as the success callback and the Alph.Xlate.translationError function as the error callback. This functionality should all mostly work outside of the context of a browser plugin. The morphology service results are in XML and are transformed via an XSLT 1.0 stylesheet to HTML for the display. The XSLT transformation may have cross-browser issues in the HTML 5 setup since the XSLT will have to reside server-side rather than in the browser (and won't be on the same server as the page in which the results are being inserted). I'm not positive this will be a problem, but if it is the simplest approach might be to implement a service which can handle the transformation. It could also be done by the morphology service itself, as an option, but this might complicate the processing done by Alph.Xlate.showTranslation to disambiguate the morphology service results with results from a treebank, if available.

Panels and Dialogs

The following features are activated from the morphology popup and are opened via a call to Alph.Xlate.openSecondaryWindow (in alpheios-popup.js). We need to update that function to eliminate any dependencies on running within the browser chrome.

  • Grammar
  • User Diagrams
  • User Alignments
  • Inflections (infl/alpheios-infl-xul)
  • The quiz display (query/alpheios-query.xul)
  • Dictionary browser

The locations used for these windows are currently either html files stored in the local plugin jar (Grammar), XUL files stored in the local plugin jar (Inflections, Quiz, Dictionary), or server-side resources (User Diagrams and User Alignments). Most of the locations are defined in one way or another in the preferences settings (defaults/preferences/alpheios.js). We should probably switch all of these to be server-side resources, using HTML 5 caching for offline access.

Most other panels and dialogs should be reimplemented as HTML5 elements which get added to the browser page, whose visibility is controlled by menu items added to the context menu.

These include:

  • The preferences dialogs (as described above under Configuration)
  • The translation panel (alph-trans-panel.xul) - there is a prototype for this available in the tei-digital-age code
  • The user vocabulary display (alpheios-vocab-window.xul/alpheios-vocab-panel.xul)
  • The about dialog
Web Service Interactions

Web service interactions should mostly be able to work with regular CORS ajax techniques.


We should validate the approach described above with a prototype which implements just the following features, and which works on both a desktop/laptop browser and an ipad or other mobile device browser.

  • Activation of the tools by clicking on the bookmarklet
  • Insertion of Context menu item to select a language
  • Insertion of Alph.Xlate.doMouseMoveOverText as Double-Click/Touch handler on the text in the page
  • Display of morphology popup with remote morphology service lookup results
  • Dictionary display activated by icon in popup