Annodex Firefox Extension Viewer (AFE): Core XUL Documentation

Table of Contents

1.0 Installation of the Annodex Firefox Extension

Note: These installation steps are intended for developers; end-users will be supplied with a Mozilla .xpi package that they can simply download and double-click on to install. For Windows users, a batch file for Firefox Browser users called "WinSetup.bat" semi-automates the installation process, with minor configuration changes required as prompted at the end of the installation. The three main points of installation are as follows:

1. Installing the Mozilla AFE Chrome:
   1. Copying the /Core/chrome/afeview/ directory to the Mozilla Firefox Chrome directory.
   2. Creating or modifying an installed-chrome.txt file to initialise the AFE Chrome with Mozilla Firefox, and deleting the existing chrome.rdf file.
2. Installing the ANXLoader Mozilla Component:
   1. Copying the components\ANXLoader.js file to the Mozilla Firefox Components directory.
   2. Deleting the compreg.dat auto-configuration file to be regenerated upon startup of Mozilla Firefox for initialising ANXLoader.
3. Installing the Media Engine Component: Please refer to Media Engine documentation for installation of plug-in libraries.
   1. Copying the platform dependent binary plug-in to the Mozilla Firefox plugins directory.

1.1 Installing the Mozilla AFE Chrome:

1. Copy, symlink or junction¹ the /Core/chrome/afeview/ directory to your chrome installation directory.
   
   For the Firefox Browser:
   • On Windows the default directory is "C:\Program Files\Mozilla Firefox\chrome"
   • On MacOS X the default directory is "/Applications/Firefox/Contents/MacOS/chrome"
   • On Linux the default directory depends on the variant of your operating system

   For the Mozilla Internet Suite:

   • On Windows the default directory is "C:\Program Files\mozilla.org\Mozilla\chrome"
   • On MacOS X the default directory is "/Applications/Mozilla.app/Contents/MacOS/chrome"
   • On Linux the default directory depends on the variant of your operating system
      
2. Create or modify a file called installed-chrome.txt file in your browser installation's chrome/ directory, and add the following lines:
   content,install,url,resource:/chrome/afeview/content/
   skin,install,url,resource:/chrome/afeview/skin/
    
3. Delete the chrome.rdf file from your Mozilla installation's chrome/directory if it exists. (This file is created by Mozilla as a cache for the installed-chrome.txt file, hence Mozilla will not read the new installed-chrome.txt with the location of the afeview chrome if it is not deleted.
    
4. To test whether your chrome installation has been successful, try opening the URL in Mozilla:
   chrome://afeview/content/

Footnote 1: Junctions in Windows are similar to symbolic links in UNIX, with the additional restriction that they can only 'symlink' to other directories or roots of disk drives. You can create them with Sysinternals's free junction utility: http://www.sysinternals.com/Utilities/Junction.html

Example: You could create a junction for our purposes by doing this:
junction "C:\MyCodeRepository\AnnodexGeckoPlugin\chrome\afeview"
"C:\Program Files\Mozilla Firefox\chrome\afeview" or "C:\Program Files\mozilla.org\Mozilla\chrome"

1.2 Installing the ANXLoader Mozilla Component

The ANXLoader component associates the "application/x-annodex" MIME type with the AFEView chrome, so that chrome://afeview/content/afeview.xul is launched whenever the user loads any file of type application/x-annodex. The installation procedure is slightly different depending on whether you use the Mozilla browser and email client suite, or the standalone Firefox Web Browser:

1.2.1 Firefox Browser

• In Windows: Copy the components\ANXLoader.js file to your "C:\Program Files\Mozilla Firefox\Components\" directory. Then, you will need to delete the following XML configuration file, so that Firefox rescans the components directory for new files the next time it starts up:
  
  C:\Documents and Settings\YOUR_USERNAME\Application Data\Mozilla\Firefox\Profiles\XXXXXXXX.default\compreg.dat
   
• Mac OS X: Copy or symlink the components\ANXLoader.js file to your "/Applications/Firefox.app/Contents/MacOS/components/" directory. Then, you will need to delete the following file, so that Firefox rescans the components directory for new files the next time it starts up:
  
  ~/Library/Application Support/Firefox/Profiles/default.XXX/compreg.dat
   
• Linux: Copy the ANXLoader.js file to the default components directory of your Firefox installation. You must locate and delete the compreg.dat profile file for Mozilla Firefox to correctly reconfigure the plug-in at next restart.

1.2.2 Mozilla Internet Suite

• Windows: Copy the ANXLoader.js file to your "C:\Program Files\mozilla.org\Mozilla\components" directory. Then, you will need to delete the following XML configuration file, so that Mozilla  rescans the components directory for new files the next time it starts up:
  
  C:\Program Files\mozilla.org\Mozilla\components\compreg.dat
   
• Mac OS X: Copy or symlink the ANXLoader.js file to your "/Applications/Mozilla.app/Contents/MacOS/components/" directory. Then, you will need to delete the following XML configuration file, so that Mozilla rescans the components directory for new files the next time it starts up:
  
  /Applications/Mozilla.app/Contents/MacOS/components/compreg.dat
   
• Linux: Copy the ANXLoader.js file to the default components directory of your Mozilla installation.

2.0 Building the Annodex Firefox Extension

The chrome and media engine are packaged as separate .XPIs. While the chrome is the same on all platforms, a different video plug-in is required for each operating system and CPU architecture. The two main components to AFE are as follows:

1. The Chrome:
   Chrome is also known as the 'Core' XPI. This is a Mozilla XUL (XML User Interface Language) application providing the overall video browsing user interface. This shows the basic clip list, transport controls and media display. The chrome is platform-independent, and it registers itself with Mozilla as the handler for application/x-annodex, and it embeds the video plug-ins. The AFE Chrome also handles the parsing of CMML metadata and clip information implementing JavaScript's XML to RDF parser functions.
    
2. Media Engine: Refer to the Media Engine documentation for further details.
   The media engine is a Mozilla plug-in used to do the playback and rendering of the audio or video. Currently, we use the VLC Mozilla plug-in as the media engine on all platforms, though this may change in the future. The video plug-in is native code specific for each of the supported platforms on Windows, Linux (x86 and PowerPC) and MacOS. Each media engine registers with Mozilla as an application/x-annodex-player plug-in; e.g. the VLC media engine is registered as application/x-annodex-vlc-viewer-plugin.

2.1 Building the Chrome XPI

1. The Installer/MakeCoreXPI.sh script packages the .XPI for the chrome. The packages should work without any preparation, as there are no binaries to compile for the chrome XPI.
2. To run the modified Javascript code for testing and debugging purposes, you must shutdown Mozilla Firefox for changes to take effect upon startup. This is because all the XUL and the Javascript code is loaded into memory upon startup. The use of existing Javascript debuggers for Mozilla Firefox as a plug-in will identify the ANXLoader.js files, but it may not be able to trace the internal Javascript code.
   
   Note: The Installer/install.rdf file defines the web location of the updates.rdf file for the XUL Core to look for version differences between the local copy of the XUL Core and the version available online. Installer/updates.rdf is the script file that defines the latest version of the XUL Core residing on the server available for download.

2.2 XUL Core Directory Structure