mozdev.org

MAF

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:

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

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.