Creating an Add-on for PFF 1.3

Two of the new features in Performancing Firefox 1.3 allows you to write Addons and Themes. This tutorial will get you started on your first Add-on for PFF.

PFF Add-ons are basically Firefox extensions tailored for PFF integration, so this tutorial assumes you know a bit of XUL, CSS and Javascript.

In reality you can get away without knowing any XUL for the time bein as it's really easy to get a hold of as you go along. A small bit of Javascript knowledge is really all you need (and a zip manager like winrar, 7-zip or winzip).

Getting Started

1) First, grab the following two Add-ons for PFF 1.3

1. FireFTP for PFF
2. PFF Add-on Template

2) Drag and drop each .xpi file onto firefox (seperately) and you will be prompted to install the addons as Firefox extension. (or install them directly by white-listing performancing.com)

3) Restart Firefox and launch pff, then click on the "Settings" nav bar button then the 'Add-ons' tab

4) Enable both of the add-ons by clicking on them, you should see them checked

You have now both installed and enabled your first PFF Add-ons.

Getting to know the Template Add-on

The template extension was built to facilitate you for packaging your add-on as a template and as a showcase for the easy api calls in PFF.

Understanding the Template Functionality:

The template add-on has placeholder prompts for events in PFF and placeholder XUL elements for the tab listing and content. We'll explain that a bit more further down.

Add-ons in PFF are based on 3 main features

1. Respond to a function call at PFF Startup
2. Respond to a function call when it's tab is clicked and the xul content is shown
3. Registering with PFF

Before looking at the code, let's look at what the first two look like.

When you enabled the Template add-on, you saw a prompt stating that the addon was loaded (this is a placeholder) as seen in the image below:

The function that displays this prompt is called everytime pff is loaded, or better put, when pff is loaded and the addon registers itself with pff (hence why it also triggers when you enabled the plugin for the first time).
This is usefull if you need to run some code when PFF starts (i.e. modify a button, change text, add a style, etc.).

Now that the addon has loaded you will see it under the Addons tab. Note however that the addons tab will only show when you have one or more addons enabled.
Clicking on the 'Add-on' tab toggles the visibility of the add-on tabs.

The second function call the Template add-on catches is when the add-on's tab is clicked.
Clicking on the PFF Template tab as shown in the image above will load the add-on's content and fire off a function call that then triggers the following prompt:

This as well is a place holder so you know where to place any code you want executed when the tab is clicked and the content is shown.

The content place holder for the Template looks like this:

This will all make more sense further on where we look at the code.
In the example of the Fireftp plugin. We only use #2 and #3,

Since we only care about when the FireFTP tab is clicked, when that function is called we load FireFTP into our content's place holder effectively giving you an embedded FireFTP.

Template Add-on Content

Now we get into the fun part.
An addon has the following structure

Or the text version would be:

The important bits here are;

• overlay.js -- Where your addon's code will be
• overlay.xul -- the xul (interface) for your addon
• overlay.css -- the css styling for your xul

While the rest of the files are important, for a basic addon, all you need to do with them is replace all instances of the template name with your own.

Editing the Template add-on

Now that you have installed the template addon, let's modify it to make your own.
First, locate your Firefox Profile (see Locate your profile folder)
then go to the extensions\pffaddontemplate@performancing.com\ directory.
     i.e. On windows mine looks something like this:
C:\Documents and Settings\Jed\Application Data\Mozilla\Firefox\Profiles\se6t32gw.pff-svn-dev\extensions\pffaddontemplate@performancing.com\

The pffaddontemplate@performancing.com is the unique identifer for the add-on.
In my case I'm going to rename it to myfirstaddon@performancing.com however you can use whatever name you want somename@somedomain.com

In this directory you will find the exact directory structure as I mentioned above.

Now that I've edited this dir to myfirstaddon@performancing.com
I then want to procede by renaming all instances of
pffaddontemplate with myfirstaddon

You can easily do this with jEdit by doing a search and replace and selecting 'directory' as shown in the image below:

Now that I've done that, lets open up the
overlay.js file
( /chrome/content/overlay.js )

The most important part of this file is the following:

This is what defines this Firefox extension as a PFF addon.
It's pretty obvious what each field does. In this example, I've changed mine to look like this:

Now we have a new and working PFF Addon.

Let's open up the overlay.xul file and change the name of the Add-on tab.
You'll see the following code:

The only change you need to make here is to the value=""
I've changed mine to looks like this

Optionally you could skip doing this if you do a search and replace for "PFF Template" to "My First".

For kicks, I'm also going to change the words of the content placeholder:

From:

To:

Here I changed the name of the 'label' element and added on onclick handler that will prompt us with the words "I clicked it" when you click on the 'This is my first!" text.

If you restart Firefox and re-launch pff, you should now have the following in your add-on's tab (click the Add-ons tab to see which ones are loaded, if you don't see your addon tab, make sure you've enabled it in the settings menu.):

Clicking on the tab should then give you a similar prompt as the Template add-on and show the following:

Here you can see the prompt that appears when I clicked on the "This is my first!" text as well.

That was easy!
Now let's look at the overlay.js file again, specifically the following functions:

and

In both of these sections, you can remove the alert(....); functions and replace them with your own code. For the FireFTP add-on I just placed a '//foo' where the alert function was in the onPFFLoad function to ignore when pff has loaded as I don't want to run any code then.

In onThisTabClick, I run code that loads fireFTP into an iframe I defined in the overlay.xul file.

Packaging your Add-on files:

Packaging the files for distributing your addon is easy.
Creat a .zip file with the content in your myfirst@... directory and rename your .zip to .xpi so your new XPI should have the following structure:

Depending on what you did with Search and Replace, you will also want to upen up the install.rdf file and edit the entries in there.
Specifically you will want to change the ID, Name, version, description and homepage to reflect your own addon.

Remember, your internal name (i.e. myfirstaddon) need to be consistent throughout your extension. As well as the directory name "myfirstaddon@performancing.com" needs to be the same as what's in the install.rdf file ID entry.

More about Extension Writing

As mentioned before PFF Addons are basically Firefox extensions tailored for PFF integration.
To learn more about Firefox Extension development, I'd start with the following links;

• http://developer.mozilla.org/en/docs/Extensions
• http://kb.mozillazine.org/Extension_development

Any questions or problems you have, please feel free to post in the developer forums.

powered by performancing firefox