View source for MailNews:Creating New Account Types

{{Warning|Some information here is specific to current trunk builds of Thunderbird and SeaMonkey, or, in some cases, rely on patches in the review process on Bugzilla. In particular, creating a new account type in this manner does not work on the 1.8 branch (Thunderbird 2 or SeaMonkey 1.1).}}

This page aims to provide a detailed guide on creating new account types from extensions for Thunderbird and SeaMonkey. This is still a work in progress, heavily dependent on [[User:Jcranmer | my (jcranmer's)]] [http://hg.mozilla.org/users/Pidgeot18_gmail.com/index.cgi/trunk_mq/ personal tree], where some critical components are merely patches in my tree and on bugzilla (where the latter may not be the most up-to-date).

== The Account Manager ==

The best I can describe the account manager is that it is a hydra of components, managing several slightly different, but distinct, components. Primarily, these are servers, accounts, and identities. Folders, messages, message headers, databases, URLs, message DB views, the folder cache, and even more end up becoming part of this mess of topics to cover, the full scope of which is beyond the scope of this article. Needless to say, I will provide a sufficient overview to allow you to create a new account type.

For a diagram-based view of what is going on, see [[User:Emre/tb/architecture/diagrams|emre's diagrams]] on the subject. For other views, I invite you to run <tt>make documentation</tt> on the mozilla codebase to generate doxygen graphs and pages for the key components. This documentation can also be accessed at [http://doxygen.db48x.net/mozilla/html db48x's site], although I will warn you that he is using the experimental SVG output for doxygen which is quite obviously not quite production-ready.

== Step 1: Account Types ==

The first thing to do when designing a new account type is to pick an internal name. This name should probably consist of the typical characters: alphanumerics, underscores, and dashes; this name will be used heavily as URI schemes and as portions of CIDs. For sake of simplicity, let's assume that the new account type is "acct" (don't actually pick this).

Defining account types requires that you implement a few interfaces. The most important ones are <code>nsIMsgProtocolInfo</code>, <code>nsIMsgFolder</code>, and <code>nsIMsgIncomingServer</code>, while other interfaces are important if you do crazier stuff, which you most likely will. Unfortunately, most of these interfaces involve a lot of repetitive code, while the nice implementations that do the magic for us are, naturally, native C++ code that JS-based implementations are unable to provide.

=== <code>nsIMsgProtocolInfo</code> ===

{{TODO|Investigate where nsIMsgProtocolInfo is used}}

Our first interface to implement is <code>nsIMsgProtocolInfo</code>, which defines basic parameters of the account type. A fair amount appears to be special casing for local folders. The contract ID is important; set it to be <tt>@mozilla.org/messenger/protocol/info;1?type=acct</tt> in our running example. Assuming you can generate the XPCOM overhead yourself, the following is an example of what to use:

<br><br>
<!-- cruft to start a new paragraph -->

 function accountInfo() {
   this._prefs = Components.classes["@mozilla.org/preferences-service;1"]
                           .getService(Ci.nsIPrefService)
                           .getBranch("acct.");
 }
 accountInfo.prototype = {
 
   // This variable represents the pref-based directory to store all server-
   // specific configurations, like News/ or ImapMail/
   get defaultLocalPath() {
     // Good idea to set this as a default pref in your extension.
     var pref = this._prefs.getComplexValue("root", Ci.nsIRelativeFilePref);
     return pref.file;
   },
   set defultLocalPath(path) {
     var newPref = Components.classes["@mozilla.org/pref-relativefile;1"]
                             .createInstance(Ci.nsIRelativeFilePref);
     newPref.relativeToKey = "ProfD";
     newPref.file = path;
     this._prefs.setComplexValue("root", Ci.nsIRelativeFilePref, newPref);
   },
 
   // Return the IID of the server for account wizard magic. You should only be
   // changing this value if you define your own incoming server for advanced
   // account wizard magic.
   get serverIID() {return Ci.nsIMsgIncomingServer;},
   getDefaultServerPort : function (isSecure) {
     return isSecure ? 443 : 80;
   },
 
   // True if you <i>need</i> a username
   get requiresUsername() {return false;},
   // True if the pretty name should be the email address.
   get preflightPrettyNameWithEmailAddress() {return false;},
   // True if you can delete this account type
   get canDelete() {return true;},
   get canLoginAtStartup() {return true;},
   // True if you can duplicate this account type
   get canDuplicate() {return true;},
   // Do we have an "inbox" for this account type?
   get canGetMessages() {return false;},
   // Can we use junk controls on these messages?
   get canGetIncomingMessages() {return false;},
   // Can we request new message notifications ("biff")?
   get defaultDoBiff() {return false;},
   get showComposeMsgLink() {return false;},
   get specialFoldersDeletionAllowed() {return false;}
 };

All of the options--except the first three--are simple true/false boolean attributes that ask whether or not an account can do specific things. Full, up-to-date documentation is available at [http://mxr.mozilla.org/comm-central/source/mailnews/base/public/nsIMsgProtocolInfo.idl the IDL file]; note that, in a few cases, the attribute name is a poor guideline for what it actually does. These defaults should be sufficient for most people, although a lot varies on what account type you are actually providing.

The first two are special attributes that require you to think somewhat before responding. First is the default local path, a directory under which all server-specific configuration servers are stored: this is essentially your Mail/ or ImapMail folders for your specific implementation. The catch is that this is actually pref-based, where the pref is de-facto of the form "mail.root.<i>acct</i>-rel"; the "rel" is there for backwards-compatibility reasons.

Second is the IID of the server. This is simply an interface that has special properties you can set with some account wizard magic; you can set this to <code>return Ci.nsIMsgIncomingServer</code> or even omit it if you do not actually need special properties.

The third non-boolean property is the default port, with an argument that tells you whether or not the port is secure. If you scrape from the web, you could set the port to return -1 or do an 80/443 combination like I do here. It's not terribly important.

=== <code>nsIMsgIncomingServer</code> ===
The second piece of the account type puzzle is the incoming server. Of all the parts related to account types, this one is the worst. Most of the attributes are really pref-based, although some key ones are not. A few of the attributes are merely helper functions, and some are not even used at all! It is expected that this class will be extremely pared in the post-TB 3 time frame as part of a general account manager overhaul.

{{TODO|Write me! Now!}}

=== <code>nsIMsgFolder</code> ===
The third and final piece of the core account type interfaces is the message folder. If you try to be too smart here, you can create refcount loops and leak horribly. This is also the core RDF object. In large part, this class works in tandem with <code>nsIMsgIncomingServer</code> through several attributes.

== Step 2: Account Wizard Overlays ==
{{Warning|The account wizard may be going away soon, which will render this code obsolete. Until I get more information, I will not be updating this section.}}
After getting a basic account setup (or perhaps before, if you want to see results sooner), the next step is to overlay the account wizard, so that you don't force your users to either edit about:config manually or find another option in a menu somewhere.

Since the account wizard is shared between SeaMonkey and Thunderbird, there is no application-specific overlays that need to be accomplished.

Here is a sample overlay:
 &lt;overlay id="''acct''_overlay"
          xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;
   &lt;radiogroup id="acctyperadio"&gt;
     &lt;radio id="''acct''account" value="newpage, accnamepage"
            label="Account Type" accesskey="A"/&gt;
   &lt;/radiogroup&gt;
   &lt;wizard id="AccountWizard"&gt;
     &lt;script type="application/x-javascript" src="chrome://''extension''/content/account.js" />
 
    &lt;wizardpage id="newpage" pageid="newpage" label="Page Name"
                onpageadvanced="return exitCallback()"&gt;
      &lt;vbox flex="1"&gt;
        &lt;!-- Enter your page in here. See the current account wizard pages
             if you want to see a model. --&gt;
       &lt;/vbox&gt;
     &lt;/wizardpage&gt;
   &lt;/wizard&gt;
 &lt;/overlay&gt;

{{TODO|Investigate the done page some more.}}
Note that we are, in fact, overlaying two elements here: the radiogroup for the account buttons, and the wizard element for the wizard pages. The single most important part of the overlay is the <tt>value</tt> attribute of your <tt>radio</tt> items. This value is a space-separated list of the pages to be visited in order. The account wizard will automatically add a "done" page to the list that displays the various set attributes of your account type for confirmation.

{{TODO|Dynamic page changes?}}
The second most important change here is the <tt>onpageadvanced</tt> attribute of the <tt>wizardpage</tt> items, since this is how you'll be actually adding the elements. If the function returns <tt>true</tt>, the page will be advanced; if <tt>false</tt>, the page will not advance (hopefully with an error dialog box as well).

{{TODO|Describe usage? Or move to the latter sections?}}
The javascript of these functions tends to be rather simple. Two main variables are manipulated: the account data (accessed via <tt>gCurrrentAccountData</tt>) and the page data (accessed via <tt>parent.GetPageData()</tt> and <tt>setPageData</tt>).

=== <tt>identitypage</tt>: Setting up an identity ===
=== <tt>serverpage</tt>: IMAP or POP server setups ===
=== <tt>loginpage</tt>: Specifying login ===
=== <tt>newsserver</tt>: Specifying news servers ===

=== <tt>accnamepage</tt>: Adding an account name ===
This page is the page that adds the pretty account name to your account. It is highly recommended that you use this page so that you can give users the ability to customize.
{| border="1" cellspacing="1" cellpadding="2"
|+ Page requirements
|-
! Attribute !! Optional !! Object !! Get or Set
|-
| <tt>wizardAutoGenerateUniqueHostname</tt> || yes || account || get
|-
| <tt>server.hostname</tt> || yes || page || get and set
|-
| <tt>accname.prettyName</tt> || no || page || set
|-
| <tt>accname.userset</tt> || no || page || set
|-
| <tt>server.servertype</tt> || no || page || get
|-
| <tt>wizardAccountName</tt> || yes || account || get
|-
| <tt>identity.email</tt> || yes || page || get
|}

<tt>wizardAccountName</tt> is used as the pre-filled value for the account name. If <tt>wizardAccountName</tt> is not defined, this page will use <tt>identity.email</tt> as the prefill instead (except for news servers, which uses its own hack).

If <tt>wizardAutoGenerateUniqueHostname</tt> is defined (apparently a hack designed for RSS accounts, according to the sources), then it will take the server's hostname and iterate over the hostname, appending successive integers, until it finds one that doesn't exist and makes that the new hostname.

The pretty name is set to value in the text field and <tt>accname.userset</tt> is set to <code>true</code>.
=== <tt>done</tt>: Finishing it all up ===

The <tt>done</tt> page is automatically added to all accounts. This page is a final confirmation of all settings, so that the user can make sure the values are correct before creating the account itself.
{{TODO|Adding other values? It looks ISP data does something here...}}
{| border="1" cellspacing="1" cellpadding="2"
|+ Page requirements
|-
! Attribute !! Optional !! Object
|-
| <tt>wizardHideIncoming</tt> || yes || account
|-
| <tt>identity.email</tt> || yes || page
|-
| <tt>login.username</tt> || yes || page
|-
| <tt>accname.prettyName</tt> || yes || page
|-
| <tt>server.hostname</tt> || yes || page
|-
| <tt>server.servertype</tt> || yes || page
|-
| <tt>server.smtphostname</tt> || yes || page
|-
| <tt>newsserver.name</tt> || yes || page
|}
{{TODO|Finish this}}
=== Using ISP Data ===

== Step 3: The Folder Pane and Folders ==
== Step 4: Handling Subscription ==
{{Warning|Extension developers may be interested in bug 102699, which allows <tt>nsIDOMParser</tt> to parse text/html types. Until such bug is committed, however, extensions are forced to use their own workarounds to pragmatically access HTML scraped from the web.}}
{{Warning|The subscribe interface (specifically <tt>nsISubscribableServer</tt>) is undergoing drastic changes as a result of bug 457333.}}

To indicate that a server is subscribable, it needs to be able to query to <tt>nsISubscribableServer</tt>. The root folder must also return <tt>true</tt> for the attribute <tt>canSubscribe</tt>. {{TODO|Hmm, can't hack in menu yet. Should probably just move to an instanceof check}} Setting these values will allow you to open up the main subscribe dialog, used for NNTP and IMAP servers (but not RSS).

The subscribe dialog will first set your server's <tt>subscribeListener</tt>, which is the callback you will be using to display data. It will then call <tt>startPopulating</tt> in a synchronous manner. When this method is called, the server object will need to call <tt>addFolder</tt> on the listener. Once it is finished, the server will call <tt>onDonePopulating</tt> on the listener.

This first call to <tt>startPopulating</tt> is not the only way that the dialog asks the server for possible folders. If the <tt>Refresh</tt> button is clicked, the function will be called again with the <tt>forceToServer</tt> parameter set to true. If the server supports new folders, the same function will also be called with <tt>getOnlyNew</tt> set as well.

A final way of getting folders is by calling <tt>startPopulatingFromFolder</tt>. This is called every time a folder is expanded. Even if no list will be generated, the server must still call <tt>onDonePopulating</tt> at the end.

The <tt>Stop</tt> button, if pressed, will call <tt>stopPopulating</tt>.

The UI uses <tt>delimiter</tt> and <tt>showFullName</tt> for display purposes. <tt>delimiter</tt> is the character that will be used to split the folder names into a hierarchy. <tt>showFullName</tt> says whether or not the full name of the folder should be displayed or just the part following the last delimiter.

Whenever the user subscribes to or unsubscribes from a folder via the UI, <tt>setState</tt> is called. Most consumers should not need to deal with this method, as it exists purely for the benefit of those servers that need to handle search in subscribe.

When the dialog is closed, <tt>subscribeCleanup</tt> is first called. Then, the functions <tt>subscribe</tt> and <tt>unsubscribe</tt>, as appropriate are called for each groups whose subscription statuses have changed. Finally, <tt>commitSubscribeChanges</tt> is called. At the end, <tt>subscribeListener</tt> is nullified.

Supporting search in the subscribe dialog is more complicated. The server is expected to be able to query to <tt>nsITreeView</tt>, in addition to returning <tt>true</tt> for the attribute <tt>supportsSubscribeSearch</tt>. If the user types in the subscribe field, <tt>setSearchValue</tt> is called with the entered text and the tree view switches to using the server.

=== Reference implementation ===
 subscribableServer.prototype = {
   // nsIMsgIncomingServer and other interfaces elided
 
   // Basic capabilities
   get subscribeListener() {return this._subscribeListener;},
   set subscribeListener(l) {this._subscribeListener = l;},
   get delimiter() {return '\t';},
   get showFullName() {return false;},
   get supportsSubscribeSearch() {return false;},
   // Subscribe utilities
   setSearchValue: function (value) {},
   setState: function (name, subscribed) {},
 
   // Subscription population
   _downloadMessages: function (window) {
     try {
       // Get the data somewhere
       let data = ...
       for (let name in data) 
         this._add(name, data[name]);
     } finally {
       this.stopPopulating(window);
     }
   },
   _loadGroupsFromCache: function() {
       // Get the data from a connection cache
       let data = ...
       for (let name in data) 
         this._add(name, data[name]);
      }
   },
   startPopulating: function (window, forceToServer, getOnlyNew) {
     this._lists = {};
 
     if (!forceToServer && !getOnlyNew) {
       this._loadGroupsFromCache();
     }
 
     // Make sure it's done asynchronously!
     this._timer = Cc["@mozilla.org/timer;1"].createInstance(Ci.nsITimer);
     let closure = this;
     this._timer.initWithCallback({
         QueryInterface: XPCOMUtils.generateQI([Ci.nsITimerCallback]),
         notify: function() {closure._downloadMessages(window);}
       }, 0, this._timer.TYPE_ONE_SHOT);
     this._populating = true;
   },
   startPopulatingFromFolder: function (window, folderName) {},
   stopPopulating: function (window) {
     // Stop the connection if open...
     this.subscribeListener.onDonePopulating();
   },
   _add: function (name, subscribed) {
     this.subscribeListener.addTo(name, subscribed, true, true);
   },
  
   // Subscribe metafunctions
   subscribeCleanup: function () {
     this._timer = null;
     this._subscribed = {};
   },
   // Subscribe information
   subscribe: function (name) {
     // Subscribe...
     this._subscribed[name] = true;
   },
   unsubscribe: function (name) {
     // Unsubscribe...
     this._subscribed[name] = false;
   },
   commitSubscribeChanges: function () {
     for (let name in this._subscribed) {
       // Do something useful...
     }
     this._subscribed = null;
   }
 };

== Step 5: Configuration and the Account Manager ==
== Step 6: Identities and Compose ==
== Step 7: Filters and Search ==