Hacking Firefox - part 35 potx

In addition, you will probably want your extension to be listed on one or more sites that host Mozilla extensions.. Creating JavaScript Installer Links You can create a direct link to yo

javascript.options.strict: When this preference is set to true, Firefox dis-plays JavaScript warnings in the JavaScript Console A warning usually means that you are doing something illegal or nonstandard in your code, and that might cause unex-pected behavior or other problems It is always recommended to solve all such problems before releasing your extension Enabling this preference causes all the warnings, not only those originating in your extension, to be reported to the JavaScript Console Many extensions have warnings in their code, and having several such extensions installed while trying to debug your own code might make finding only the relevant warnings difficult

browser.dom.window.dump.enabled: You should set this preference to trueif you want to use the dump()function to print messages to the standard console More information on this appears later in this chapter

As with other preference settings, you can type about:config in your Firefox address bar and use

the Preferences window to create new preferences and modify the existing ones Other methods for setting preferences, such as modifying the prefs.js file, will also work

Logging

Logging is a simple but very efficient method for debugging your code Printing the values of your variables, the received messages, return codes, and so on can help you figure out where the problem is and how it can be solved Logging can also be used to report major events and errors in your application, and looking at these messages can help you make sure that the appli-cation is actually doing what you expect it to do

There are several logging mechanisms in Mozilla:

Standard Console: You can use the dump()function to print messages to the standard console Similar to the alert()function,dump()expects a single string argument By default, the standard console is disabled in Firefox To enable it, set the value of the browser.dom.window.dump.enabledpreference to trueand start Firefox with the -consolecommand-line flag

JavaScript Console: This console can be opened using Tools ➪ JavaScript Console To

print a line to this console, you first obtain the nsIConsoleServiceinterface and then call its logStringMessagemethod:

var consoleService = Components.classes[‘@mozilla.org/consoleservice;1’]

.getService(Components.interfaces.nsIConsoleService); consoleService.logStringMessage(“Testing 1 2 3”);

Remove the debug messages before releasing your extension to the public Having a lot of such messages printed can slow your code down and create an unnecessary clutter in the console window You can create your own wrapper function that will determine whether the debug message should be printed:

function myPrintDebugMessage(message) {

if (gMyDebugging) { dump(message);

}

If you use the preceding function to print all your debug messages, toggling the value of the global gMyDebuggingflag turns all the messages on and off

You can often use the alert() function for basic debugging without needing any of the pre-ceding logging mechanisms Temporarily inserting a call to this function in the problematic piece

of code can sometimes help you quickly figure out what the problem is

Developer Extensions

Several extensions can be used to troubleshoot your extension Some of these are listed here:

The DOM Inspector can be used to examine the DOM structure of your documents,

their styles, and much more

Venkman is an advanced Mozilla-based JavaScript debugger.

Extension developer’s extension can be used to quickly run JavaScript code snippets,

edit XUL, HTML, and much more

ColorZilla can be used to quickly get various pieces of information about XUL

ele-ments, including their colors, ids, class names, and so on You can also use ColorZilla to quickly launch the DOM Inspector on the selected element

There are probably many other extensions you might find useful during the extension develop-ment process, and many new ones are being released all the time

Deploying Your Extension

You have created your extension, packaged it, and fixed all the bugs found Your creation is now ready for release to the public

Most authors create a home page for their extension The page typically contains some infor-mation about the extension, its author, and the latest version of the extension available for download In addition, you will probably want your extension to be listed on one or more sites that host Mozilla extensions

The Mozdev.org site allows you to host your Mozilla extension project on their servers and pro-vides many useful tools for managing the development process and collaborating with other developers Your extension must be released under an Open Source license to qualify for being hosted at Mozdev

Configuring Your Server

Firefox allows extensions to be installed directly from the Web without their having to be downloaded to the local disk first Giving your file an XPI extension and putting it on a web server isn’t enough for it to be installable directly from your site Your web server should send this file using the correct MIME type,application/x-xpinstall With Apache, this can be achieved by creating an htaccessfile that has the following line:

AddType application/x-xpinstall xpi

Inserting the preceding directive into an htaccess file and placing this file in a directory on your server allows you to change the MIME settings for this directory only, including all its subdirecto-ries Adding a similar line to the main httpd.conf file can make the setting global Also, many web hosting providers won’t give you access to the main http.conf file of your web server but will allow you to place local htaccess files in your directories

Creating JavaScript Installer Links

You can create a direct link to your XPI file on your web page, and if the file is sent using the application/x-xpinstallMIME type, clicking this link triggers the Firefox install mechanism:

<a href=”http://www.iosart.com/firefox/siteleds/SiteLeds_0.1.xpi”

title=”Install SiteLeds (right-click to download)”>Install SiteLeds 0.1</a>

There is an alternative way of triggering the extension installation process A global object called InstallTriggeris available to scripts running in web pages You can use this object’s methods to trigger the installation process and to verify that the extension was indeed success-fully installed Using this method also allows you to specify a custom icon that will appear in the installation dialog

An example of using InstallTriggerfollows:

<script type=”text/javascript” language=”JavaScript”>

function installCallback(name, result) { alert(‘The installation of ‘ + name +

‘ finished with a result code of ‘ + result);

}

function installExtension(aEvent) { var params = {

“SiteLeds”: { URL: aEvent.target.href,

IconURL: ‘http://www.iosart.com/firefox/siteleds/logo.png’, toString: function () { return this.URL; }

} };

// trigger the installation process:

var res = InstallTrigger.install(params, installCallback);

if (!res) { alert(‘Error calling install’);

}

return false;

}

</script>

<a href=”http://www.iosart.com/firefox/siteleds/SiteLeds_0.1.xpi”

title=”Install SiteLeds (right-click to download)”

Take a closer look at what we have done:

1 Adding an onclick=”return installExtension(event)to the anchor HTML element causes the intallExtensionfunction to be called when the link is clicked

The onclickhandler returns false, preventing the default anchor click action from being performed

2 Inside the installExtensionfunction, we define the parameter object for the installmethod This object contains the URLs of the extension XPI package and its icon

3 We then call the InstallTrigger.installfunction The second parameter is the name of the function that will be called when the installation completes (or in case the user cancels the installation)

4 If InstallTrigger.installreturns a zero result, there was a problem starting the installation process For example, your site may not be on the user’s white list for sites that are allowed to install extensions In this case, the user should see a Firefox notifica-tion, but you can further explain the situation by displaying an appropriate popup mes-sage or redirecting the user to an explanation page, for example

5 When the installation process finishes or is cancelled by the user, the

installCallbackfunction is called This function receives two parameters: the URL

of the extension package and the installation result code A zero result code means suc-cessful installation

Getting Your Extension Listed

There are several sites that list Mozilla extensions Users often visit these sites to check out the new extensions or when they are looking for an extension with a specific functionality If you want people to notice your new extension, you should have it listed on one or more of the fol-lowing sites:

Mozilla Update (addons.mozilla.org): This is the official Mozilla extensions site.

The Extension Manager dialog links to it, and this makes it the first place that the users look for new extensions The site contains a FAQ with information about getting your extension listed

The Extension Mirror (www.extensionsmirror.nl): A very active site with the

largest index of the existing extensions The site administrators actively look for new extensions on the Web and on the MozillaZine forums and publish them on the site, so theoretically you don’t have to do anything to get your extension listed The Extension Mirror has an Announcements forum where you can announce your extension to make sure it is noticed by the administrators

The Extension Room (extensionroom.mozdev.org): A popular index of Mozilla

extensions The site has instructions for getting your extension listed

The MozillaZine Extensions Forum (forums.mozillazine.org): Many extension

authors announce their extensions on this forum, which is read by many members of the Mozilla community You can start a new topic, letting people know about your new extension and its purpose People can comment on this post, providing valuable feed-back, comments, and bug reports

Extension Programming Techniques

The previous sections have shown how you can create a simple extension This section intro-duces additional techniques that can be useful for creating extensions that are more elaborate

Understanding the Browser Chrome

You saw that to extend a XUL user interface you need to know its structure: the elements you want to overlay, their hierarchy, ids, and so on If you want to extend the browser, it is impor-tant to have a basic understanding of the browser chrome: its XUL windows and dialogs, style sheets, and JavaScript code There are several ways to learn about these components:

The DOM Inspector can help you navigate through the document hierarchy and exam-ine the user interface elements, their properties, and styles

You can learn a lot by looking at the browser code; just like your extension, the browser’s chrome is composed of XUL, CSS, and JavaScript files you can examine

The Web offers a lot of useful information, including documentation, references, tutori-als, and so on See the “Online Resources” section, later in this chapter, for some useful links,

Finally, you can use the Discussion Forums and the IRC to ask for help from your fellow community members The “Online Resources” section lists some popular forums and IRC channels

Using the DOM Inspector

The DOM Inspector is launched by choosing Tools ➪ DOM Inspector in your browser The main window is divided into two panes, as shown in Figure 17-8 The left pane displays the DOM tree, a hierarchical structured view of the document elements The right pane displays detailed information about the selected element (its DOM attributes, style sheets, properties, and much more)

The DOM Inspector is included in the Firefox installer, but you may need to choose the Custom installation option and select Developer Tools to have it installed

To start examining a XUL window, make sure it is open and then select it from the File ➪ Inspect a Window list in the DOM Inspector Once the desired window is selected, its URL appears on the DOM Inspector address bar, and the left pane is updated to reflect its DOM structure You can now explore the document tree in the left panel by expanding and collapsing the tree elements When you select a visible UI element in the tree, it is highlighted by a blink-ing red border in the target window

You can search for specific elements by their tag name, id, or attribute by choosing Search ➪ Find Nodes , as shown in Figure 17-9

F IGURE 17-8: The DOM Inspector window

F IGURE 17-9: The DOM Inspector Find Nodes dialog

You can also find a visible user interface element by choosing Search ➪ Select Element By Click and then clicking on the desired element in the window you are examining If the DOM Inspector successfully finds the element you clicked on, the element is highlighted by a blink-ing red border for a few seconds and then selected in the DOM Inspector tree view

If you want to examine a specific visible element when the DOM Inspector isn’t open, you have

to open the DOM Inspector, select the desired window, choose Select Element By Click, return to the window, click on the wanted element, and then return to the DOM Inspector dialog With the ColorZilla extension, there is a faster way of achieving the same thing Click on the ColorZilla status bar icon, click on the desired element, and then choose DOM Inspector from the ColorZilla context menu The DOM Inspector will be launched with the desired element selected

in the left pane

Once you have selected the element you want to inspect in the left pane, the right pane can be used to examine it more closely You can use the drop-down list above the right panel to select the type of information you are interested in, as shown in Figure 17-10

F IGURE 17-10: The various types of information provided by the DOM Inspector

Here’s a brief overview of the available information types:

DOM Node: This displays some basic information about the selected DOM node,

including its tag name, attributes with their values, and so on

Box Model: Displays the element’s layout information, including its position,

dimen-sions, margins, and so on

XBL Bindings: XUL elements can be extended using Extensible Binding Language

(XBL) This view displays information about the XBL definitions that were applied to the selected element

CSS Style Rules: Displays all the CSS rules that are applicable to the selected element

and information about the style sheets and the selectors that contributed these rules

Computed Style: After the various CSS rules applicable to the selected element are

merged and all the conflicts are resolved according to the cascading order, an element

receives its final set of styles This set of styles, called the computed style, is displayed in

this view

JavaScript Object: Every element is an object with a set of properties and functions that

can be accessed using JavaScript This view displays these properties and their values Besides allowing you to examine the selected elements, the DOM Inspector allows you to modify them dynamically For example, you can modify and delete the existing element’s attributes or even add new ones by using the context menu in the DOM Node view, as shown

in Figure 17-11 By using the context menu in the left pane, you can manipulate the selected element (delete it, duplicate it, set its pseudo-classes to hover, active, or focus, and so on) The DOM Inspector is a very powerful tool that can be used both for learning and for trou-bleshooting purposes If you learn to use it, you will surely find it indispensable

F IGURE 17-11: Dynamically changing the node’s attributes

Examining the Source Code

One of the great things about the Mozilla platform is that it is open source If you are not sure about how something works, you can always take a look at the code and see exactly what is happening behind the scenes

Typically, you will want to understand how some part of the browser works by looking at its XUL and JavaScript files You can use the DOM Inspector to find out what XUL file defines a specific part of the UI Just open the wanted window with the DOM Inspector and look at its address bar For example, when examining the Options dialog you will see the following:

chrome://browser/content/pref/pref.xul This means that this dialog is defined in the pref.xulfile inside the browserchrome package

There are several ways to find the needed source files and examine them, including the following:

If you have Firefox installed, you already have all the browser chrome XUL, CSS, JavaScript, and other files on your machine They are located in the chrome subdirectory under the main Firefox application folder In this directory, you will find several JAR files (browser.jar, toolkit.jar, and so on) These files are very similar to the chrome JAR file we created for our extension in the previous sections; they contain the chrome that the browser itself is built of For example, if you want to look at the browser.xul file found at chrome://browser/content/browser.xul, you should look inside the browser

jar file that contains the browser package Looking inside the installed-chrome.txt file in the chrome directory can give you an idea about the installed browser chrome packages and the JAR files that contain them

We already mentioned that JAR files are regular ZIP archives You can extract all the files from a JAR archive and examine them, perform a search for specific keywords, and

so on Also, many ZIP programs allow you to take a quick look at a file inside an archive without needing to extract it first

The Mozilla Cross-Reference site, located at http://lxr.mozilla.org, contains all the latest Mozilla source code You can browse and search this code until you find the needed information For example, the browser.xul file can be found here:

http://lxr.mozilla.org/mozilla/source/browser/base/content/browser.xul

The site is very useful if you want to see the file history, including when the file changed, who changed it, and what bugs were fixed in the process Another useful feature is that you can easily create a link to a specific line in any file — the line numbers in the code listing pages are actually links — and use this link elsewhere, for example, to create a bookmark, report a problem, or ask questions about the code

You can download the complete Firefox source code and extract it to a local directory For example, Firefox 1.0 source code is a 31MB archive that can be downloaded from here:

http://ftp.mozilla.org/pub/mozilla.org/firefox/releases/1.0/source/firefox-1.0-source.tar.bz2

You can browse the Mozilla FTP site (http://ftp.mozilla.org/pub/

mozilla.org/) and find the source code package that is most appropriate for your needs

Once the code is extracted, you will get a directory tree very similar to the one found at the Mozilla Cross-Reference site

The Mozilla source code package is compressed using the BZIP2 format Many compression programs (7-Zip is one) support this format and can be used to open such archives

Online Resources

If examining the document structure and looking at the code didn’t get you closer to under-standing how things work, you can try finding more information on the Web or asking your fellow Firefox hackers for help This section lists the most useful online resources for extension developers

XULPlanet (http://www.xulplanet.com/): An excellent resource packed with

Mozilla-related guides, tutorials, and examples The site has several reference sections covering everything from XUL to XPCOM components

Mozilla.org (http://www.mozilla.org): Has a lot of useful information for

devel-opers Most of it is linked from the documentation page at http://www.mozilla org/docs/, but there are many additional resources scattered around the site You can

do a site search to try to find the needed information

MozillaZine.org knowledge base (http://kb.mozillazine.org): A user-contributed wiki with many useful articles, guides, and links to additional resources The Development section has a lot of information on extension programming

MozillaZine forums (http://forums.mozillazine.org/): Post your questions and comments here The site has a Mozilla development section with a forum dedicated

to extensions

netscape.public.mozilla newsgroups (http://www.mozilla.org/community/

developer-forums.html): You can search the newsgroups for the wanted informa-tion or post your Mozilla development-related quesinforma-tions The Mozilla.org site has a list

of the available newsgroups and their topics

Internet Relay Chat (IRC) (irc://irc.mozilla.org/): There are several IRC channels you can visit to chat with your fellow Mozilla developers in real time Several developer channels, including #developers,#mozilla, and others, can be found on the Mozilla.org IRC server

More XUL

This section introduces several additional XUL-related techniques you might find useful in the process of extension development

More XUL Elements

After reading the XUL section in Chapter 16 and going over the various examples in this chapter, you should have a pretty good understanding of how XUL elements can be used to create a user interface This section provides some additional examples of the basic XUL wid-gets and is intended to give you a taste of the most common UI elements and their XUL repre-sentations

If you want to test the XUL code in the following examples, you can create a file with an xul extension and the following contents:

<?xml version=”1.0” encoding=”UTF-8”?>

<window align=”start”

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

[Your XUL widgets go here]

.

</window>

Once you create the file and insert some XUL elements, you can open it in Firefox using File ➪ Open File The align=”start” part makes sure your XUL widgets are shown correctly when opened inside the browser window