Creating a custom theme for Net Usage

This article will provide a walkthrough on how to modify the netusage.svg file to create a custom theme for Net Usage.

In order to modify an SVG file we will first need a program to open the file, the program I use and recommend for this is Inkscape, a free and open source vector graphics editor.

This walkthrough is based upon the theme I created to extend the length of the usage bar as posted on this Whirlpool forum thread: http://forums.whirlpool.net.au/forum-replies.cfm?t=803008&p=37#r737.

1. In the Firefox location bar enter "about:netusage?theme" and press Enter.
   
2. When the Net Usage Theme Building Wizard page is displayed click the New/Open button and select or create a project directory.
3. A new file has now been created in this directory called netusage.svg; we open this file in Inkscape.
4. We can now see each element which makes up the Net Usage bar, to extend the length of the bar we first need to increase the size of the document. Click File > Document Properties on the menu bar of Inkscape, in the dialog box which appears we can increase the width of the document, I chose to increase this to 180 px however you can choose any width you wish, we can close this dialog box.
5. Now that we have increased the documents width we can resize the usage bar. Click on the dark grey border of the outer rectangle and then using the right hand side drag handle increase the width of the bar, now repeat this step for the inner rectangle.
6. Now we need to adjust the clipping of the usage bars themselves, to do this we need to open Inkscape's XML Editor (Shift+Ctrl+X) and take note of the inner rectangles new width (see screenshot), these figures may differ if the rectangles have been resized freehand. This width is what we must adjust our clipping by minus approx 1 px (the stroke width of the inner rectangle).
7. Enter this new clipping width minus approx 1 px and click set (see screenshot).
8. Now we can resize the usage bars themselves, don't forget to resize the green and blue bars to the left initially to expose the orange and yellow bars which represent usage over 100% of peak and off-peak quota respectively.
9. Move the percentage label over and save the file. The next step is to package the file using the wizard.
   
10. Click Load under the Test section of the wizard, if you are happy with your theme move to the next section of the wizard and fill in your theme package information, finally click Make Dist under section 5 of the wizard.
    
11. The final step is to zip the contents of the distribution folder using whatever zip program you wish, I use and recommend 7-Zip another free and open source program. Once zipped the file should be renamed to end with the file extension of .xpi.
    

Congratulations you have just created your own custom theme for Net Usage. Although this walkthrough only covered extending the length of the usage bar, any number of custom themes can be created by making additional modifications to the netusage.svg file, so get creative and see what you can come up with.

Turning on the Debug File

Net Usage creates a debug file (netusage_debug.txt) whenever an error occurs. When you are trying to create your own ISP script you will want the debug file on all the time. This allows you to check variables, parsing commands and other useful information, even when the script works correctly.

To turn on the debug file follow these steps:

1. In the address field in Firefox enter about:config and hit Enter.
2. In the filter box type netusage and hit Enter.
   
3. You should see a few lines starting with extensions.netusage.0...
   The 0 in the preference name corresponds to the number of Net Usage meters you have in your browser. For example, if you only have 1 meter you will see preferences starting with extensions.netusage.0. If you have 2 meters you will see preferences with extensions.netusage.0 and extensions.netusage.1 and so on. I will assume you only have one meter in your browser.
4. Add a new preference to the list by right clicking somewhere in the window and selecting New -> Boolean from the pop up menu. In the dialog enter extensions.netusage.0.debug as the Preference Name. and click OK. Then select True for the preference Value and click OK.
5. Click on the Show All button on the filter line, then enter netusage in the filter field and hit enter. You should now have a new preference of extensions.netusage.0.debug set to True.

Now every time Netusage retrieves the statistics from the ISP's usage page it will write a debug file called netusage_debug.txt in %AppData%\Mozilla\firefox\Profiles\{Your Profile Directory}. When you have finished with the debug files you can turn them off by going back to the about:config page in Firefox and changing the value we just created to False.

If you need more information on the debug file, have a read of this blog post.

Getting the ISP javascript file

If you're going to dig around in the files below be sure to have a backup of your Net Usage directory so you can copy everything back if needed. I'm going to assume an intermediate level of knowledge of computers and Windows for this blog. If I've glossed over too many parts please leave a comment and I will update the blog entry as required.

Information on each Australian ISP is recorded in the isps.js file. If you have installed an additional country pack it will be in a file called isps_xx.js where xx is a two letter country abbreviation. Don't go searching your computer for these files yet, you wont be able to find them because they have been stored in a JAR file.

There is heaps of information on the Internet about Firefox JAR and XPI files. To cut a long story short, the JAR and XPI files are just a normal ZIP file. Therefore if you want to get your ISP javascript files you need to rename your JAR files to a ZIP file and then extract the ISP javascript file you want to edit.

This is how it's done (on XP):

1. Go to the Firefox Profile in your Application Data directory by entering %AppData%\Mozilla\firefox\Profiles\ in the Run command on the Start Menu. Navigate to the Extentions directory in your profile. Mine is at

   C:\Documents and Settings\Gerard\Application Data\Mozilla\firefox\Profiles\8ndbqffi.default\extensions

2. Hit CTRL + F and find netusageitem.jar (if your are using an Additional ISP pack you will need to find netusageisps.jar)
3. In the Find Results window right click on the result and select Open Containing Folder. You should end up in your extensions chrome directory.
   
4. Copy the netusageitem.jar and call it netusageitem.jar.bak so you have a backup in case things go bad.
5. Now copy the netusageitem.jar file again but rename it netusageitem.zip
6. You should now have three files in your chrome directory netusageitem.jar.bak, netusageitem.zip and netusageitem.jar (if you are editing an Additional ISP pack you should have netusageisps.jar.bak, netusageisps.zip and netusageisps.jar)
   
   
7. I use Winzip so you may need to change the process slightly for your compression software. You want to extract the isps.js or the isps_xx.js file from the zip file you have just created. When you extract the file you will need to extract it with folder names. Using Winzip, double click on the netusageitem.zip file. You will be presented with a list of files in the zipfile. Click on isps.js and click the Extract button.
   
   
8. Now ensure the Extract to: path is the chrome path for your extension. Ensure the Selected files/folders is marked and Use folder names is ticked. Click Extract. Close Winzip.
   
   
   
   
9. The chrome folder you are in should now contain a content folder. In the content folder is the isps.js or isps_xx.js file you will need to edit.
   
   
   

I use notepad++ to edit my javascript files. It is small, free, has syntax highlighting and can open more than one file at a time. Open the javascript file and have a look. We still have some more setting up to do before we can start the editing process.

Getting the source files

To add your own ISP to Net Usage you don't need to download all the source files. There is an easier way to get the file you want, but I'll describe that in a future blog.

If you want to get all the source files for Net Usage you will need to download a SVN client. SVN is an abbreviation for (Sub)Version Control. If you want to learn more about SVN have a read of this page. Critter has been good enough to provide the source for Net Usage via SVN.

Download and install a free SVN client, I use TortiseSVN, which I find works well for me. Once your SVN software has been installed create a directory somewhere on your computer where you want to store the source files you are about to download.

I did it in the following manner, I opened "My Computer" and navigated to the D: drive. Then in the right pane I right clicked and selected New > Folder from the menu. I called the new folder netusage_source. (d:\netusage_source) Once you have created the directory, right click on it in Explorer and select SVN Checkout from the menu. A dialog will be displayed, in the URL of repository field enter http://netusage.iau5.com/svn/ then click OK.

TortiseSVN should do its thing and start downloading the files to the directory you have created. Once it's finished click OK and the download window will close. You can now open the netusage_source folder and you will have all the source files.

My next blog will describe how to get the isps.js file from the installed package on your computer.

How to get an ISP added

Although Net Usage supports many ISPs, it doesn't support all of them. When I installed Net Usage my ISP was not supported. Damn...

I searched the forums on Whirlpool but could not find how to get the information Critter needed to add my ISP. The forums, stated to use the instructions on the homepage to add an ISP. Unfortunately, I couldn't find any instructions. I ended up downloading the source files from the SVN and searched through the code until I figured out what to do.

First, you need to install Net Usage. Once you have it installed, and displayed on your tool-bar, type about:netusage?add into the address bar of Firefox (the place where you normally enter the website you want to visit). Don't precede it with http:// or anything else, just enter about:netusage?add.

Follow the instructions on the page but do not send the file to Critter. Over the next few blogs I will explain in detail how to edit the source file and create your own script for your ISP.

Parsing Errors

More often than not, Net Usage will sit there doing it's thing and you will not experience any problems with it. However, at some time the ISP will change their page and your meter may stop working.

You will know the meter is not working because it will display a white cross in a red circle.

When you hover your mouse over the meter it may indicate a "parsing error" has occurred. If the error is a parsing error a debug file should have been created in the Mozilla Profile directory. The full path to the profile directory on my computer is:

C:\Documents and Settings\Username\Application Data\Mozilla\Firefox\Profiles\8ndbqffi.default\

The easiest way to find the profiles directory on your computer is to click on the Windows Start button and click on Run... (alternatively press the Widows-Logo [] key and the R key at the same time). In the Run dialog enter the following command:

%AppData%\Mozilla\firefox\Profiles\

Then hit Enter. A window should be displayed with a folder named something like 8ndbqffi.default. Your folder name will be different, but it should be the right place. Double-click on the folder to open it and find the netusage_debug.txt file.

If the debug file is not there, go back to firefox and left click on the meter to get Netusage to fetch your data again. You will get another parsing error, then go back to the profiles directory and the netusage_debug.txt file should be there.

This is a normal text file but if you open it in notepad the line-breaks will not be displayed correctly. If you want to see what's in the file, right click on the file and select "Open With" from the menu and then click on WordPad. I prefer a program called notepad++ but WordPad will do for just looking at the contents. Don't edit anything in this file, Critter need this file the way it is to work out why Net Usage is not working correctly.

Once you have finished looking at the contents of the debug file close WordPad and don't save any changes. To fix the problem you will need to email this file to Critter (his email address is at the bottom of the Net Usage homepage).

Net Usage Installation

One of the questions I've seem many times on the Whirlpool forums is "I've installed Net Usage but I can't see the meter". In this blog I will show you how to install Net Usage.

1. Download and install the add-on from the Net Usage website. Click on the Download Latest Version link and then click the Install Now button.
   
   
   
   
   
   
   
   
2. Once the add-on has installed and Firefox has restarted Net Usage will not be visible. You need to add the meter to one of your toolbars in order to use it. To add the meter to a toolbar, right click on one of the buttons in the main toolbar (I've right clicked on the refresh button it the capture to the right) and click on Customize... from the menu.
   
   
   
3. In the customize dialog, find the Net Usage Item (you may need to scroll down a bit to see it) and drag it on to a convenient location on your toolbar. There will be more than one Net Usage item. If you have more than one ISP account you can display a meter for each ISP. Once you have dragged the meter where you want it, click on the Close button.
   
   
   
   
4. Now that you have the meter on your toolbar you need to setup the account information in the Preferences menu item. Right click on the meter and select Preferences to open the preferences dialog.
   
   
   
   
   
   
   
5. In the Preferences dialog select your ISP, refresh frequency, username, password and any other information you may need. The ISP settings section is customised for each ISP in the list so your window will not look the same is the one to the right. But you get the idea.
   
   Once the information has been entered click OK. You may need to right click on the meter and select Update Usage (alternatively just left click the meter) to get the initial reading from the ISP.
   
   
   
6. Once you've updated the usage you should see a bar similar to mine. I have a Peak and Off-Peak allowance so I have a green bar and a blue bar on my meter. If you only have one allowance you will only see a green bar with the percentage used. When you hover your mouse over the meter a dialog should pop-up displaying the information retrieved from your ISP. If you still have a red cross in your meter, hover the mouse over it and an error message will be displayed indicating the nature of the problem.
   
   

Finally go to the developers page and read it. There are some trouble-shooting and usage tips near the bottom of the page. Read the two topics "What is the black triangular arrow on the usage bar?" and "What is the target surplus/deficit?", it will explain how to read the meter correctly.