The Extension Builder is the most powerful and useful feature of Extension Developer. Shown in Figure 16.3 is the dialog box that appears when this feature is selected.

Figure 16.3. One useful part of Extension Builder is its capability to edit the install.rdf file automatically.

Other features of the Extension Builder include the capability to build the extension, install it, determine its folder location, and show its installed folder.

The install.rdf editor is able to read the extension’s install.rdf file. All extensions must have an install.rdf file (this file tells Firefox all about the extension).

In the previous section, “Preferences for Extension Developers,” you set some preferences when developing extensions. The Extension Developer’s menu item Toggle Debugging Prefs toggles three of the four recommended extension building preferences:

Being able to toggle these preferences is important because, when they are set, Firefox performance can be seriously compromised.

The one preference that is not toggled is javascript.options.strict. If your extension uses JavaScript and you are encountering problems, manually enable javascript.options.strict preference, as earlier described.

Sometimes the JavaScript Console’s one-line JavaScript evaluator is not sufficient for testing pieces of JavaScript code. The JavaScript Shell interface can be very useful in such cases.

In Figure 16.4, the JavaScript Shell was started. The first six lines in the window are welcome text, complete with some links (including Math, help, and enumerate Windows()).

Figure 16.4. The variable MyVar is assigned a string; then MyVar's contents are displayed in an Alert box.

The steps to display the Alert box shown in Figure 16.4 are shown here:

If you click the help link (end of the third line), a short but useful help page is displayed. After using this small window for a while, you might find that it is indispensable when developing simple JavaScript code.

The JavaScript Environment is similar in concept to the JavaScript Shell. The most important difference is that the JavaScript Environment allows you to develop more complex JavaScript code.

The JavaScript Environment window is shown in Figure 16.5. In this example, I’ve written a simple JavaScript program that prints the squares of numbers between zero and five. (When you start the JavaScript Environment, you will see the inspiration for this program.) To make this example a bit more than trivial, I’ve created a function to do the square function.

Figure 16.5. In the JavaScript Development Environment window, the top half is the window where you enter your code.

print("Squares of numbers 0 through 5:");
for (i = 0; i <= 5; ++i)
  print(SquareIt(i));

function SquareIt(a) {return(a * a);}

This small JavaScript program created the results shown in Figure 16.6.

Figure 16.6. The browser window shows the actual code; the JavaScript Injector window shows the file being executed; and the Alert window shows the results.

The JavaScript Injector enables the user to execute JavaScript that has been saved in a file. This allows easy testing of complete JavaScript files without having to cut and paste.

Shown in Figure 16.6 is Firefox with a small sample JavaScript program. This program is similar to the one in the previous example; however, the previous example’s print() statements have been replaced with alert() statements. This was done because the JavaScript Injector runs the JavaScript program in a true JavaScript environment, whereas the other two examples have a text output area available.

In the end, all three of these JavaScript tools are very useful.

Much like the JavaScript Shell, the HTML Editor has a window with two sections. In the upper section you enter your HTML code, and in the bottom, as you are working, you will see the rendered results of the HTML.

This small tool supports clipboard copy and paste, letting you easily move HTML code into and out of the HTML Editor. (This is important because there is no file Open, Save, or Close command.)

Figure 16.7 shows the HTML Editor with a small piece of HTML that was lifted from my cooking web page.

Figure 16.7. This HTML was created completely in the Real-time HTML Editor. If you are a guy and think you can’t cook, think again.

The Real-time HTML Editor gives you immediate feedback by showing what the HTML code will look like in a browser window.

When you find that JavaScript won’t do everything you want (and JavaScript is limited, intentionally), the next avenue to greater functionality is XUL. XUL allows for easy development of platform-independent user interfaces, although Java and JavaScript must still be relied on for much of the underlying functionality.

In Firefox, click Edit in the menu for an example of a menu using XUL. It is not a part of Windows. Firefox doesn’t use the Windows GUI interface except for client output. Everything you see in the Firefox window—the menu, the toolbar(s), the status bar, and so on—is a creation of Firefox. Most Windows applications use Windows to display titles, menus, toolbars, and the like. That is fine for those applications, but Firefox was designed to be platform independent.

Someday most applications will use XUL—a victory for developers who don’t want to be tied down to a specific operating system. The XUL Editor is shown in Figure 16.8. This code example is a bit more complex than our previous JavaScript examples, but it does more. Though not obvious, our XUL example uses JavaScript.

Figure 16.8. XUL frees you from the operating system, just like the operating system frees you from the hardware.

To be more readable, this simple bit of XUL code is shown in Listing 16.1. In this code, several items are highlighted in bold; these are areas that deserve closer inspection.

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
<window id="yourwindow" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<label value="This is our XUL example of a menu."/>

<toolbox flex="1">
  <menubar id="My-menubar">
    <menu id="filemenu" label="File">
      <menupopup id="filepopup">
        <menuitem label="New" oncommand="alert('You clicked on File, New in the menu')," />
        <menuitem label="Open"/>
        <menuitem label="Save"/>
        <menuseparator/>
        <menuitem label="Exit"/>
      </menupopup>
    </menu>
    <menu id="editmenu" label="Edit">
      <menupopup id="editpopup">
        <menuitem label="Cut"/>
        <menuitem label="Copy"/>
        <menuitem label="Paste"/>
        <menuseparator/>
        <menuitem label="Undo"/>
        <menuitem label="Redo"/>
      </menupopup>
    </menu>
  </menubar>
</toolbox>

</window>

In Listing 16.1, we have added code to the file menu’s New command. Added is an oncommand attribute. The data assigned to the oncommand attribute is what will happen when the user selects (clicks) this item. In this example, "alert('You clicked on File, New in the menu')," is JavaScript code. I enclosed the entire item in double quotation marks. Usually, a text literal passed to the JavaScript alert() function is enclosed in double quotation marks, but because this entire item is in double quotation marks, I instead used single quotation marks for the alert()’s parameter.

After you get used to using XUL, you will find it easy to create user interface functionality using a combination of XUL and JavaScript.

Chrome is the look and feel of an application’s user interface. Colors, button shapes, fonts, sizes, and so on are all specified as parts of chrome. Chrome is always affected by themes and, to a lesser extent, by extensions. This lesser extent is typically parts of chrome that are directly part of the extension’s functionality (such as added dialog boxes, menu items, and so forth).

When Firefox loads, it loads the chrome. From then until Firefox closes, Firefox does not change the chrome. When a new theme is selected, Firefox implements the theme when it restarts. The same is true in regard to extensions—extensions are loaded and configured at startup, not during the normal operation of Firefox.

The Extension Developer extension forces Firefox to reload the chrome without a restart. The concept is that this makes developing extensions (and themes) much faster. At least that is the idea.

My experience has been that developing extensions can be a risky process. Not only can you load the extension you are developing and have Firefox crash, but you also can damage the profile. In fact, it is too painfully easy to corrupt a profile when developing extensions.

If you are willing to take the risk that a reloading of the chrome might not resolve some problems your extension has caused but that you might not realize have occurred), you should try the Reload All Chrome option.

The Firefox Console is a separate window started when the Firefox command contains the switch –console.

The Firefox Console displays the streams stdout and stderr in a simple, display-only window (refer to Figure 16.2). Both stdout (which is short for standard output) and stderr (which is short for standard error) are terms that are inherited from the C and Unix days.

stdout is the nonerror output from a number of I/O statements. stderr is error output, either specifically written to stderr by the program or from runtime functionality’s error trapping routines.

The JavaScript Console serves a function very similar to that of the Firefox Console. The JavaScript Console receives error message information from JavaScript about errors and other problems that occur in JavaScript code.

Unlike the Firefox Console, though, the JavaScript Console has some management tools. There are controls to restrict how much information is displayed (All, Errors, and Warnings and Messages) and a Clear button. Plus, the JavaScript Console allows copying information about an error to the Windows clipboard so it can be pasted into other applications if necessary.

The JavaScript Console can be displayed in a Firefox sidebar (see http://www.digitalmediaminute.com/article/1348/updated-open-firefox-javascript-console-in-a-sidebar), as a separate window (select JavaScript Console in the Tools menu), or in a tab (by creating a new tab and entering the following URI in the Location bar):

chrome://global/content/console.xul

Figure 16.9 shows the JavaScript Console displayed as a separate window (go to the Tools menu and click JavaScript Console).

Figure 16.9. The JavaScript Console; no matter how it’s displayed, it always looks the same.

At the top of the screen are the buttons that limit the display to either a severity level or all messages and a Clear button to clear the console’s display. Below these buttons is a small text area in which you can type a JavaScript statement and have it evaluated by either clicking the Evaluate button or pressing the Enter key.

Another powerful advantage of the JavaScript Console is that it provides information about errors in a consistent format. Each error has a severity level symbol (Error, Warning, or Message), an error description, an error source (usually a file), along with optional error-specific information.

The filename for the error is a link to that file. Click the filename, and the file is opened in a browser window.

Comments in XUL and XML are begun with the characters <!-- and end with -->. The number of hyphens in a beginning or ending comment must be exactly two—no more, no less. Comments must not contain any double hyphens. A sample comment is shown here:

<!-- This is a valid comment -->

Processing instructions are lines that contain instructions for the application that is processing the XUL or XML. An example of a processing instruction is

<$xml version="1.0"$>

This instruction tells the application that the version of XML is 1.0.

Your new extension needs a name. I’ve picked the name MyExtension as the name for the extension. After you have a name for the extension picked out, the extension will need a home. The name for this top-level folder is not critical. Other subfolder names will be significant, but the topmost level folder can have any convenient name, usually the same name as your extension.

In My Documents, I created my MyExtension folder. In this folder we need two subfolders. The first is named content, and the second is called chrome. We now have these folders:

Contained in the root folder will be two or three project files: the install.rdf file, the extension’s .xpi file, and (for Firefox 1.5 and later) the chrome.manifest file.

The content folder is where you will put your working copies of the extension’s files.

In MyExtension the three files in the contents folder are

More complex extensions will have more files in the contents folder.

The chrome folder will hold the extension’s JAR file. Most extension developers use the chrome folder only to hold the JAR file, and nothing else. However, this name is significant to Firefox, so you should not put your JAR file anywhere else.

All extensions are distributed using XPI files. The definition of an XPI file is that it is a Mozilla extension distribution file, although that tells little of what it really is.

XPI files are, for all intents and purposes, simply renamed Zip files. You can create them in several ways. My method uses the WinZip command-line interface driven by a batch file. (I will go more into depth regarding this batch file later in this chapter.)

Contained in the XPI file will be a minimum of two files:

More complex extensions might have other files that are used as part of the installation process. An example is the Google Bar extension that also has install.js and googlebar.js.

All the root files in the XPI file are used for the extension’s installation. The extension’s actual functionality is always contained within the JAR file.

The following paragraphs cover the contents of the XPI file for this chapter’s extension project (see Figure 16.12).

Figure 16.12. This extension has only install.rdf and the extension’s JAR file for contents.

Contained within the extension’s JAR file are all the files that make up the extension. Some of the files often found in a JAR file include XUL, RDF, JavaScript, and various image files.

The files contained in this extension’s JAR file are shown in Figure 16.13.

Figure 16.13. The JAR file contains the actual extension’s working code.

There will be two or three files in the JAR:

A few other files can be used to streamline the extension packaging process. If you want to use it, the Extension Developer extension also provides this functionality.

The first supporting file is named makexpi.bat (see Listing 16.2). This is a command batch file that calls the command-line version of WinZip to create both the JAR file and the XPI file. Optionally, this batch file can do other cleanup tasks as well. Comments have been added to this file to make its function clearer.

@echo off

If X%1 == Xhelp (
Echo makexpi [firefox]
Echo where specifying firefox builds for Firefox 1.1.x and later.
Echo if no parameter is specified this will build
Echo a Firefox version 1.0.x and earlier
Echo extension.
goto end
)

REM the debug.txt file holds the output from all the commands.
REM This keeps execution cleaner.
time /T >debug.txt

REM - Create the JAR file first. WinZip will add or create as necessary.

echo Refreshing the JAR file! >>debug.txt
REM This line is for versions of Firefox 1.0.x and earlier.

If X%1 == Xfirefox (
   "%programfiles%WinZipwzzip" -a -r -P chromemyextension.jar content
myextensionOverlay.js contentmyextension-Overlay.xul >>debug.txt
) else (
   "%programfiles%WinZipwzzip" -a -r -P chromemyextension.jar content >>debug.txt
)

REM - Build the XPI file
echo Refreshing the XPI file! >>debug.txt

If X%1 == Xfirefox (
"%programfiles%WinZipwzzip" -a -r -P MyExtension.xpi chromemyextension.jar chrome
.manifest install.rdf >>debug.txt
) else (
"%programfiles%WinZipwzzip" -a -r -P MyExtension.xpi chromemyextension.jar install.rdf
 >>debug.txt
)

REM - Tell when this build was made

echo Desplaying the timestamp! >>debug.txt
Echo Generate time was

type time.txt

REM - Restore profile to clean version

echo Refreshing the Firefox profile! >>debug.txt

call clearprofile.bat

Rem bailout on help and errors label
:end

In Listing 16.3, you must change the parts in bold to whatever filenames you want for your extension.

@echo off

Rem you *must* fix the profile name below (in bold) to match your profile name!

RD /s /q "%appdata%MozillaFirefoxProfilesjvaofcos.Testing Profile"
MD ""%appdata%MozillaFirefoxProfilesjvaofcos.Testing Profile"
xcopy /s /y ""%appdata%MozillaFirefoxProfilesjvaofcos.Testing Profile.bak" "%appdata%
MozillaFirefoxProfilesjvaofcos.Testing Profile
" >>debug.txt

In Listing 16.3, you must change jvaofcos.Testing Profile to reflect the name of the Firefox profile you created for testing and debugging purposes.

The install.rdf file is the file Firefox uses to install the extension (see Listing 16.4). This file describes the extension and provides Firefox with the name and location for the extension’s JAR file.

<?xml version="1.0"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#">

   <Description about="urn:mozilla:install-manifest">
     <em:id>{71536D06-A8BD-411a-BC0C-15C1FDB7DF2A}</em:id>
     <em:version>0.1.05</em:version>
     <em:targetApplication>
       <Description>
         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
         <em:minVersion>0.9</em:minVersion>
         <em:maxVersion>1.0</em:maxVersion>
       </Description>
     </em:targetApplication>
     <em:name>My Extension</em:name>
     <em:file>
       <Description about="urn:mozilla:extension:file:myextension.jar">
         <em:package>content/</em:package>
       </Description>
     </em:file>
   </Description>
</RDF>

In the install.rdf file, you must provide a new GUID for your extension. My GUID was 71536D06-A8BD-411a-BC0C-15C1FDB7DF2A, and it is in bold in the listing. Please don’t just change a few numbers trying to make your own GUID; use a generator as described previously to make a new GUID.

The minVersion and maxVersion need to be changed to reflect for which versions of Firefox your extension is designed. The defaults in Listing 16.4 are what you should use for versions of Firefox before 1.5.

WW[.XX[.YY[.ZZ]]][+]

The name My Extension should be changed to the name of your extension. Spaces are acceptable, and no quotation marks are needed.

The JAR filename, myextension, must be the same as the JAR file created by makexpi.bat.

Everything else in install.rdf should remain the same.

The contents.rdf file needs some modifications, as shown in Listing 16.5.

<?xml version="1.0"?>
<RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
      xmlns:chrome="http://www.mozilla.org/rdf/chrome#">

  <RDF:Seq about="urn:mozilla:package:root">
    <RDF:li resource="urn:mozilla:package:myextension"/>

 </RDF:Seq>

 <RDF:Description about="urn:mozilla:package:myextension"
   chrome:displayName="My Extension"
   chrome:author="Peter D. Hipson"
   chrome:authorURL="http://www.hipson.net"
   chrome:name="myextension"
   chrome:extension="true"
   chrome:settingsURL="chrome://myextension/content/settings/settings.xul"
   chrome:description="Add a menu item to Files in Firefox.">
 </RDF:Description>

 <RDF:Seq about="urn:mozilla:overlays">
   <RDF:li resource="chrome://browser/content/browser.xul"/>
 </RDF:Seq>

 <!-- overlay information for Mozilla Firebird-->
 <RDF:Seq about="chrome://browser/content/browser.xul">
   <RDF:li>chrome://myextension/content/myextension-Overlay.xul</RDF:li>
 </RDF:Seq>
</RDF:RDF>

In Listing 16.5, the lines starting with chrome: should be changed as appropriate. The chrome:name value should match the name in chrome:settingsURL and in the chrome://myextension line.

The myextension-Overlay name should match the name of your extension’s XUL file. Mozilla conventions say that overlay should be part of the name.

You need to modify the myextension-Overlay.xul file as shown in Listing 16.6. This filename needs to match the name in the contents.rdf file (refer to Listing 16.5). This file is identical for all versions of Firefox.

<?xml version="1.0"?>

<overlay id="MyExtensionOverlay"

xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

// Include the Javascript

  <script type="application/x-javascript"
  src="chrome://myextension/content/myextensionOverlay.js">
  </script>

  <menupopup id="menu_FilePopup">
    <menuitem label="My Extension" position="1" oncommand= "myextensionmessage();" />
  </menupopup>
</overlay>

In the myextension-Overlay.xul file, you must give the overlay a name. Change MyExtensionOverlay to a name that suits your extension’s name.

In the chrome: line, the myextension should be changed to match the chrome:name in the contents.rdf file.

The menuitem line needs to reflect whatever chrome changes your extension is doing. I’m adding a menu item, but you might be doing something different. The myextensionmessage() call to JavaScript must match your JavaScript functions, if you use JavaScript, or whatever way you choose to add functionality to the menu item.

The myextension.js file contains the JavaScript code to give my extension its functionality (see Listing 16.7). In the listing, you would rename it to match the name in the myextension.xul file. This extension is trivial—it just displays a message box using the JavaScript alert() function call. This file is the same for all versions of myextension.

// An example of some JavaScript functionality.
// You could code virtually any functionalty that
// JavaScript supports here:

function myextensionmessage() {

    alert("         ...and, it worked!         ");
}

If you decide to use JavaScript in your extension, you could use this file to hold your JavaScript functionality. As extensions grow more complex, additional JavaScript source files might need to be added.

Because some of the changes to install.rdf will be new even to experienced extension writers, let’s cover them in detail. First, Listing 16.8 shows the new install.rdf file.

Most of the changes in install.rdf involve the addition of lines and some minor rearranging of content.

<?xml version="1.0"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#">

  <Description about="urn:mozilla:install-manifest">
    <em:id>{71536D06-A8BD-411a-BC0C-15C1FDB7DF2A}</em:id>
    <em:version>0.1.05</em:version>
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.0</em:minVersion>
        <em:maxVersion>1.5+</em:maxVersion>
      </Description>
    </em:targetApplication>

    <!-- Front End MetaData -->
    <em:name>My Extension</em:name>
    <em:creator>Peter D. Hipson</em:creator>
    <em:description>Add a menu item to Files in Firefox. </em:description>
    <em:homepageURL>http://www.hipson.net</em:homepageURL>
    <em:updateURL>http://www.hipson.net</em:updateURL>

    <em:file>
      <Description about="urn:mozilla:extension:file:myextension.jar">
        <em:package>content/</em:package>
      </Description>
    </em:file>
  </Description>
</RDF>

In addition to the name and GUID changes outlined in Listing 16.8, in versions of Firefox earlier than 1.5, you need to make the following changes to your install.rdf file.

You should create a new section, preceded by the following comment line:

<!-- Front End MetaData -->

This comment indicates that data for your extension follows. Next, add four lines that take data that was in your contents.rdf file and place them in install.rdf. The format of the lines will change—we are only interested in the extension-specific data that has been highlighted in the listing.

The <em:name>My Extension</em:name> remains the same as the previous example:

<em:creator>Peter D. Hipson</em:creator>

The em:creator line takes the data that was in the contents.rdf file’s chrome:author line. No quotes are needed for this field:

<em:description>Add a menu item to Files in Firefox. </em:description>

The em:description line takes the description that was in the chrome:description line in the contents.rdf file:

<em:homepageURL> http://www.hipson.net</em:homepageURL>

The data in em:homepageURL is the chrome:authorURL data from contents.rdf:

<em:updateURL>http://www.hipson.net</em:updateURL>

The em:updateURL data was not present in the sample contents.rdf file and simply specifies where to look for updates to this extension.

The chrome.manifest file is new to Firefox 1.5 (see Listing 16.9). It is intended to replace the complex and often problematic contents.rdf file with something that’s easier to work with.

This file, in this example, has just two lines, making it considerably shorter than contents.rdf. The file is a simple text format, created with Notepad or your favorite text editor.

overlay chrome://browser/content/browser.xul chrome://myextension/content
/myextension-Overlay.xul
content myextension jar:chrome/myextension.jar!/content/

A chrome.manifest file has, at a minimum, the lines shown in Listing 16.9. Some additional lines might be present in a more complex extension’s chrome.manifest file.

These potential lines are listed in the following, along with a description. Compare these specification lines with the lines in Listing 16.9 to see how the parameters would change. Items in bold would change to match your extension.

The content package line describes the extension (packagename) and the location of the extension’s JAR (or other content) file:

content packagename path/to/files

In the chrome.manifest file, the path/to/files was jar:chrome/myextension.jar!/content/. The exclamation point after the JAR file’s extension is required, so don’t forget it.

The locale package line specifies the locale name and the path to that locale’s files. This line is required in chrome.manifest:

locale packagename localename path/to/files

An example of this line is locale myextension en-US jar:en-US.jar!/locale/en-US/myextension. In this example, en-US is the locale identifier for English in the United States. The en-US.jar file is the JAR file containing elements specific to the locale and the location in that JAR file of the necessary content. This file is optional in chrome.manifest.

The skin package line specifies the extension’s skin (think theme) location. Again, it includes the package name and a path to files that would be similar to that in the previous examples:

skin packagename skinname path/to/files

The XUL overlay package line specifies the extension’s XUL overlay’s location. There is a path to the chrome for this extension:

overlay chrome://file-to-overlay chrome://overlay-file

An example of this line from chrome.manifest is

overlay chrome://browser/content/browser.xul chrome://myextension/content
/myextension-Overlay.xul

This code gives the information provided in the contents.rdf file’s overlay section.

Many extensions modify the Cascading Style Sheets (CSS) used by Firefox. The style overlay line provides this information in a format similar to the previous overlay line:

style chrome://file-to-style chrome://stylesheet-file

Firefox is a multiplatform product, meaning it will run on Windows, Linux, and Mac OS/X. If your extension is specific to one of these platforms, add the keyword platform at the end of the content lines.

More complex extensions have multiple occurrences of these lines in chrome.manifest. If you want to learn more about chrome.manifest, go to http://www.mozilla.org/xpfe/ConfigChromeSpec.html.