File:  [mozdev] / maf / www / dev-documentation.html
Revision 1.5: download - view: text, annotated - select for diffs - revision graph
Sat Oct 6 19:48:26 2018 UTC (15 months, 3 weeks ago) by pamadini
Branches: MAIN
CVS tags: HEAD
Align site with changeset ebc9c413b60c

<!-- MAIN CONTENT -->
<div class="maf-column-contents">

<div class="maf-box-warning">
  <p>The Mozilla Archive Format add-on is no longer maintained since
   <b>September 5, 2018</b>.</p>
</div>

<h2>Developing with Mozilla Archive Format</h2>
<p>This document is a <b>reference for add-on developers</b>, 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.</p>

<h3>Supporting the MAFF file format</h3>

<p>If you want to enable your application to use the
 <a href="maff-file-format.html">MAFF file format</a>, the MAF project provides
 support in two ways:</p>

<ul>
  <li>
    <p><b>For Mozilla extensions</b></p>
    <p>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.</p>
    <p>Alternatively, since most of the <a href="source.html">source code</a> of
     MAF is available under a <a href="http://www.mozilla.org/MPL/">MPL 1.1+,
     GPL 2.0+, LGPL 2.1+</a> disjunctive tri-license, you can integrate it with
     other extensions released under a compatible license.</p>
  </li>
  <li>
    <p><b>For other applications</b></p>
    <p>If you want to add support for the MAFF file format to other applications, the
     <a href="maff-specification.html">MAFF specification</a> provides some of
     the required technical information. The specification does not depend on a
     specific programming language or Mozilla-based technology.</p>
  </li>
</ul>

<h2><a name="stability"></a>Stability levels</h2>
<ul>
  <li>
    <p><b><a name="status-internal"></a>Internal</b></p>
    <p>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.</p>
    <p>All the methods that aren't listed in the API documentation are
     considered internal.</p>
  </li>
  <li>
    <p><b><a name="status-public"></a></a>Public</b></p>
    <p>Public methods and techniques are designed for use by other extensions.
     Changes to the interfaces of these methods will appear in the
     <a href="changelog.html">changelog</a>.</p>
    <ul>
      <li>
        <p><b><a name="status-unstable"></a>Unstable</b></p>
        <p>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.</p>
      </li>
      <li>
        <p><b><a name="status-stable"></a>Stable</b></p>
        <p>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.</p>
      </li>
    </ul>
  </li>
</ul>

<h2>API documentation</h2>

<h3>Accessing the internal MAF objects</h3>
<p>You can access the MAF JavaScript module using the following technique:</p>
<p>[API status: <a href="#status-unstable">public unstable</a>]</p>
<pre class="code"><code>// 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.
}</code></pre>
<p>You can then access the MAF objects using the <tt>MafObjects</tt> variable.
 For example:</p>
<p>[API status: <a href="#status-internal">internal</a>]</p>
<pre class="code"><code>// Create a new object
var exampleObject = new MafObjects.MaffArchive();

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

<h3>Adding a new file type to the save dialog</h3>
<p>You can add a file type to the standard "Save As" dialog of Firefox or
 SeaMonkey using the following technique:</p>
<p>[API status: <a href="#status-unstable">public unstable</a>]</p>
<ol>
  <li>
    <p>Create an overlay for
     <tt>chrome://maf/content/integration/mafCommandsOverlay.xul</tt>.</p>
  </li>
  <li>
    <p>Add code similar to the following:</p>
    <pre class="code"><code>// 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 &amp; 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);</code></pre>
  </li>
  <li>
    <p>Implement the <tt>nsIWebBrowserPersist</tt> XPCOM interface in
     <tt>MyPersistObject</tt>. You can find an example of a JavaScript
     implementation in the MAF source code.</p>
  </li>
</ol>

</div>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>