17 of 26

The eHow Earnings Tracker stores its data in XML format, so one of the things that I needed to learn how to do was program with XML in Firefox Add-ons.  Mozilla has a whole section of code snippets dedicated to XML but I will walk through exactly what I did in the development of the tracker and point out some gotchas that I figured out along the way.

The first step in this process was to figure out how to create an XML DOM tree in memory.  This turned out to be pretty straightforward to do thanks to Mozilla’s How to create a DOM tree documentation.  I wound up with the following code to create my basic XML DOM hierarchy:

var createEarningsDOM = function()
{
    m_trackerDOM = document.implementation.createDocument(null, null, null);

    var trackerNode = m_trackerDOM.createElement(m_xmlNodeTracker);
    trackerNode.setAttribute(m_xmlAttrVersion, m_xmlVersion);

    m_articleListElem = m_trackerDOM.createElement(m_xmlNodeArticleList);
    trackerNode.appendChild(m_articleListElem);

    m_statsElem = m_trackerDOM.createElement(m_xmlNodeStats);
    trackerNode.appendChild(m_statsElem);

    m_trackerDOM.appendChild(trackerNode);
};

You should notice a couple of things about the source code above.  First, I create variables to hold my node and attribute names.  This ensures consistency when I refer to particular nodes and attributes throughout my code.  It also means that if I decide to change the string for a node or attribute name, I only need to do it in one spot.  The second thing is that I create variables to hold references to DOM nodes so that I can easily manipulate them later in the code.

Now that I was able to create an XML DOM tree in memory, it was time to figure out how to write it out to a file.  Mozilla has some decent documentation on parsing and serializing XML.  I combined the information there with what I learned about file I/O and wrote the following code to serialize my XML DOM to a file:

var s = new XMLSerializer();
XML.prettyIndent = 4;
var xmlString = XML(s.serializeToString(m_trackerDOM)).toXMLString();

if(!FileIO.write(m_earningsFile, xmlString))
{
    throw Error("Failed to save file " + m_earningsFile.path);
}

The “pretty” serialization for XML strings is really cool because it formats the XML so that it’s very readable.  It makes life a lot easier when you need to look at the contents the XML file.

Now that I was able to write out XML to a file, I needed a way to read it back in again later.  I used the DOMParser.  The one thing to watch out for with the DOMParser is that when the parsing fails, it doesn’t throw an exception.  Instead, it returns an XML document that contains the parsing error.

This is the code I came up with for loading the XML DOM from a file:

var fileContents = FileIO.read(currentFile);

if(fileContents)
{
    logMessage("\tParsing file");
    var parser = new DOMParser();
    m_trackerDOM = parser.parseFromString(fileContents, "text/xml");

    logMessage("\tLooking for " + m_xmlNodeArticleList);
    m_articleListElem = m_trackerDOM.getElementsByTagName(m_xmlNodeArticleList)[0];

    if(!m_articleListElem)
    {
        // XML parsing failed, grab error
        var s = new XMLSerializer();
        XML.prettyIndent = 4;
        logMessage(XML(s.serializeToString(m_trackerDOM)).toXMLString());                    
        throw Error("Failed to parse XML data file");
    }
}

In this piece of code, I read in the file contents and parse it, attempting to find the DOM element that I’m looking for.  If I don’t find the element then something has gone wrong – either the parsing failed, or the XML is not what I’m expecting it to be.  In either case, I log the results of the parseFromString() function to my log file so that I know what went wrong.

One of the major pieces of the eHow Earnings Tracker involves writing data to an XML file and reading it back later.  Figuring out how to do file I/O in a Firefox add-on was not straightforward due to Mozilla’s wide array of Chrome APIs and spotty documentation.

Unfortunately, file I/O is not one of Mozilla’s new FUEL APIs.  FUEL is a Javascript Library available to Firefox add-ons that is far easier to use than the older XPCOM API.  It was introduced in Firefox 3.0 and Mozilla has been slowly adding functionality to it.

Starting with Mozilla’s file I/O code snippets was a quite confusing – the documentation meanders all over the place showing bits and pieces of code without explaining anything in much depth.  On top of that, they suggest that you use the io.js wrappers at the beginning of the page but then none of the examples shown use it.

Basically what it comes down to is that file I/O is done by using the XPCOM interfaces nsIFile and nsILocalFile.  The io.js wrappers are utility functions used to encapsulate the tedious syntax needed to use them.  I don’t fully understand the purpose of everything in io.js but I will show you what I did figure out and ultimately use in the tracker implementation.

The first thing that I needed to do was get a hold of the current Firefox profile directory since that’s where I wanted to store my data.  I chose the current profile directory because I wanted to be able to support multiple Firefox profiles using the tracker without overwriting each other’s data.

I wound up with the following function to do it:

var getProfileDir = function()
{
    var dir = DirIO.get('ProfD');
    if(!dir || !dir.exists())
    {
        throw Error("Failed to open profile directory");
    }

    return dir;
};

What this code does is create an nsIFile object that represents the profile directory.  ‘ProfD’ is a special string that refers to the profile directory.  You can see a list of the supported strings in the file I/O code snippets.  If you want to open a specific directory path, use DirIO.open() instead of get().

Once you have an nsIFile object, you can do a bunch of things with it.  The following code snippet will try to open a file in the profile directory and create it if it doesn’t already exist:

var openEarningsBackupFile = function(username)
{
    var currentFile = getProfileDir();
    currentFile.append(username + ".xml");

    if(!currentFile.exists())
    {
        if(!FileIO.create(currentFile))
        {
            throw Error("Failed to create earnings backup file");
        }
    }
    return currentFile;
}

The append function of the nsIFile object lets you navigate a file hierarchy one level at a time.  You could go down multiple levels like so:

currentFile.append("path1");
currentFile.append("path2");
currentFile.append("file.xml");

This would navigate to [currentFile.path]\path1\path2\file.xml.  The create() function will create any path segments that don’t already exist.

Keep in mind that the append function modifies the calling object so if you want to open up two different files in a particular directory then the easiest way to do it is to create an nsIFile object that points to the directory and then clone it:

var file1 = getProfileDir();
var file2 = file1.clone();
file1.append("file1.xml");
file2.append("file2.xml");

Once you have an nsIFile object pointed to an existing file you can read from and write to it.  The following copy function shows how to do reads and writes with nsIFile objects using the io.js wrappers:

// srcFile and destFile should be nsIFile objects
var copyFile = function(srcFile, destFile)
{
    var srcText = FileIO.read(srcFile);

    if(!srcText)
    {
        throw Error("Failed to read " + srcFile.path);
    }

    if(!FileIO.write(destFile, srcText))
    {
       throw Error("Failed to copy " + srcFile.path + " to " + destFile.path);
    }
 };

Another not-so-obvious thing to figure out was how to get the path where the add-on is installed.  After quite a bit of searching, I came up with this bit of code:

var getExtensionDir = function()
{
    var dir = Components.classes["@mozilla.org/extensions/manager;1"].getService(Components.interfaces.nsIExtensionManager).getInstallLocation(m_extensionId).getItemLocation(m_extensionId);

    if(!dir)
    {
        throw Error("Failed to get extension installation directory");
    }

    return dir;
};

File I/O in Firefox add-ons is pretty easy to do once you see how all of the pieces fit together.

Since I now have a Firefox plugin that will properly update the browser’s status bar with the URL of the web page being viewed, it’s time to write code that will specifically detect an eHow earnings page.  For those of you following along at home, take the code from the previous post and add the following function just after the updateStatusBar function :

var update = function()
{
    var host = Application.activeWindow.activeTab.uri.host;
    var path = Application.activeWindow.activeTab.uri.path;

    m_eHowMsg = ""

    if(host.search(/www.ehow.com/i) == 0)     
    {         
        // eHow earnings URLs are in the form "http://www.ehow.com/members/user-p#-articles.html" or  "http://www.ehow.com/members/user-articles.html"         
        var userAndPageNumPattern = new RegExp("\/members\/\(.+)-(.+)-articles.html");         
        var userAndPageNumResult = userAndPageNumPattern.exec(path);          
        var userPattern = new RegExp("\/members\/\(.+)-articles.html");         
        var userResult = userPattern.exec(path);          

        if(userAndPageNumResult && (userAndPageNumResult.length < 1))         
        {             
            m_eHowMsg = userAndPageNumResult[1];         
        }
        else if(userResult && (userResult.length &lt; 1))         
        {             
            m_eHowMsg = userResult[1];         
        }     
    }      
    updateStatusBar(m_eHowMsg);
}

This function looks for URLs that match eHow earnings pages and then updates the status bar with the eHow user name that it finds.  To hook this function up, just replace the calls to updateStatusBar in onTabSelect() and onTabLoad() with calls to update().

Now when we navigate to a URL that contains eHow article earnings data we see the username in the status bar (the status bar will be blank for other URLs):

The code from my previous post worked great with a single tab open in Firefox.  However, using multiple tabs exposed a problem – all tabs in a single Firefox window share the same status bar.  Another issue is that the event “DOMContentLoaded” gets fired any time a page finishes loading, regardless of what tab you’re on.  This means that the information in the status bar may or may not actually match the tab that you’re on.

I also found some better techniques for placing my code in a namespace/module that are described here and here.  It’s also worth noting that Mozilla’s Developer Center has documentation for their Javascript APIs and objects.  Unfortunately, the documentation usually isn’t very good and I wind up spending an awful lot of time looking for simple pieces of information.

After a bit of work, I came up with the code below to do what I wanted.  This code only works for Firefox 3.5 because that’s when event data was added for the TabOpen, TabClose, and TabSelect events.  In the code below, event.data is a BrowserTab object.

// Create a global variable for the addon
var g17of26 = {};

g17of26.eHowEarningsTracker = function ()
{
    // Private functions
    var updateStatusBar = function(msg)
    {
        var statusBar = window.document.getElementById("ehow_earnings_tracker_statusbar");

        if(statusBar)
        {
            statusBar.setAttribute("label", msg);
        }
    }

    return {  // This brace must stay on the same line as the return - it's a Javascript quirk

        // This function is called when the browser is first launched
        onBrowserLoad : function()
        {
            Application.activeWindow.events.addListener("TabOpen", g17of26.eHowEarningsTracker.onTabOpen);    
            Application.activeWindow.events.addListener("TabClose", g17of26.eHowEarningsTracker.onTabClose);
            Application.activeWindow.events.addListener("TabSelect", g17of26.eHowEarningsTracker.onTabSelect);

            Application.activeWindow.activeTab.events.addListener("load", g17of26.eHowEarningsTracker.onTabLoad);
        },

        // This function is called when the browser quits
        onBrowserUnload : function()
        {
            window.removeEventListener("load", g17of26.eHowEarningsTracker.browserLoad, false);
            window.removeEventListener("unload", g17of26.eHowEarningsTracker.browserUnload, false);        

            Application.activeWindow.events.removeListener("TabOpen", g17of26.eHowEarningsTracker.onTabOpen);
            Application.activeWindow.events.removeListener("TabClose", g17of26.eHowEarningsTracker.onTabClose);
            Application.activeWindow.events.removeListener("TabSelect", g17of26.eHowEarningsTracker.onTabSelect);
        },

        // This function is called when a tab is opened
        onTabOpen : function(event)
        {
            event.data.events.addListener("load", g17of26.eHowEarningsTracker.onTabLoad);
        },

        // This function is called when a tab is closed
        onTabClose : function(event)
        {
            event.data.events.removeListener("load", g17of26.eHowEarningsTracker.onTabLoad);
        },

        // This function is called when a tab is selected
        onTabSelect : function(event)
        {
            updateStatusBar(Application.activeWindow.activeTab.uri.spec);
        },

        // This function is called when a page finishes loading in a tab
        onTabLoad : function(event)
        {
            if(event.data.uri.spec == Application.activeWindow.activeTab.uri.spec)
            {
                updateStatusBar(event.data.uri.spec);
            }
        }
    };
}(); // the parens here cause the anonymous function to execute and return

// Hook up events
window.addEventListener("load", g17of26.eHowEarningsTracker.onBrowserLoad, false);
window.addEventListener("unload", g17of26.eHowEarningsTracker.onBrowserUnload, false);

As it turns out, hooking up Javascript to XUL so that an addon can actually do something is remarkably similar to linking HTML and Javascript together when doing web development.  The first step is to create a Javascript file and include it it in the XUL file much like you would include a Javascript file in an HTML file:

<overlay id="ehow_earnings_tracker_overlay" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
    <script type="application/x-javascript" src="chrome://ehow_earnings_tracker/content/browser_overlay.js" />
    <statusbar id="status-bar">
        <statusbarpanel id="ehow_earnings_tracker_statusbar" label="" />
    </statusbar>
</overlay>

Now we can add code in browser_overlay.js to actually do something.  In this case, we will update the status bar text with the URL of HTML page that was loaded:

// Creates a global variable called "ehow_earnings_tracker"
var ehow_earnings_tracker =
{
    init:
        function()
        {
            // Grab the contents of the browser
            var appcontent = document.getElementById("appcontent");
            if(appcontent)
            {
                // Get notified when the page is done loading
                appcontent.addEventListener("DOMContentLoaded", ehow_earnings_tracker.onPageLoad, true);
            }
        },

    onPageLoad:
        function(aEvent)
        {
            var doc = aEvent.originalTarget; // doc is document that triggered "onload" event
            var statusBar = document.getElementById("ehow_earnings_tracker_statusbar");

            if(!statusBar)
            {
                return;
            }

            statusBar.setAttribute("label", doc.location.href);
        }
};

// Hook into the window load event
window.addEventListener("load", ehow_earnings_tracker.init, false)

Now, when I run Firefox with my plugin enabled it dynamically updates the status bar with the URL of the loaded page:

Firefox addons are implemented using a combination of XUL, Mozilla’s proprietary XML based language, and Javascript.  For anyone who’s done development with HTML and Javascript, learning to write a Firefox addon is pretty straightforward.  All you need is a decent tutorial to get started.  Fortunately, finding tutorials on how to create addons for Firefox is pretty easy.  Some of the ones I found were pretty old, but as far as I could tell the information was still accurate. If you need to learn Javascript, there are plenty of tutorials over on W3Schools.  If you prefer books, I highly recommend David Flanagan’s Javascript: The Definitive Guide.

I decided to start with a tutorial from Mozilla which shows you how to create a classic “Hello World” program by displaying “Hello, World” in the browser’s status bar.   I went through the tutorial quickly and easily by following the exact steps that were outlined in the tutorial.  “Hello, World” showed up my the status bar without  a hitch.  The flaw with this tutorial is that it doesn’t show you how to make the addon actually do something, which is the topic of my next post.

Another useful article I found was this article on Lifehacker that gives some good tips for getting set up to develop Firefox addons.

Last fall I was looking for a way to make some additional income and my wife, whose career currently consists of writing online, pointed me toward eHow.  I’ve never been much of a writer but I thought I’d do ok with writing How-To articles about programming and other computer related topics.  I browsed around the site and found that most of the computer related content was just awful.  Almost all of it was poorly written, out of date, or just completely inaccurate.  I thought to myself “I can do better than this!”.

So in October I created an account and wrote a couple of articles about programming with WPF.  I got distracted with other things for a while the two articles earned next to nothing over the next six months.  In late April I decided to give it another shot and I’ve written 25 more articles since then.  I still haven’t earned much of anything, but from reading the eHow forums I’ve concluded that you really need to reach a critical mass of article count and a certain threshold of article age before you really start seeing any sort of real money.  Even just going from 2 articles to 27 over the course of two months I’ve noticed a significant acceleration in the rate that my earnings are increasing.  Of course, creating this blog has completely stalled my eHow article writing .

eHow writers earn money through some secret earnings algorithm that seems to be primarily based on people clicking ads on your articles.  The official eHow line is that the earnings are based on a variety of factors but the primary driver really seems to be  ad clicks.  Fortunately for me, computer related ads seem to do very well in terms of CPC (cost per click – the rate that advertisers pay for ad clicks).

The previous two paragraphs are background info for the topic of this post – tracking eHow earnings is a royal pain in the butt.  eHow gives you very limited data for your earnings.  For each article in your library, you are shown lifetime views and lifetime earnings.  The only other numbers you get are lifetime views for all articles and total earnings for the month.  This means that you have no way to track article views or earnings over time unless you manually record them every day.  To make matters worse, you can only see data for 10 articles at a time.  For a few days I tried tracking the earnings manually using a Firefox addon called TableTools to copy the earnings data and paste it into Excel.  That just sucked and I was determined to create a better way.

My first thought was to create a Windows application that could make HTTP requests to snag the earnings data since it would involve using technology that I was already familiar with.  I opened up Firebug and watched the HTTP traffic as I logged into eHow and viewed my earnings pages.  I immediately realized that trying to decipher all of the traffic to figure out what requests I’d need to make was going to be a total nightmare.

It then dawned on me that this might be a good thing to implement using a Firefox addon.  From my experience using other Firefox addons, I knew that they were capable of doing everything that I would need it to do.  Perfect!  I would get an opportunity to learn how to write Firefox addons, I would be creating something that I would want to use on a regular basis and something that other people would most certainly want to use.  I was sold – off to learn how to write a Firefox addon!