Content Tabs

This content covers features introduced in Thunderbird 3

Content Tabs enable Thunderbird to display remote content in a tab, which users can browse in (mostly) the same way as with a browser. For example, invoking Thunderbird's Help | What's New menu option opens a tab that displays web content. The Thunderbird team can update this content via the website at any time.

Content Tabs can take advantage of form fill, autocomplete, password manager, cookies, "find as you type" and a range of other browsing features.

New in Thunderbird 3.3 Content tabs now also support favicons.

Opening a Content Tab

A Content Tab is opened via the tabmail interface. The following example checks the user preference for whether new messages should be opened in a tab or message window, then displays the "What's New" page for nightly builds of Thunderbird (in either a Content Tab or a new message window, depending on the user's preference settings).

let url = "http://www.mozillamessaging.com/en-US/thunderbird/nightly/whatsnew/";
let tabmail = document.getElementById("tabmail");
if (!tabmail) {
  // Try opening new tabs in an existing 3pane window
  let mail3PaneWindow = Components.classes["@mozilla.org/appshell/window-mediator;1"]
                                  .getService(Components.interfaces.nsIWindowMediator)
                                  .getMostRecentWindow("mail:3pane");
  if (mail3PaneWindow) {
    tabmail = mail3PaneWindow.document.getElementById("tabmail");
    mail3PaneWindow.focus();
  }
}

if (tabmail)
  tabmail.openTab("contentTab", {contentPage: url});
else
  window.openDialog("chrome://messenger/content/", "_blank",
                    "chrome,dialog=no,all", null,
                    { tabType: "contentTab",
                      tabParams: {contentPage: url} });

To test out opening something in a Content Tab, you can enter the following in the Error Console and press Evaluate:

Components.classes['@mozilla.org/appshell/window-mediator;1'].getService(Components.interfaces.nsIWindowMediator).getMostRecentWindow("mail:3pane").document.getElementById("tabmail").openTab("contentTab", {contentPage: "http://www.mozillamessaging.com/en-US/thunderbird/nightly/whatsnew/"});

Both the above examples will open a Content Tab with a default click handler.

Handling clicks

Opening a Content Tab without a specified click handler will use a defaultClickHandler. The default click handler will push any about:, http: or https: links out to the external browser and will load any others internally or externally depending on the setting of the network.protocol-handler.expose.* preferences.

You can explicitly specify the defaultClickHandler by providing a clickHandler argument when opening the Content Tab. Note that this is the equivalent to not providing a clickHandler argument:

tabmail.openTab("contentTab", {contentPage: url,
                               clickHandler: "specialTabs.defaultClickHandler(event);" });

The clickHandler is the value inserted into the onclick attribute of the browser element created for the contentTab.

Limiting browsing to certain sites

Thunderbird supplies a siteClickHandler, which takes an extra argument (a regular expression). This results in the following functionality:

  • If the link clicked has an http or https scheme and the regular expression does not match the link, the link will be opened in the external browser.
  • Otherwise, the link will be opened internally in the browser element (and according to the network.protocol-handler.expose.* preferences).

Note: Due to the limitations of http and the possibility for redirects, if sites change or use JavaScript, the onclick handlers may not be able to ensure the contentTab stays within a site. Extensions using this function should consider this when implementing the handlers.

A good example of this site limitation is the Personas extension. It can open a Content Tab for browsing its gallery, but as soon as the user tries to go outside the site they are pushed to their external browser, which will provide them with better overall support for general browsing. The code to do this is relatively simple and is reduced down to:

let PersonasController = {
  get _thunderbirdRegExp() {
    delete this._thunderbirdRegExp;
    return this._thunderbirdRegExp = new RegExp("^http://www.getpersonas.com/");
  },


  openURLInTab: function (url) {
    ...
    openTab("contentTab", { contentPage: url,
                            clickHandler: "specialTabs.siteClickHandler(event, PersonaController._thunderbirdRegExp);" });
    ...
  }
};

Other click handlers

Extensions can provide their own click handlers, although they should be based on the siteClickHandler, which should be checked regularly for any updates that fix bugs.

Saving click handlers

Content Tabs are hooked up to the session persistence code that tabmail provides. The click handler will be saved alongside the Content Tab URL and restored when the application is restarted.

Extending Content Tabs

Extensions can extend Content Tabs in two ways: by extending the current Content Tab code (which will affect all extensions) or by providing your own template and support code.

If you wish to implement your own specific types, then you need to look at:

Security

Extensions should consider security issues. Thunderbird provides a minimal security UI at the moment, given that it doesn't support browsing by default. Various security considerations include:

Installation of add-ons

New in Thunderbird 3.1 Content tabs have in-built support for loading add-ons from non-whitelisted sites. They now automatically subscribe to the "xpinstall-install-blocked" notification and display a notification bar for installation if required.

The blocked notification can also be displayed if the administrator has blocked add-on installation within Thunderbird. This is situation is also supported in the notification bar.

Note: The click handler must allow clicks through to the xpi for the installation to work correctly - otherwise the xpi will attempt to be loaded in the default browser.

Lightweight Themes

New in Thunderbird 3.1 Thunderbird has support for Lightweight Themes. Lightweight Themes referenced in content tabs can be installed into Thunderbird. See the Personas extension for an example.

See Also

Bugs relating to Thunderbird's implementation of Content Tabs should be filed in Bugzilla. First, check for existing known bugs. If your bug is new, specify the "Thunderbird" product and the "Toolbars and Tabs" component when you create the bug.

Document Tags and Contributors

Tags:
Contributors to this page: Level, jenzed, Standard8, chrisdavidmills
Last updated by: chrisdavidmills,