Documents

1. Mozile Documentation - A General Introduction to Mozile
2. Mozile Development - Notes on the Development of Mozile
1. JavaScript - JavaScript resources
2. DOM - Document Object Model resources
3. XUL - Extensible User-Interface Language resources
4. XBL - Extensible Binding Language resources
5. JSDoc - JSDoc documentation resources
6. JsUnit - JsUnit testing framework resources
3. Mozile Design - An explanation of the design of Mozile
1. Mozile Usage - A description of how Mozile is used (behaviour specification)
2. Mozile Core - A description of the Mozile Core code
3. Mozile Modules - A description of the Mozile Modules
4. Mozile Server-Side - A description of the Mozile Server-Side code
5. Mozile Extension - A description of the Mozile Extension code

(All Documentation in a Single File)

Contents

1. Mozile
   1. Mozile Server-Side
   2. Mozile Extension
   3. Development Versions
   4. Other Versions
2. Configuring mozile.js
3. MozileMediator
4. Mozile Modules
   1. Common Module Options
   2. General Modules
      1. XHTMLBasic
      2. UndoRedo
      3. CopyCutPaste
   3. Save Modules
      1. HTTPPost
      2. LocalFile
5. Mozile Commands
   1. MozileCommandList
   2. MozileCommandSeparator
   3. MozileBlockSetCommand
   4. MozileUnformatCommand
   5. MozileWrapCommand
   6. MozileStyleCommand
   7. MozileInsertCommand
6. How Mozile Works
7. Mozile Development
8. Building Mozile

Mozile

Mozile is a What-You-See-Is-What-You-Get (WYSIWYG) inline editor for HTML and XHTML documents. It runs in Mozilla browsers such as Firefox, is programmed using JavaScript, and makes use of advanced Mozilla technologies such as XUL and XBL. You can use Mozile on your web pages by adding a single <script> tag which links to the configuration file. You can also install Mozile as an extension in your browser, which will allow you to edit any page with the click of a button.

Mozile is an open source project, hosted by Mozdev.org, and licensed under the MPL 1.1, the GPL 2.0, and the LGPL 2.1. Note that Mozile is not conisdered a finished product. It contains some bugs, and you use it at your own risk.

Configuring mozile.js

The configuration and bootstrapping for Mozile is done in the mozile.js file. This is the only file which you must add to your document to allow Mozile to function. There are two main parts of the file that users may want to edit. The first of these is marked "CONFIGURATION" and contains some variables you may want to change:

• mozileScriptSource This field is required. It specifies the path from the document to the mozile root directory. This is the only option for which the default may not be correct, so check it carefully. Examples (include only one):
var mozileScriptSource = "../../"; var mozileScriptSource = "http://somewhere.com/path/to/mozile/"
• mozileOptions This field includes options which change the behaviour of the basic MozileMediator object. Leave the field empty if you don't have a particular option you want to add, and see below for more details on options. For example,
var mozileOptions = "debugLevel=0, warnBeforeUnload=false";
• mozileInterface The default is true, and means that the Mozile toolbar and other user interface tools will be activated. If set to false then Mozile will still allow editing of the page, and will perform faster, but without the toolbar there will be fewer editing options. The default is,
var mozileInterface = true;
• mozileModules The mozileModules array contains a list of modules which Mozile will attempt to load. Each entry is a double-quoted string, and the entries must be separated by commas. Each entry most contain the exact name of the module to be loaded. It may also contain additional options. See below for more details. An example is,
var mozileModules = [ "UndoRedo", "XHTMLBasic", "HTTPPost", ]; // end of mozileModules array

Once these configuration options are set, Mozile will be ready to run. The last thing you might want to change is the commands that Mozile runs to make your document editable. These are defined in the "COMMANDS" section, and there are three different commands which you can use.

• mozile.createEditor This command creates a single editor, given the "id" of an element in the document.
mozile.createEditor("myEditor", "")
• mozile.createEditors With this command you can create multiple editors which match a given CSS selection rule. The following examples show how to create an editor for all div elements, and an editor for all elements with class="editor",
mozile.createEditors(div,""); mozile.createEditors(".editor","");
• mozile.makeDocumentEditable This will make the entire document editable.
mozile.makeDocumentEditable("")

While it may take some work to configure Mozile the first time, a little experience will make the process much faster. Remember that you can share the same mozile.js file across many pages, or have different mozile.js files for different pages, depending on your needs.

MozileMediator

JavaScript is an object-based language, and so most of the time you manipulate DOM or browser objects to accomplish your goals. Mozile is no different. The MozileMediator object is the key to editing documents with Mozile.

Mozile is configurable. You can change the default options for the MozileMediator object in the mozile.js file, thereby changing the behavious of Mozile. Here is an example of the options which can be set:

Below are explanations for these options.

• root It specifies the path to the mozile root directory. Normally this option is set by the mozileScriptSource variable, and does not need to be included in the mozileOptions variable. In any case, the MozileMediator needs a "root" setting.
• warnBeforeUnload Set to true if you do not want to be warned before leaving a page that it has not been saved. The default is false.
• loadJIT When true Mozile will load the core.js file and then wait until editing is about to begin before loading the other files "just-in-time". The default is false, which means Mozile will load all files when the page loads.
• activateOnFocus When true Mozile will turn editing on as soon as the user clicks in an editable area. If false then you will have to use the mozile.startEditing() command to activate Mozile. Other useful commands are mozile.stopEditing() and mozile.isEditable(). The default value is true.
• replaceAnchors When true, whenever a Mozile editor is focussed Mozile will replace all the <a href="">link</a> elements with substitutes. This allows users to click inside the elements to edit them without following the links. As soon as the Mozile editor loses focus, the elements are restored. The default value is true.
• toolbarPosition Decides which method is used to position the toolbar and statusbar. The default is absolute, which means that the toolbar is moved rapidly to make sure that it's always at the top of the window. The other option is fixed, which uses the CSS position:fixed property to keep the toolbar in place. Mozile is actually faster when the absolute mode is used. There are several bugs associated with a "fixed" toolbar, and so its use is not recommended.
• toolbarUpdateFrequency An integer which determines how often the toolbar is updated. 0 means never, 1 means rarely, and 2 means often. 2 is the default, but lower levels can improve performance.
• hideInactiveCommands A Boolean value. When true inactive command buttons and menu items are hidden (using the XUL element's "collapsed" property). When false the commands are disabled (using the "disabled" property) but not hidden. The default is false.
• defaultInterval An integer which determines how many milliseconds elapse between updates for the toolbar and dialogs. The default is 100, and smaller numbers may lead to poor performance.
• keyboardShortcuts Indicates whether Mozile should use keyboard shortcuts to activate commands. The shortcuts will override the browser's shotrcuts. Can be true or false. The default is true.
• debugLevel This is an integer which allows you to filter debugging messages by their severity. 0 is the lowest level, allowing all messages to be logged. A setting of 4 will only log critical messages, which is the default.
• mode The mode setting makes small changes to Mozile's behaviour as appropriate to the kind of document. Can be one of HTML, XHTML, or XML and the default is XHTML.
• namespace Currently has no effect. Intended to allow the user to set the namespace for new elements.
• saveCharset, saveEntities, saveConversion These options apply to save modules, and are described below. By setting them here you make them the default settings for all save modules.

Mozile Modules

Additional features can be added to Mozile using modules. Modules are collections of JavaScript and other files. Mozile comes with several useful modules, and you can write your own. To add a new module you copy the files for the module into a subdirectory of the modules directory named after the module. So the XHTMLBasic module is stored in a directory called modules/XHTMLBasic/. You then add a new entry to the modules array in your mozile.js configuration file. For example,

The entry which configures a module can include additional options which are described below. For each entry in the mozileModules array, Mozile searches for the appropriate JavaScript file and imports it. To continue the example, when Mozile is loaded it would search for the "XHTMLBasic.js" file in the modules/XHTMLBasic directory, and then it would add a <script> element to the document which points to that file.

Mozile Commands

The interface.js file and the XHTMLBasic module include a system for defining commands which can manipulate the document in more advanced ways than basic text editing. In order to use commands, mozileInterface must be set to true in the mozile.js configuration file. Most of the commands also require the XHTMLBasic module to be loaded.

Mozile makes good use of object oriented design. There is a MozileCommand class with common functionality, and a number of subclasses with specialized functionality. For instance, there is a MozileCommandList subclass which allows commands to be grouped together.

The MozileCommand class provides methods for creating and controlling XUL buttons and menuitems, which allow the user to access the command from the Mozile toolbar. It also provides for keyboard shortcuts and for executing the command.

Commands are usually created by calling the createCommand(configString) method of a MozileCommandList object and providing a configuration string. This creates the command and attached it to the command list. The MozileMediator object has a root command list which can be accessed with mozile.getCommandList() and which forms the top level of the Mozile toolbar.

The configuration string for a command looks much like the configuration string for a module. It has the name of a command type (a class), followed by a colon and several options. Here is an example of a command added to the root command list:

This list explains the common command configuration options:

• id Required. The unique id by which this command is known.
• label The label for this command. A very short phrase.
• undoable A Boolean value which determines whether this command can be undone or not. Default is true.
• tooltip Not currently working. A short phrase describing what the command does.
• image A path to an image file for the command's icon.
• accesskey Accesskeys are used to allow keyboard navigation of a menu. It should be a letter from the command's label which is different from the other accesskeys in the group.
• accelerator The keyboard shortcut for the command. Accelerator format must follow this sequence: "Command-Meta-Control-Alt-Shift-Key". Mozile will check the UserAgent string for the browser, and replace "Command" with "Control" on Linux and Windows, or "Meta" on Macintosh. One of "Command", "Control" or "Meta" must be present, and "Key" is a single uppercase character.
• buttonPosition A non-negative integer indicating the position the command's button should have in its group.
• menuPosition A non-negative integer indicating the position the command's menuitem should have in its group.

After a command instance is created, you can override its command() method and customize its function. For example,

There are several subclasses of the MozileCommand class, each with its own specialized functionality, described below.

How Mozile Works

This is a high-level overview of how Mozile works, from a technical perspective. The system may seem overly complex, but in many ways the technologies being used are being stretched beyond their original intentions.

Mozile is a set of JavaScript functions which manipulate the Document Object Model (DOM) of a web page. It includes functions which insert text into a text node, which wrap a selection in a new element, and which change the properties of elements. Modules add features like copying and pasting, undo, and saving the contents of the document to a local file or sending them via HTTP POST.

You activate Mozile either by including the mozile.js file in the document with a script tag, or by using the Mozile Extension to insert the mozile.js script tag. The mozile.js file contains code which inserts another script tag, pointing to the core.js file. Once core.js loads it creates a global instance of the MozileMediator object called mozile and loads any modules which have been configured. The modules are loaded using the same script tag insertion technique.

Once all Mozile code and modules are loaded, Mozile executes mozileConfiguration() in mozile.js which create new Mozile editors. The mozile.createEditor() and mozile.createEditors() methods insert a CSS stylesheet into the document (using a style tag), and add CSS rules for the editors. These CSS rules include the -moz-binding property, which binds an XBL widget to an element in the document. The XBL bindings are stored in the core.xml file.

XBL bindings have content, implementation, and handlers. The Mozile editors use very simple XBL. The content of an XBL widget can include anonymous elements, but the editors do not. The editors have a constructor, which registers them with the global mozile instance. They also have handlers, which catch mouse and keyboard events as they pass through the bound element, and call a global function to handle them.

The DOM is a hierarchy, which we can think of as a tree. Events start at the leaves, and proceed up toward the root. When an event comes through a Mozile editor, the editor attempts to handle it. Mozile tracks focus, blur, keypress, keyup, and mouseup events. Each has a different handler function, which calls other functions as needed.

The discussion so far has ignored the Mozile toolbar and other interface tools. When the variable mozileInterface in mozile.js is set to true, Mozile will load the interface.js file. This file includes additional code dealing with the Mozile toolbar, status bar, various popups, and additional commands. The Mozile interface also uses XBL to bind a more complicated widget to the document.

Basic text editing functionality is included by default. To add more functionality you can define MozileCommand objects and register them with the global mozile instance. This requires mozileInterface to be true. There is a hierarchy of MozileCommand objects, which serve different purposes. These include a MozileCommandList object which groups commands, and (in the XHTMLBasic module) MozileBlockSetCommand, MozileUnformatCommand, MozileWrapCommand, MozileStyleCommand, and MozileInsertCommand. These can be configured with options which specify keyboard shortcuts, icon images, labels, and more. The commands can also be provided with functions which specify when that command is available, which allows for context sensitive functionality. Commands will show up in the Mozile toolbar as buttons or list items. See the section above for more details.

When the document is saved, Mozile makes a copy of the whole document and removes the script and style tags that were added to insert JavaScript code and CSS rules.

Mozile Development

Mozile is written in JavaScript. Documentation is done using JSDoc, which is similar to JDoc. The JSDoc files are included with the development versions of Mozile or at the Mozile website (http://mozile.mozdev.org/0.7/docs/jsdoc/). Tests are written using JsUnit, and provided with the development versions. To test Mozile in your browser, go to http://mozile.mozdev.org/0.7/testing/index.xml If you notice that some of the test are failing, please report the problem and include the "Errors and failures" information that JsUnit provides.

Report bugs here: http://mozile.mozdev.org/bugs.html. Please include as much information as you can, such as: exact Mozile version, Server-Side or Extension, browser name and exact version, operating system, a URL if possible, and the steps we should take to reproduce the bug.

To get in touch with Mozile developers, please use our mailing list: mozile@mozdev.org, details at http://mozile.mozdev.org/list.html. You're also welcome to visit us on IRC at irc://irc.freenode.net/#mozile".

The soure code for Mozile 0.7 is available on the Web at http://mozile.mozdev.org/0.7/ both in downloadable files and in CVS. The code for 0.7 laid out in the following manner.

• core The Mozile Core code.
• demos Contains demonstrations of Mozile in action.
• docs Mozile documentation, including these files.
• jsdocs Contains the JSDoc documentation for Mozile.
• WWW Contains a version of the general documentation rendered for the Mozile web site.
• XHTML Contains a version of the general documentation rendered into XHTML.
• XML Contains the original version of this documentation.
• extension The Mozile Extension code.
• mozile The main code directory.
• package Storage of packages and build tools.
• images All images used by Mozile.
• jsunit Contains code for the current version of the JsUnit testing framework.
• modules Contains all the Mozile modules.
• server-side The Mozile Server-Side code.
• mozile The main code directory.
• package Storage of packages and build tools.
• testing Contains Mozile's JsUnit testing code.

Building Mozile

Mozile provides an Apache Ant build script in the tools directory. It can generate documentation, compress JavaScript files, and package Mozile for deployment as a server-side or XPI package. The build.xml file describes the logic, and the settings are in the build.properties file.

Once you have Ant installed, open a terminal and cd to the tools directory. Then just run ant to see a help message explaining the build options.