Mozile (xhtml editing in your browser)
|resources:||Home Use FAQ Contribute Mailing List Plan Source Code Bugs|
Welcome to Mozile, the WYSIWYG XHTML editor for Mozilla! This document includes information for using and developing Mozile. It is a work in progress, and we welcome suggestions and contributions.
- Mozile Documentation - A General Introduction to Mozile
- Mozile Development - Notes on the Development of Mozile
- DOM - Document Object Model resources
- XUL - Extensible User-Interface Language resources
- XBL - Extensible Binding Language resources
- JSDoc - JSDoc documentation resources
- JsUnit - JsUnit testing framework resources
- Mozile Design - An explanation of the design of Mozile
- Mozile Usage - A description of how Mozile is used (behaviour specification)
- Mozile Core - A description of the Mozile Core code
- Mozile Modules - A description of the Mozile Modules
- Mozile Server-Side - A description of the Mozile Server-Side code
- Mozile Extension - A description of the Mozile Extension code
- Configuring mozile.js
- Mozile Modules
- Mozile Commands
- How Mozile Works
- Mozile Development
- Building Mozile
- Mozile Server-Side
- Mozile Core
- Mozile Modules
- Mozile Server-Side
- Mozile Extension
<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.
As a web developer, the easiest way to allow your users to use Mozile to edit your pages is to install Mozile as a set of server-side tools. You can download the latest version of the
mozile-0.7.X.zip file from the Mozdev.org mirrors at http://downloads.mozdev.org/mozile/.
To use Mozile, you need to add a
<script> tag to the
<head> of all the documents you want to edit, and set the
src attribute to point to the
mozile.js configuration file. For example,
You can then change the configuration file to suit your needs. See the notes below. By default, Mozile will make any element which has the attribute
class="editor" into a Mozile editor. For example,
You will also want to take a look at the modules which are available to extend the capabilities of the Mozile core code.
Mozile can also be installed as an extension into your Mozilla (SeaMonkey) or Firefox browser. Although Mozile works with both browsers, Firefox has much better support for extensions (particularly uninstalling them), and is recommended over Mozilla.
You can download the latest
mozile-0.7.X.xpi file from the Mozdev.org mirrors at http://downloads.mozdev.org/mozile/ Your browser may block the installation until you add "mozdev.org" to the list of site which are allowed to install extensions. The browser will ask permission to install the extension. Once the extension is installed, you will have to restart the browser.
With the Mozile extension installed, you can go to the "File" menu and select "Edit this page" to make any page editable. In Firefox you can also select "View -> Toolbars -> Customize..." and add the Mozile edit button to your toolbar. In Firefox you can select "Tools -> Extensions", pick "Mozile" from the list, and select "Preferences" to change the Mozile settings.
If you want to help develop Mozile, or see how it works, you can download a devlopment version of the Server-Side or Extension versions. Look for files named
*-devel.* on the Mozdev.org mirrors at http://downloads.mozdev.org/mozile/.
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
mozileroot directory. This is the only option for which the default may not be correct, so check it carefully. Examples (include only one):
- 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,
mozileInterface The default is
true, and means that the Mozile toolbar and other user interface tools will be activated. If set to
falsethen 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,
- 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 mozileScriptSource = "../../"; var mozileScriptSource = "http://somewhere.com/path/to/mozile/"
var mozileOptions = "debugLevel=0, warnBeforeUnload=false";
var mozileInterface = true;
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.js Commands
- mozile.createEditor This command creates a single editor, given the "id" of an element in the document.
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
divelements, and an editor for all elements with
- mozile.makeDocumentEditable This will make the entire document editable.
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.
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.Mozile Configuration Options
root It specifies the path to the
mozileroot directory. Normally this option is set by the
mozileScriptSourcevariable, and does not need to be included in the
mozileOptionsvariable. In any case, the MozileMediator needs a "root" setting.
warnBeforeUnload Set to
trueif you do not want to be warned before leaving a page that it has not been saved. The default is
trueMozile will load the
core.jsfile 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.
trueMozile will turn editing on as soon as the user clicks in an editable area. If
falsethen you will have to use the
mozile.startEditing()command to activate Mozile. Other useful commands are
mozile.isEditable(). The default value is
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
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:fixedproperty to keep the toolbar in place. Mozile is actually faster when the
absolutemode 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.
1means rarely, and
2is the default, but lower levels can improve performance.
hideInactiveCommands A Boolean value. When
trueinactive command buttons and menu items are hidden (using the XUL element's "collapsed" property). When
falsethe commands are disabled (using the "disabled" property) but not hidden. The default is
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
false. The default is
debugLevel This is an integer which allows you to filter debugging messages by their severity.
0is the lowest level, allowing all messages to be logged. A setting of
4will 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
XMLand the default is
- 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.
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
modules/XHTMLBasic directory, and then it would add a
<script> element to the document which points to that file.
Modules have version numbers which can be checked to make sure that an appropriate version is being used. Versions are specified using the common X.Y.Z format, where X,Y, and Z are non-negative integer numbers. For example, a module could have version 1.1.1 or 0.2.0. If you restrict the versions which are allowed, Mozile will not load a module which has an invalid version number. You can also specify a path to a module which is different than the usual
modules/ModuleName path. Below are the options which are common to all modules.
- minVersion Determines the lowest module version.
- maxVersion Determines the highest module version.
notVersions Excludes a set of particular version numbers. For example
- requireVersion Requires that the loaded module has precisely the specified version number. This option takes precedence over other options.
remoteVersion This option means that the directory which holds the module will not be simply
ModuleName-remoteVersion. Use this option when you have more than one version of a module installed, and you want to pick between them.
remotePath Specifies a path to the module, which will override the default path of
forceRemote Not implemented. Can be
truemeans that the remote version is always used.
falsemeans that Mozile will use a local version if possible, which is the default behaviour.
The XHTMLBasic module adds a set of basic XHTML editing tools. This includes: bold, italic, underline, and strikethrough; superscript and subscript; fonts and sizes; paragraphs, lists, and headings; text and background colors; and inserting images, links, etc.Configuration Options
semantic Determines whether Mozile should use semantic markup (e.g.
<strong>) or non-semantic markup (e.g.
<b>). This option can be set to
false. The default is
This module adds the ability to undo and redo editing actions. There are no special configuration options.
The module adds the ability to copy, cut, and paste text. By default it only works within a document. This is because of security features which are built into the browser, and prevent a web page from inspecting your system clipboard. The module can be set to ask permission from the user which (if granted) will give it access to the system clipboard and allow cutting, copying, and pasting between the document and all the user's applications.Configuration Options
requestPermissions Determines whether Mozile should ask permission to use the system clipboard. Note that granting permission can be a security risk. This option can be set to
false. The default is
By default, when the user wishes to save the file she is editing, Mozile will show a dialog with the source code for the file. To add more saving options, you need to add Mozile modules and configure them in the
mozile.js configuration file.
You add and configure a save module just like a normal module. Here are some of the options you can use to configure a save module.Common Configuration Options
default Sets a save module to be used by default. Can be
default=false. Only one save module should have the
defaultoption set to
true. If more than one module has
default=true, then the last module with that setting will be the default.
- saveCharset Determines the character set which Mozile will use to save the document contents. The default is to use the document's character set.
saveEntities Determines which characters Mozile will convert into HTML entities when saving. Options are
transliterate. Multiple options can be included. The default is
none. For example,
- html40latin1 Convert Latin1 chars. (  to ÿ)
- html40symbols Convert W3C Greek, General Punctuation, Letterlike Symbols, Arrows, Mathematical Operators, Miscellaneous Technical characters.
- html40special Convert General Punctuation characters.
- mathml20 Convert Mathematical Markup Language 2.0 entities.
transliterate Convert certain extended chars into ASCII equivalents. (e.g. Capital A with a circumflex accent to A^). Warning: you could end up with some
>characters in the middle of your xhtml.
saveConversion Determines some of the details of the character set and entity conversion Mozile performs. Multiple options can be included, but some options are mutually exclusive. For HTML and XHTML the defaults are
decimalncr. For XML by default no options are set. For example,
- none Don't create entities.
- entitybeforecharset Create entities before converting to the save charset.
- entitiyaftercharset Convert to the save charset, then create entities.
- nofallback Ignore unknown characters that don't have text entity equivalents.
- questionmark Replace unknown chars with a question mark.
- escapedunicode Replace unknown chars with a string representing the Unicode hexadecimal value. E.g. \u03a9
- decimalncr Replace unknown chars with a decimal numeric character reference. E.g. Ω
- hexncr Replace unknown chars with hexadecimal numeric character reference. E.g. Ω
- charsetfallback If there is an invalid character, try and guess what the correct charset is and use this instead of the specified charset. The exact effect of this option is unknown.
- ignoreignorables Ignore default ignorable code points. (Max thinks this means Unicode characters above U010000.) The exact effect of this option is unknown.
saveEntities=[html40latin1,html40symbols]Save Entities Options
saveConversion=[entitybeforecharset, ignoreignorables, decimalncr]Entity Conversion
This module sends the contents of the document to a URL using the HTTP POST method.Configuration Options
url This should be a string including the full path to the location where the document should be saved. For example:
This module saves documents to the local file system.Configuration Options
file This should be a string including the full path to the location where the document should be saved. By default Mozile will prompt for the save location. If you are accessing the current document using the
file://protocol, Mozile tries to save to the original file. For example:
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: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
- 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.
As discussed above, this special type of command is used for grouping other commands together. By itself it performs no action.
This does nothing except render a separator in the toolbar or menu where it appears.
This command changes the block-level element which contains the current selection. For example, you can change a paragraph to a heading. Block level elements are those which have the CSS
display property set to
- tag Required. The name of the new tag to replace the old none.
This command operates in three different ways. If the "tag" option is set, it will start at the selection and remove the first ancestor tag with the matching name. If the "tag" option is not set and text is selected, then all the markup will be removed from that selection. If there is no "tag" option and no selection, then the current element is "unwrapped": the elements is removed but is contents are inserted in its place.Configuration Options
tag Optional. The name of the tag to be removed by this command. For example,
tag=acreates an "unlink" command.
Takes the selection and wraps it inside a new tag. This can be complicated because of the nesting of tags in the document.Configuration Options
mode Required. Can be
inlinemeans that the new element is not block-level, and could be something like a
btag. Every time the command is executed the selection is wrapped in a new tag.
toggleis different because it checks to see if the selection is already inside a tag of the given type, and if so it removes the selection from that tag. This allows the user to toggle the tag on and off, like one usually does in a word processor.
blockmeans that the new element is treated as a block-level element.
- tag Required. The name of the new tag to replace the old none.
This command is like MozileWrapCommand, except that it uses a
span tag with a "style" attribute specifying CSS rules.
mode Required. Like the same option for MozileWrapCommand, with the addition of a
toggleBlockmeans that the style for the whole block is changed, and can be toggled back. The
toggleBlockoptions look for the parent block-level element and set its "style" attribute.
- style Required. A string with the contents of the new "style" attribute.
Inserts a node into the document, replacing the current selection. There are no configuration options, but you must define a new method for the command called
createNode() which will return a copy of the node to be inserted.
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.
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
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
mozile.js which create new Mozile editors. The
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
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
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
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: email@example.com, 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.Mozile Source Tree
- 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.
Mozile provides an Apache Ant build script in the
build.xml file describes the logic, and the settings are in the
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.
The Document Object Model is the W3C standard for accessing and manipulating the contents of an HTML, XHTML, or XML document.
Mozile's main purpose is to provide easier access to the functionality that the DOM makes possible.
The XML User-interface Language is the markup language that Mozilla uses to define it's UI. It's about as easy to write as HTML, but provides a set of widgets better suited to UI design.
Mozile's toolbar and popups use XUL.
The eXtensible Binding Language is a little known but very interesting Mozilla technology. It allows you to define "bindings" which attach "anonymous content" to elements in the DOM. The anonymous content is not seen by normal manipulations of the DOM, but it is displayed. By using XBL and XUL you can change a simple XHTML tag into a customized widget, with all sorts of special behaviour. The best part is that the underlying XHTML code stays nice and clean.
Mozile uses XBL to bind its editors to elements of the document. The editors then catch events as they move up the DOM tree, and send them to Mozile for handling. XBL is also used for the Mozile toolbar.
Ideally, every non-trivial function in Mozile should have at least one JsUnit test. This would allow the automated testing of Mozile code for bugs.
Right now there are tests for every class in Mozile, but not all methods are tested. We would like to have better unit test coverage.
We would also like to add functional tests which check Mozile as a whole by simulating user interaction. Currently there are none.
This document describes the behaviour that Mozile presents to the end user, the person actually editing pages using Mozile. Since there are two ways of deploying Mozile, below are sections describing the use of both Mozile Server-Side and the Mozile Extension. After these section is a discussion of common tasks, such as editing, saving, and configuring Mozile. This document does not cover the deployment of Mozile.
The following modules are complete and included with Mozile 0.7:Finished Mozile Modules
- XHTMLBasic Standard XHTML editing tools
- CopyCutPaste Clipboard functions
- UndoRedo Undo/Redo features
- HTTPPost Saving via HTTP Post
- LocalFile Saving to local filesystem
The following are some module possibilities:Possible Mozile Modules
- CSSEdit Advanced editing of CSS styles
- Debugging Advanced debugging tools, mainly for developers
- FormEdit Advanced editing HTML forms
- ImageEdit Image picking, sizing, and cropping
- MathEdit MathML editing
- MES Mozile Editing Scheme support
- RNGValidation Validation against RelaxNG schemas
- ShowTags Show labels on tags
- SourceEdit Allow editing of document source
- SpellChecking Allow spell checking
- TableEdit Allow editing of tables
- WebDAV Saving via WebDAV
- XSDValidation Validation against an XML Schema
James A. Overton - http://mozile.mozdev.org - 2006-11-01