View the latest version of these documents: http://mozile.mozdev.org/0.7/docs/index.html
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 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 also an open source project, hosted by Mozdev.org, and is 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,
<script type="application/x-javascript" src="mozile/core/mozile.js"/>
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,
<div class="editor">
<p>This paragraph is editable!</p>
</div>
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 it 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/.
This document explains the details of Mozile 0.7. Mozile 0.6 is also being maintained. That version is only available as an extension, but has several features which Mozile 0.7 lacks, and may be more stable. See http://mozile.mozdev.org/ for more details.
All of 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. The file may look complicated, but most of the parts can be ignored by everyone except Mozile developers. There are four parts of the file that users may want to edit.
mozile
root directory. Examples (include only one):var mozileScriptSource = "../../";
var mozileScriptSource = "http://somewhere.com/path/to/mozile/"
var mozileScriptSource = "chrome://mozile/content/"
var mozileOptions = "debugLevel=0, warnBeforeUnload=false";
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;
var modules = [
"UndoRedo",
"XHTMLBasic",
"HTTPPost",
]; // end of modules 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 two different commands which you can use.
mozile.js Commandsmozile.createEditor("myEditor", "")
div
elements, and an editor for all elements with class="editor"
,mozile.createEditors(div
,"");
mozile.createEditors(".editor","");
Be careful not to nest one editor inside another. Mozile performs better with a small number of editors, and with small to medium sized documents.
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.
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 Mozile Object is key to editing documents with Mozile.
Mozile is configurable. You can change the default options for the Mozile Object in the mozile.js
file, thereby changing the behavious of Mozile. Here is an example of the options which can be set:
var mozileOptions = "mode=XHTML, namespace='http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd', keyboardShortcuts=true, toolbarPosition=absolute, toolbarUpdateFrequency=2, warnBeforeUnload=true, debugLevel=4";
Below are explanations for these options.
Mozile Configuration Optionsmozile
root directory. Normally this option is set by the mozileScriptSource
variable, and does not need to be included in the mozileOptions
variable.true
if you do not want to be warned before leaving a page that it has not been saved. Default is false
.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.true
or false
. The default is true
.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,
var modules = [
"UndoRedo",
"XHTMLBasic",
"HTTPPost",
]; // end of modules array
The entry which configures a module can include additional options which are described below. For each entry in the modules
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.
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.
mozileRoot/modules
.true
or false
. true
means that the remote version is always used. false
means that Mozile will use a local version if possible, which is the default behaviour.For example,
"CopyCutPaste: minVersion=1.0.2, maxVersion=1.1.2, notVersion=1.0.6, notVersion=1.1.0, remotePath='/path/to/module/' "
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. There are no special configuration options.
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 Optionstrue
or false
. The default is false
.For example,
"CopyCutPaste: requestPrivileges=false"
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 Optionsdefault=true
or default=false
. Only one save module should have the default
option set to true
. If more than one module has default=true
, then the last module with that setting will be the default."HTTPPost: url='http://yoursite.com/save.php'"
."LocalFile: file='C:\somefile.html'"
.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.
In general, Mozile does not make much use of object oriented design. The Mozile Object is large and monolithic, and is meant to have only a single instance. In the case of commands, however, Mozile uses object oriented techniques. 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 created by calling the createCommand(config)
method of a MozileCommandList object with a configuration string. This creates the command and attached it to the command list. The Mozile Object has a rootCommandList
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 rootCommandList
:
mozile.rootCommandList.createCommand("MozileWrapCommand: id=Mozile-XHTMLBasic-Strong, tag=b, mode=toggle, label=Bold, tooltip='Make text bold', accelerator='Command-B', image='../../images/bold.png'");
This list explains the common command configuration options:
Common Command Configuration OptionsAfter a command instance is created, you can override its command()
method and customize its function. For example,
var help = mozileList.createCommand("MozileCommand: id=Mozile-Help, label='Help'");
help.command = function(event) {
window.open(mozile.root+"docs/index.html", "Mozile Help", "");
}
There 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 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 "block", "list-item", "table-cell", or "moz-box".
Configuration OptionsTakes the contents of the selection, converts it to text, and replaces the old selection. This will remove any markup (i.e. tags) from the selection.
Takes the selection and wraps it inside a new tag. This can be complicated because of the nesting of tags in the document.
Configuration Optionsb
tag. Every time the command is executed the selection is wrapped in a new tag. "toggle" is 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. "block" means that the new element is treated as a block-level element.This command is like MozileWrapCommand, except that it uses a span
tag with a "style" attribute specifying CSS rules.
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.
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 calls a configuration function which creates a global instance of the Mozile Object called mozile
, as well as loading 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 commands in mozile.js
which create new Mozile editors. The Mozile.createEditor()
and Mozile.createEditors()
methods insert a CSS stylesheet into the document (using a stype 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 much more complicated widget to the document.
Basic text editing functionality is included with editors 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 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 Be warned that the tests may be broken.
Report bugs here: http://mozile.mozdev.org/bugs.html. To get in touch with Mozile developers, please use our mailing list: mozile@mozdev.org, details at http://mozile.mozdev.org/list.html.
The soure code for Mozile is available on the Web at http://mozile.mozdev.org both in downloadable files and in CVS. It is laid out in the following manner.
Mozile Source TreeJames A. Overton - http://mozile.mozdev.org - 2006-02-02