* Changed error message “This is not an eHow Earnings page!” to “The eHow Earnings Tracker must be run from your Article Library (the ‘Articles’ tab under ‘My Profile’)”
* Added “Update Earnings using Yesterday’s Date” menu option.  This is useful if you didn’t get a chance to run the Tracker yesterday but you know that the earnings haven’t yet updated today.
* Added “Average of X per day” for both earnings and views.  Note that this average is over the selected date range.

* “Change from previous day” values now take deleted articles into account so there are no longer negative changes.

Finding the source of a network connection problem often requires one of more of the following:

• Run ipconfig from the command line
• Run tracert from the command line
• Checking various properties in Control Panel
• Restarting the network card
• Rebooting the computer
• Contacting the ISP

Not only does a user need to know about how run several different tools, they also have to know how to interpret the results.  My goal is to write a single application that will be able to walk the user through (and perform when possible) all of the troubleshooting steps needed to diagnose a broken network connection.

The requirements for the application are as follows:

• Provide a streamlined interface and detailed information for advanced users
• Walk novice users through the troubleshooting steps – explain the results and suggest steps to take to resolve the problem
• Educate users that are interested in learning more by explaining various network terms and describing what test results mean and explain why resolutions are suggested

I would really like this application to be something that is useful for everyone.  Too many tools are targeted solely at users who already know what they’re doing.

The idea here is that advanced users (like me)  will be able to do network troubleshooting by running one tool instead of several.  Novice users will be able to do their own troubleshooting and not have to bother computer savvy friends or relatives every time their network connection goes south .

If you have any comments, questions, or would like to participate in beta testing when it’s ready then head over to the forums.

Because the add-on hasn’t yet gone through the approval process to make it public, you need to check the box next to “Let me install this experimental add-on”.  That will enable the “Add to Firefox” button:

Click on “Add to Firefox” and you will be taken to the “please donate” page:

Once again, click on the checkbox and then “Add to Firefox”.  That will take you to the end user license agreement:

Click on “Accept and Install” and you will get the Software Installation dialog:

Click on “Install Now” and the tracker will be installed.  After installation, you will be prompted to restart Firefox:

Click on “Restart Firefox”.  After Firefox restarts, you should see a dialog box telling you that the tracker was installed:

The eHow Earnings Tracker has now been installed, so close the dialog box show above and log onto your eHow account.  Go to “My Profile” and then click on the “Articles” tab:

Now you can run the tracker by going to Tools – eHow Earnings Tracker – Update Earnings or by right-clicking somewhere on the page:

You should see the screen flash a few times as the tracker navigates through your article library.  When the tracker is finished, it will open a new window with your earnings data in it:

Changes since 0.4.0:

*==> Version 1.0.1 (August 5, 2009)

* Fixed bug with Tracker not working if the Windows user name had an apostrophe in it

*==> Version 1.0.0 (August 3, 2009)

* Added ability to toggle table display between earnings and views

*==> Version 0.6.0 (August 2, 2009)

* Added column sorting
* View table still gone, will be coming back soon!

*==> Version 0.5.0 (July 30, 2009)

* Added ability to select a date range
* Views table is gone, will return next version

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.

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.

Changes since 0.3.0:

*==> Version 0.4.0 (July 13, 2009)

* Added “Totals” and “Change from previous day” rows for earnings and views

*==> Version 0.3.1 (July 13, 2009)

* Fixed problem with URL parsing when users had dashes(-) in their name.

Changes since Version 0.2.0:

*==> Version 0.3.0 (July 13, 2009)

* Added “Copy Earnings Data to Desktop” menu option
* Added Views to HTML report

*==> Version 0.2.3 (July 12, 2009)

* Additional logging
* Fixed issue with invalid XML characters getting stored as part of titles
* Added “Delete Earnings Data” menu option

*==> Version 0.2.2 (July 12, 2009)

* Fixed bug related to addition/removal of articles from the article library

*==> Version 0.2.1 (July 12, 2009)

* Added more error logging
* A backup earnings.xml file is now created on a successful update

Changes since 0.1.1:

*==> Version 0.2.0 (July 12, 2009)

* eHow earnings report now opens in its own tab
* Added styling to $0.00 value fields so that they are italics with gray font
* Added eHow graphics & color scheme
* Added “View Last Update” which views the last HTML stats page rather than regenerating it from eHow article earnings pages
* Added error logging and menu item to copy log file to desktop

*==> Version 0.1.2 (July 9, 2009)

* Added CSS styling to HTML report

Once development work settles down I’ll write some more posts about the tracker and how to write Firefox Addons.