Getting Started

Here's how you can get a copy of Mozile, modify your pages to use Mozile, and configure Mozile's features.

Getting Mozile

You can download the latest version of Mozile from our web site at http://downloads.mozdev.org/mozile/. Simply unzip the archive and copy the files to an accessible location on your web server.

The Mozile distribution includes demonstrations, documentation, and testing tools for development, which you may not need. You can safely delete the contents of the demos, doc, jsunit, and tests directories. It is important to leave the images, lib, and src directories intact.

Using Mozile

Once you have a copy of Mozile installed on your web server, you can include the Mozile code in your web pages. This is done by adding an HTML script tag to the head of your HTML page. The script tag should look like this:

Example 1.1. Including the mozile.js script

<script type="text/javascript" src="path/to/mozile.js"></script>

The src attribute must be a valid path from the web page to Mozile's mozile.js file. Now Mozile will be available to edit your web page, but you have to specify which parts of the document are editable. You can do this in two ways:

  • Set the contentEditable attribute to true to make that element editable.

    Example 1.2. Making an element editable woth contentEditable

    <div contentEditable="true">
    	<p>This paragraph is editable.</p>
    </div>

    Caution

    It is possible to include elements with contentEditable="false" inside editable elements, but Mozile does not yet handle this case properly.
  • Use the mozile.editElements("editor") command to edit all elements with the class="editor" attribute. See the configuration section below for more configuration options.

    Example 1.3. Making an element editable with mozile.editElement("editor")

    <div class="editor">
    	<p>This paragraph is editable.</p>
    </div>

At this point you should be able to edit your web page with Mozile in any supported web browser.

Configuring Mozile

Although the default settings should be right for most situations, you can also configure Mozile to suit your particular situation. Just add another script element, and include your configuration commands.

Example 1.4. Configuring Mozile

<script type="text/javascript" src="path/to/mozile.js"></script>
<script type="text/javascript">
	// Configuration Options
</script>

If you are using the same configuration options in many files, you can include them in a separate config.js file which all your pages can share.

Example 1.5. Configuring Mozile with a file

<script type="text/javascript" src="path/to/mozile.js"></script>
<script type="text/javascript" src="config.js"></script>

Here are some of the most important settings and configuration commands you can use with Mozile. Below is a longer description of how they work. Configuration for the save system is described in the next section.

Important Configuration Settings

  • mozile.root - Indicates where the mozile directory is relative to the document. Mozile tries to set this automatically, but sometimes it is necessary to set the root manually.
  • mozile.useDesignMode - When true the document.designMode will be used in browsers that support it. When false designMode is not used, and Mozilla/Firefox users will have to press F7 to enable an editing cursor. Because of bugs with designMode the default is now false.
  • mozile.defaultNS - Sets the default namespace URI. Should be null for HTML documents. For XHTML documents use "http://www.w3.org/1999/xhtml". For XML documents use XHTML or the your default XML namespace.
  • mozile.alternateSpace - Set this to "\u00A0" (a non-breaking space) if you want Mozile to insert spaces every time the user presses the space bar. This makes Mozile behave more like a word-processor. If no mozile.alternateSpace is specified, Mozile will keep the HTML code clean and ignore extra spaces. See below for more details.
  • mozile.emptyToken - By default this is set to "\u00A0" (a non-breaking space). In order to avoid display bugs, the empty token is automatically inserted into any empty element which has CSS display: block. See below for more details.
  • mozile.help - The URL of a help page which will be opened by a help command. Defaults to mozile.root/doc/html/index.html.
  • mozile.debug.alertLevel and mozile.debug.logLevel - These can be set to "suppress", "warn", "inform", or "debug", in order from least to most verbose. They indicate what kinds of messages the user should be alerted to, and which should be logged. To turn off all messages use "suppress".

Important Configuration Functions

  • mozile.require(module name) - Makes sure that a Mozile module is loaded.
  • mozile.editElement(element or id) - Makes a single element editable.
  • mozile.editElements(list or class) - Makes a set of elements editable.
  • mozile.editDocument() - Makes the whole document editable.
  • mozile.useSchema(schema file) - Tells Mozile to use an RNG schema to structure editing.
  • mozile.editAllText(rich) - Makes all text inside editable areas editable without using an RNG schema. The argument rich can be false for basic text editing, and true for rich editing of elements. You probably want to use either mozile.useSchema() or mozile.editAllText() but not both.

Here are some examples of configuration settings.

Example 1.6. Configure some basic Mozile options

<script type="text/javascript" src="path/to/mozile.js"></script>
<script type="text/javascript">
  // Specify the "mozile" directory.
  mozile.root = "path/to/";
  // Insert spaces like a word processor.
  mozile.alternateSpace = "\u00A0";
  // Wait until the document is loaded to run these commands.
  window.onload = function() {
    // Make all elements with class "editor" editable.
    mozile.editElements("editor");
  }
</script>

Example 1.7. Configure Mozile to edit without an RNG schema

<script type="text/javascript" src="path/to/mozile.js"></script>
<script type="text/javascript">
  // Enable rich text editing without an RNG schema.
  mozile.editAllText(true);
  // Wait until the document is loaded to run these commands.
  window.onload = function() {
    // Make all elements with class "editor" editable.
    mozile.editElements("editor");
  }
</script>

Example 1.8. Configure Mozile for XML editing

<script type="text/javascript" src="path/to/mozile.js"></script>
<script type="text/javascript">
  // Set a default XML namespace.
  mozile.defaultNS = "http://somewhere.com/xml-namespace";
  // Make the whole document editable.
  mozile.editDocument();
  // Wait until the document is loaded to run these commands.
  window.onload = function() {
    // Specify an RNG schema file to use.
    mozile.useSchema("path/to/custom-schema.rng");
  }
</script>

The most important setting is mozile.root. mozile.root tells Mozile where to find the mozile directory which contains all of the Mozile files. Mozile tries to automatically detect the location of the mozile directory by looking at the src attribute of the script tag which loaded mozile.js into the page. This should work, as long as the mozile.js is in the mozile directory. If you have moved the mozile.js file, then you must change the mozile.root setting so that it points from the web page to the mozile directory.

Another important function is mozile.require(). It will make sure that the named module has been loaded into Mozile. If one module depends on others, the dependencies will be loaded automatically. If there is a module that you do not want to load, you can either remove the mozile.require() line, or you can "comment out" that module by adding // to the beginning of the line. The // tells JavaScript to ignore the rest of the line after the double-slash, treating it as a comment and not as code.

After the modules are loaded, you can change other settings which apply to the loaded modules. In most cases you won't need to change any, but you can look at Mozile's API documentation for settings which you might like to change. You probably want to change the setting after the module has been loaded, so that you change doesn't get overridden.

Caution

If you have commented out a module, be sure to also comment out any settings that apply to that module. Otherwise there may be errors that will stop Mozile from running.

You can use the mozile.editElement(), mozile.editElements() and mozile.editDocument() methods to determine which parts of the document are editable. You can call mozile.editElement() and mozile.editElements() as many times as you like, although it only makes sense to call mozile.editDocument() once. Elements which have been marked as editable will have a new mozile property (which is an object), and the value of element.mozile.editable will be true.

You can use the mozile.useSchema() and mozile.editAllText() commands to determine how the document will be edited. It's better to use mozile.useSchema() when possible (see below) but sometimes the unstructured editing of mozile.editAllText() is the right choice. There are few cases where both would be wanted.

A window.onload = function() { ... } block is used to specify code which is supposed to be executed only after the document has finished loading. It is usually best to put mozile.editElement(), mozile.editElements(), and mozile.useSchema() commands inside this block.

Saving Changes

The changes that Mozile makes to the document are reflected immediately in the DOM. Mozile provides tools to help you save the content of the document. Currently we have a simple "display" save method and one using HTTP POST. Save functionality is provided in mozile.save module. These save options are for web site designers to configure how Mozile works in their sites. In the future we plan to include more options for Mozile users to save their content.

The default save method is mozile.save.display, which takes the content of the document and displays it as source code using the mozile.gui.display() method. For the default HTML Toolbar GUI this means displaying the source in a new window. You can then copy and paste the source code as you like.

The mozile.save.post method uses XMLHttpRequest to send the content of the document to a web server using the HTTP POST operation.

General Save Configuration

  • mozile.save.target - Indicates the node which should be saved. The default is document.
  • mozile.save.format - Used to format the saved data. Can be "uppercase" or "lowercase", which will change the case of all tag names. Defaults to null which means no reformatting is done.
  • mozile.save.warn - When true the user will be warned before she leaves a document with unsaved changes.
  • mozile.save.method - Sets the method to be used by save operations.

Save Configuration for mozile.save.post

  • mozile.save.post.async - When true the POST is done asynchronously.
  • mozile.save.post.uri - The URI to be POSTed to. Security restrictions on XMLHttpRequest require that the URI must be in the same domain as the web page it is called from.
  • mozile.save.post.user - Optional. The name of the user to POST as.
  • mozile.save.post.password - Optional. The password for the user.
  • mozile.save.post.showResponse - When true the result of the POST operation will be displayed. This is meant to be used for debugging, and it defaults to false.

Here is an example using all of these save configuration options.

Example 1.9. Configuring Mozile

<script type="text/javascript" src="path/to/mozile.js"></script>
<script type="text/javascript">
  mozile.require("mozile.save.post");
  mozile.save.target = document;
  mozile.save.format = null;
  mozile.save.warn = true;
  mozile.save.method = mozile.save.post;
  mozile.save.post.async = true;
  mozile.save.post.uri = "http://somesite.com/save_data.php?id=Mozile";
  mozile.save.post.user = null;
  mozile.save.post.password = null;
  mozile.save.post.showResponse = false;
</script>

When you call the mozile.save.save() or mozile.save.saveAs() methods, Mozile will execute the save() or saveAs() methods of the current mozile.save.module.

Of course, you can write your own code for saving changes. The first step is to create a new instance of the mozile.save.Method class. You can also make use of the mozile.save.getContent() method, which takes a Node or a Document as its argument and returns a string representation.

Warning

You must take steps to ensure that the data submitted by your users is safe. Failure to do so could result in a cross site scripting (XSS) security vulnerability.

An XSS vulnerability can occur when your site accepts content generated by one user and displays it to another user without ensuring that the content does not include malicious code. For example, an attacker posts a message to a message board with malicious JavaScript embedded. The user loads the message in his browser and the malicious JavaScript is executed: it reads the user's cookie or login information. Then the malicious code sends that information back to the attacker by setting the document.location to a URL which encodes the data, or by other means. Now the attacker has access to the user's cookie or login information, which may be used to hijack the user's account on the web site or to violate the user's privacy in other ways.

Mozile does not cause XSS vulnerabilities. Any vulnerability that exists in a web site can be exploited without Mozile. However, Mozile is usually used to edit rich HTML and submit that HTML back to a web site. Any web site that accepts HTML content from its users must be very careful to sanitize submitted data before displaying it.

JavaScript code can be embedded in script tags, src or onload attributes, or even in CSS with IE's expression statement. Not just JavaScript, but objects like Flash applets can also be used for XSS attacks. The category of XSS attacks includes a wide variety. One must be very careful.

Every site has different needs and there is no one best way to sanitize HTML. Different tools exist for different programming languages which may be used to run a dynamic web site. Most CMS systems provide tools for sanitizing submitted data. Although we cannot offer specific advice, here are some resources that should be generally useful.

XSS Resources

  • HTML Tidy - Does not sanitize data, but formats HTML in a standard way. This will make it easier for sanitizers to do their work.
  • XSS Cheat Sheet - A long list of XSS vectors.
  • Bitflux XSS Prevention - An example of using regular expressions to sanitize HTML.

Programmers should make it a habit to check all data entered by users. The web is no exception to this rule.