July | 2009 | visophyte: shiny? shiny.

As part of our goal to make it easy to write extensions for Thunderbird 3, we’ve been working on getting Jetpack running under Thunderbird and exposing Thunderbird-specific points. This is all experimental, but it’s having good results.

The first example replaces the message you get from twitter when someone follows you and instead shows you that person’s twitter page so you can see what they’ve written. Unfortunately, if you try and click on links on the page you will become sad because they all try and trigger your web browser. But Standard8 is hard at work resolving the content display issues. Besides demonstrating registration via a regex over the sender’s e-mail address, it also shows us extracting message headers from the message. Also, we introduce a small HTML snippet that precedes the nested web browser so it’s not just an embedded web browser.

jetpack.future.import("thunderbird.messageDisplay");
jetpack.thunderbird.messageDisplay.overrideMessageDisplay({
  match: {
    fromAddress: /twitter-follow-[^@]+@postmaster.twitter.com/
  },
  onDisplay: function(aGlodaMsg, aMimeMsg) {
    let desc = aMimeMsg.get("X-Twittersendername", "some anonymous jerk") +
      " has followed you on Twitter.  Check out their twitter page below.";
    return {
      beforeHtml:
        <>
          <div style="background-color: black; color: white; padding: 3px; margin: 3px; -moz-border-radius: 3px;">
            {desc}
          </div>
        </>
      url: "http://twitter.com/" + aMimeMsg.get("X-Twittersenderscreenname")
    };
  }
});

Our second example of the extension point replaces e-mails from Amazon about an order (order confirmation and shipment confirmation) with the amount of money you spent on the order in BIG LETTERS (or rather BIG NUMBERS). It uses a regular expression run against the message body to find the total order cost. Then it generates a simple web page to present the information to you.

jetpack.future.import("thunderbird.messageDisplay");
jetpack.thunderbird.messageDisplay.overrideMessageDisplay({
  match: {
    fromAddress: /(?:auto-confirm|ship-confirm)@amazon.(?:com|ca)/
  },
  _totalRe: /Total(?: for this Order)?:[^$]+\$\s*(\d+\.\d{2})/,
  onDisplay: function(aGlodaMsg, aMimeMsg, aMsgHdr) {
    let bodyText = aMimeMsg.coerceBodyToPlaintext(aMsgHdr.folder);
    let match = this._totalRe.exec(bodyText);
    let total = match ? match[1] : "hard to say";
    return {
      html:
      <>
        <style><![CDATA[
          body { background-color: #ffffff; }
          .amount { font-size: 800%; }
        ]]></style>
        <body>
          you spent... <span class="amount">${total}</span>
        </body>
      </>
    };
  }
});

The modified version of Jetpack can be found here on the “thunderbird” branch. “about:jetpack” can be triggered from the “Tools” menu. Besides the development jetpack, you can also add jetpacks from the about:jetpack “Installed Features” tab by providing a URL directly to the javascript file. Unfortunately, I just tried installed more than one Feature at the same time and that fell down. I’m unclear if that’s a Thunderbird content issue, a problem with my changes, or a problem in Jetpack/Ubiquity that may go away when I update the branch.

About the name. David Ascher picked it. My choice was flamboydoc in recognition of my love of angry fruit salad color themes and because every remotely sane name has already been used by the 10 million other documentation tools out there. Regrettably not only have we lost the excellent name, but the color scheme is at best mildly irritated at this point.

So why yet another JavaScript documentation tool:

JavaScript 1.8 support. JSHydra (thanks jcranmer!) is built on spidermonkey. In terms of existing JS documentation tools out there, they can be briefly lumped into “doesn’t even both attempting to parse JavaScript” and “parses it to some degree, but gets really confused by JavaScript 1.8 syntax”. By having the parser be the parser of our JS engine, parsing success is guaranteed. And non-parsing tools tend to require too much hand labeling to be practical.
Docceleterator is not intended to be just a documentation tool. While JSHydra is still in its infancy, it promises the ability to extract information from function bodies. Its namesake, Dehydra, is a static analysis tool for C++ and has already given us great things (dxr, also in its infancy).

Support community API docs contributions without forking the API docs or requiring source patches. DevMo is a great place for documentation, but it is an iffy place for doxygen-style API docs. Short of an exceedingly elaborate tool that round-trips doxygen/JSDoc comments to the wiki and user modifications back again, the documentation is bound to diverge. By supporting comments directly on the semantic objects themselves[1], we eliminate having to try and determine what a given wiki change corresponds to. (This would be annoying even if you could force the wiki users to obey a strict formatting pattern.) This enables automatic patch generation, etc.
Mashable. You post the JavaScript source file to a server running the doccelerator parser. You get back a JSON set of documents. You post those into a CouchDB couch. The UI is a CouchApp; you can modify it. Don’t like the UI, just want a service? You can query the couch for things and get back JSON documents. Want custom (CouchDB) views but are not in control of a documentation couch? Replicate the couch to your own local couch and add some views.
Able to leverage data from dehydra/dxr. Mozilla JS code lives in a world of XPCOM objects and their XPIDL-defined interfaces. We want the JS documentation to be able to interact with that world. Obviously, this raises some issues of where the boundary lies between dxr and Doccelerator. I don’t think it matters at this point; we just need internal and API documentation for Thunderbird 3 now-ish.
A more ‘dynamic’ UI. The UI is inspired by TiddlyWiki‘s interface where all wiki “pages” open in the same document. I often find myself only caring about a few methods of a class at any given time. Documentation is generally either organized in monolithic pages or single pages per function. Either way, I tend to end up with a separate tab for each thing of interest. This usually ends in both confusion and way too many tabs.

1: Right now I only support commenting at the documentation display granularity which means you cannot comment on arguments individually, just the function/method/class/etc.

Example links which will eventually die because I’m not guaranteeing this couch instance will stay up forever:

The hg repo is here. I tried to code the JS against the 1.5 standard and generally be cross-browser compatible, but I know at least Konqueror seems to get upset when it comes time to post (modified) comments. I’m not sure what’s up with that.

Exciting potential taglines:

Doccelerator: Documentation from the future, because the documentation was doccelerated past the speed of light, and we all know how that turns out.
Doccelerator: It sounds like an extra pedal for your car and it’s just as easy to use… unless we’re talking about the clutch.
Doccelerator: Thankfully the name doesn’t demand confusingly named classes in the service of a stretched metaphor. That’s good, right?

visophyte: shiny? shiny.

Andrew Sutherland writes things but (almost) always includes pictures to look at.

Monthly Archives: July 2009

Thunderbird Jetpack messageDisplay.overrideMessageDisplay fun.

Doccelerator: JavaScript documentation via JSHydra into CouchDB with an AJAX UI