Developing with Mozilla Archive Format

This document is a reference for add-on developers, describing the services that Mozilla Archive Format offers to other extensions installed on the same user profile. Services available to other extensions include web archive creation and extraction, metadata handling, and integration with user interface enhancements, like the ability to add file types to the save dialogs.

Supporting the MAFF file format

If you want to enable your application to use the MAFF file format, the MAF project provides support in two ways:

• For Mozilla extensions

  If you are working on a Mozilla extension and would like to add web archive support, including MAFF and MHTML, it is advisable to use the services of Mozilla Archive Format, rather than writing a custom implementation. This is also the easiest way to get bugfixes as new versions of MAF are released.

  Alternatively, since most of the source code of MAF is available under a MPL 1.1+, GPL 2.0+, LGPL 2.1+ disjunctive tri-license, you can integrate it with other extensions released under a compatible license.

• For other applications

  If you want to add support for the MAFF file format to other applications, the MAFF specification provides some of the required technical information. The specification does not depend on a specific programming language or Mozilla-based technology.

Feedback and updates

The Mozilla Archive Format interfaces described in this document are not finalized, and are likely to change as new versions are published. Extensions that use these APIs will need to be updated from time to time to reflect those changes. How often depends on the stability levels of the referenced APIs.

All of the internal MAF objects are available to other extensions, but only the methods marked as public in this API reference are actually checked for backwards compatibility. If you plan to use other methods in your extension, please get in touch and those methods will be added to the list of public methods.

Relevant changes in the interfaces of public methods will be announced on the MAF mailing list. If you would like to be notified of updates, please see the feedback page for information on how to subscribe and send messages to the mailing list.

Compatible extensions

Some extensions, like Multiple Tab Handler, are particularly suited to work together with the Mozilla Archive Format user experience. If you think your extension is in this category, or if your extension makes use of the MAF services, feel free to write to the MAF mailing list. Your extension will be taken into consideration for inclusion into the list of compatible extensions.

Compatible extensions are tested periodically with the latest version of MAF, in the areas in which they actually work together. For example, the UnMHT extension makes use of the services to add file types to the "Save As" dialog, and includes its own copy of the file type identification and MHTML encoding routines of MAF. Considering that the encoding routines work separately, the areas subject to testing are save integration and MHTML file opening.

Stability levels

• Internal

  Internal methods of the MAF objects are always available to other extensions installed in the same user profile as MAF, but may change without notice.

  All the methods that aren't listed in the API documentation are considered internal.

• Public

  Public methods and techniques are designed for use by other extensions. Changes to the interfaces of these methods will be announced on the MAF mailing list and will appear in the changelog.

  • Unstable

    Unstable public methods and techniques are likely to change in future versions of MAF. Changes will typically appear in new minor versions, and will be available in experimental releases first.

  • Stable

    Stable public methods and techniques will not change very often. If support for a stable method is dropped, this will be announced some time before the support is actually removed. This will typically happen only when a new major version is released.

API documentation

Accessing the internal MAF objects

You can access the MAF JavaScript module using the following technique:

[API status: public unstable]

// Import the Mozilla Archive Format objects
var MafObjects = {};
try {
  Components.utils.import("resource://maf/modules/mafObjects.jsm", MafObjects);
} catch (e) {
  // If MAF is not installed, an exception is thrown.
  // You may want to check for a more specialized exception type here.
}

You can then access the MAF objects using the MafObjects variable. For example:

[API status: internal]

// Create a new object
var exampleObject = new MafObjects.MaffArchive();

// Use a method from a singleton object
var exampleMethodResult = MafObjects.MimeSupport.encodeQuotedPrintable("a=b");

Adding a new file type to the save dialog

You can add a file type to the standard "Save As" dialog of Firefox or SeaMonkey using the following technique:

[API status: public unstable]

1. Create an overlay for chrome://maf/content/integration/mafCommandsOverlay.xul.

2. Add code similar to the following:

   // Create the new save behavior object
   var newSaveBehavior = new InternalSaveBehavior();
   newSaveBehavior.getFileFilter = function(aContentType, aFileExtension) {
     // Return the required values
     return {title: "Display name", extensionstring: "*.ext;*.otherext"};
   }
   newSaveBehavior.mandatoryExtension = true;
   newSaveBehavior.isValidForSaveMode = function(aSaveMode) {
     // aSaveMode is a bitmask. Return true if the filter must be
     // displayed. Display it only if the file is a type that can
     // be saved in an archive.
     return aSaveMode & SAVEMODE_MAFARCHIVE;
   }
   newSaveBehavior.isComplete = true;
   newSaveBehavior.getPersistObject = function(aSaveBrowsers) {
     // saveBrowsers is an array of browser objects
     return new MyPersistObject(aSaveBrowsers);
   }
   
   // Add the save behavior to the browser, before the one already
   //  present at index 2, assuming it is the one for saving as
   //  text only.
   gInternalSaveBehaviors.splice(2, 0, newSaveBehavior);

3. Implement the nsIWebBrowserPersist XPCOM interface in MyPersistObject. You can find an example of a JavaScript implementation in the MAF source code.