Technical Overview |
Overview of Technical Information for the Fabula Project
Table of Contents
- Source Code
- The Fabula Reader
- The Fabula Maker
- Modifying the Code
- Getting Involved
When Fabula was first conceived back in 1998, XML Workshop had the foresight to see that Mozilla* would be an ideal solution. Back then, Mozilla was in its infancy and working with it was quite hard, as the browser was still full of bugs. Since then, Mozilla has matured nicely, and as it turns out is the perfect platform for Fabula. Mozilla is very XML compliant, and XML forms the basis for file saving and sharing in Fabula. Mozilla is also cross-platform, so without a lot of work, Fabula can be ported to other platforms. Windows is the principle development plaform, although Macintosh computers are also quite popular in schools, which is the target audience. In fact, linux is also an important platform, as it has been speculated that Fabula can be extended to other languages in third-world countries, where linux, as a free OS, is more popular
Every package addon to Mozilla is available as an XPI file (XPI stands for Cross Platform Installer). Fabula is split into 2 XPI files, the Maker and the Reader. An XPI file is simply another zip file with the reader/maker.jar file and an install script install.js. When an XPI is opened by Mozilla or called with the InstallTrigger() function, Mozilla unzips the XPI file and runs the install.js script, which registers the chrome and copies the jar file to the chrome subdirectory of Mozilla. Mozilla must be restarted before this chrome is available. The install.js script included with the Maker and Reader is quite rudimentary, and there are better ones available from mozdev.org which should be implemented in future versions. Once the Maker or Reader is successfully installed, there are two ways to run the Maker or Reader:
- Start Mozilla from the command line like so:
mozilla -console -chrome chrome://maker/content
This is a more elegant approach and it shows what the Maker/Reader should look like in the final version. (The -console option opens the Mozilla console to print debugging information).
- Start Mozilla as usual and type the following into the url bar:
This is quite an ugly way to see fabula, but it is good for development as you can make a change to the Fabula source code and then hit refresh in the main Mozilla toolbar to see the changes (make sure you have "Disabled XUL-Cache" in the Mozilla debug options).
- Actually, a third way has been mooted. It is possible for the install script to insert an item in the tasks menu of Mozilla, which would launch the Maker/Reader. This is detailed in bug #132.
Fabula is all about stories, Making and Reading stories. Stories are stored in XML format, using a story dtd that was developed specially. Examples of elements in our story document are: <lang1>, <audio>, <wordlist>, etc. For a full set, open up a sample story from the library. A drawback to the current method of saving (as used in v1.1), is that the stories are also saved in html format. This is necessary in order to reopen the story in the Maker, as the Mozilla Editor (which forms the backend for the Maker) cannot open XML files directly. A solution to this has been discover, but won't be available until a later version (see bug #138** for more details of this solution.
Stories are rendered in the Maker and Reader by CSS, which Mozilla supports (CSS 2.0 in fact). See the reader-story.css and maker-story.css files for details on how stories are rendered. Note: the XUL files for rendering the user interface also use CSS.
The Fabula Maker also saves the XML file along with the html file. This XML file is for use with the Fabula Reader, which only opens XML files. All embedded images and sounds in the story are saved in images and sounds subdirectories of where the story XML file is, and all urls are relative to this. This is a rather messy solution, specially when it comes to distributing stories. A solution to this is detailed in bug #139, ie. to save the story and all embedded content in a zip file (.fab) using Mozilla's zip file api.
The Fabula Reader
- Opening File. Simply sets the location of the active document to the location of the XML story file you want to open.
- Images. Images are handled by embedded html <img> elements in the XML file.
- Wordlist. The wordlist is a dialog box that displays language word pairs for both languages in all the letters of the (English) alphabet. This dialog box words by calling the DOM function getChildNodes on the <wordlist> element (there is only one per story). The child nodes of wordlist are all word-pairs, which this dialog can then display, by altering the DOM attributes for the current XUL window (the wordlist window). Each time someone clicks a different letter, the words starting with that letter are displayed.
- Exiting. Exiting calls up a confirmation XUL dialog box, and if confirmed just closes the browser window (this.close()).
The Fabula Maker
The Maker is a wysiwyg editor, which looks almost the same as the Reader, except you can scroll up and down to different pages. The default story in the Maker is MakerInitPage.html. In most cases, editing stuff in the Maker will give you direct feedback to what that looks like in the Reader. The Maker saves the story in both html (in order to reopen in the Maker) and XML (in order to open in the Reader) formats. It saves/copies the images and sounds in a subdirectory of the html/xml story file. A breakdown of the main features/functions in the Maker follows:
- New Story. Opens a new browser window and loads the Maker chrome into it.
- Opening. Uses the open function in the editorshell.
- Saving. Uses the save/save as function in the editorshell. Uses the file.js file i/o library to save the XML file. The XML file is constructed from the html DOM tree using the t2s.js file, which converts a DOM tree to a string (which can then be written to a file), and also does some translation to our XML story format, eg. <img> becomes <html:img>. After that, any sounds or images are copied to subdirectories of the XML file and their URLs changed to relative. Note: by default, the editorshell asks for the title of the page, which we discard in the XML file.
- New Page. Uses the DOM cloneNode() function to copy the hidden page (which is at the end of every story). Then sets the page to not hidden.
- Insert Image. (Clicking button or clicking image will bring up this dialog). Images are already inserted on every page by default, so this dialog just changes the src attribute or this. It also inserts an xlink around the image if a hotspot sound is required. It detects the current page using the shared getPage() function, which is used throughout the maker.
- Insert Sound. Creates a new sound element before each language panel and displays them as an image in CSS. Also wraps an xlink around this, which allows playing of the sound.
- Wordlist. When this dialog opens, it checks to see if there are already words defined in the story file (in a similar manner to the reader wordlist dialog above). To add more words, this dialog clones existing words in the list, if any (actually, every story has 1 hidden word, so that others can be cloned).
- Outline View. Outline view is achieved by switching the style sheet for the story so that each page is a lot smaller and is displayed 3 across. This is done using the applystylesheet() function in the editorshell. We also need to do some fancy manipulation of <br>s in order to get 3 across in a row.
- Preview. Preview mode opens a new Mozilla window with the Reader chrome as default. It passes the url of the story as an argument to the openDialog() function. The preview function saves the story first.
- Undo/Redo. Call editorshell functions.
- Insert Extra Letters. This allows for the insertion of special characters into the story. The dialog is opened as non-modal, so the user can type at the same time as having it open. This dialog calls the insertSource() method of editorshell. Note: adding a new character in this dialog requires you add the corresponding code in t2s.js
Most of this functions are available via the toolbar, menus or popup menu.
Fabula has been localised into 9 different languages. The Fabula Reader is available in English, French, Dutch, Spanish, Welsh, Irish, Basque, Frisian and Catalan. The Fabula Maker is currently only available in English, French, Dutch, Spanish, Welsh and Frisian, but the other languages are planned.
For verion 1.1, each language is in a separate XPI file. However, Mozilla supports multiple languages in the same chrome, but this has to be implemented in Fabula, together with a language switcher (see bug #30.
Modifying the Code
Modifying the code can be cumbersome, as one must zip up the source tree as a jar file and copy it to the Mozilla chrome directory everytime (although this is probably no more complicated than having to compile a program before running it). I recommend using a batch file (there is a sample one included in the reader.jar file) or a shell script (here is an example of one). Make sure the batch/script zips the source tree up like this:
- content subdirectory of zip file containing mostly XUL and JS files.
- skin subdirectory of zip file containing mostly CSS and image files.
- locale subdirectory of zip file containing all locales for package.
- en-US subdirectory of locale containg English DTDs and property file.
- Other locales are called (although this isn't implemented in v1.1 - instead each language is a separate file with the language in en-US):
- fr French
- nl Dutch
- es Spanish
- cy Welsh
- fr Frisian
- ca Catalan
- eu Basque
- ga Irish
So, to recap, if you edit a XUL,JS,DTD, or any file, you must zip up the content tree as a jar and copy it over the maker.jar or reader.jar file in the Mozilla chrome directory. Make sure the zip file preserves the reletive directory structure as described above.
Any one can make changes to the Fabula source code, but if you would really like to contribute to the project as a whole, let us know and we can tell you what you can do.
There are plenty of bugs/features to fix/implement and a shortage of people to fix them! If you would like to get involved, please mail the Fabula Developer Mailing List or alternatively Eoin Campbell, the technical supervisor.
- fabula.mozdev.org Fabula developer resources.
- fabula.eu.org The website for fabula resources.
- XML Workshop The intitial (technical) developers of Fabula.
- Mozilla.org Where is all started.
- Bugzilla The bug-tracking system for Mozilla. If something that should work, doesn't, check if it's listed here.
- LXR The Mozilla source code.
- Bugula The bug-tracking system for Fabula. Developer password needed.
- xulplanet XUL resources.
- Mozdev.org A database for other Mozilla-based projects. A good place to find code samples.
* Mozilla is the term used in this document for the Mozilla open source browser. However, Netscape 6 and others are based on Mozilla and may be able to run Fabula.
** Bugs are recorded in bugula, which requires a username and password, which are only available to developers of Fabula
Author: David McNamara, Date: Monday February 5th, 2001