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 Addons are basically Firefox extensions tailored for PFF integration, so this tutorial assumes you know a tab bit of XUL, CSS and Javascript.
In reality you can get away with knowing any XUL for the time being and to use this tutorial, and as you go along you'll start to pick it up really easily.
1) First, grab the following two Add-ons for PFF 1.3
2) Drag and drop each .xpi file onto firefox (seperately) and you will be prompted to install the addons as Firefox extension.
3) Restart Firefox and launch pff, then click on the "Settings" nav bar button then the 'Add-ons' tab
3) Enable both of the add-ons by clicking on them, you should see their checkboxe's checked
You have now both installed and enabled your first PFF Add-ons.
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 can have 3 main components
Before looking at the code, let's show 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 has loaded.
This is usefull if you need to run some code when PFF starts.
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.
The second function call the Template add-on accepts 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 shows us the following prompt:
This aswell is a placeholder so you know where to place any code you want executed when the tab is clicked and the content is shown.
The contet placeholder for the Template looks like this:
This will all make more sense furthur 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 placeholder effectively giving you an embeded 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;
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 )
This 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 Addon 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 is you did a search and replace for "PFF Template" to "My First".
For kicks, I'm also going to change the words of the content:
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:
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
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 the files for distributing you 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.
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;
PFF Addons are basically Firefox extensions tailored for PFF integration, so this tutorial assumes you know a tab bit of XUL, CSS and Javascript.
In reality you can get away with knowing any XUL for the time being and to use this tutorial, and as you go along you'll start to pick it up really easily.
Getting Started
1) First, grab the following two Add-ons for PFF 1.3
2) Drag and drop each .xpi file onto firefox (seperately) and you will be prompted to install the addons as Firefox extension.
3) Restart Firefox and launch pff, then click on the "Settings" nav bar button then the 'Add-ons' tab
3) Enable both of the add-ons by clicking on them, you should see their checkboxe's 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 can have 3 main components
- A function call at PFF Startup
- A function call when it's tab is
- Registering with PFF
Before looking at the code, let's show 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 has loaded.
This is usefull if you need to run some code when PFF starts.
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.
The second function call the Template add-on accepts 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 shows us the following prompt:
This aswell is a placeholder so you know where to place any code you want executed when the tab is clicked and the content is shown.
The contet placeholder for the Template looks like this:
This will all make more sense furthur 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 placeholder effectively giving you an embeded FireFTP.
Template Add-on Content
Now we get into the fun part.
An addon has the following structure
Or the text version would be:
pffaddontemplate.xpi
/chrome.manifest
/install.rdf
/chrome/
/chrome/content/
/overlay.js
/overlay.xul
/chrome/skin/
/overlay.css
/pffaddontemplate-icon.png
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
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 )
This most important part of this file is the following:
var myfirstaddon = {
//Required fields: Change these values to reflect your Add-on
name: "PFF Template Add-on", //Add-on Name
version: "1.0", //Add-on version number
description: "A template add-on for PFF", //Add-on Description
author: "Jed Brown", //Add-on Author
id: "myfirstaddon", //Add-on internal name
pffver: 1.3, //Min PFF version supported
//User fields: add your own
myvariable: "hello" //Make sure the last defined var does not have a trailing ','
}
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:
var myfirstaddon = {
//Required fields: Change these values to reflect your Add-on
name: "My First", //Add-on Name
version: "0.5", //Add-on version number
description: "My First PFF Add-on", //Add-on Description
author: "Jed Brown", //Add-on Author
id: "myfirstaddon", //Add-on internal name
pffver: 1.3 //Min PFF version supported
}
Now we have a new and working PFF Addon.
Let's open up the overlay.xul file and change the name of the Addon 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 is you did a search and replace for "PFF Template" to "My First".
For kicks, I'm also going to change the words of the content:
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:
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
That was easy!
Now let's look at the overlay.js file again, specifically the following functions:
myfirstaddon.onPFFLoad = function () {
alert("Hello world, its the "+myfirstaddon.name+" addon\n Doing something when PFF loads\n or this addon is enabled!")
}
and
myfirstaddon.onThisTabClick = function () {
alert("Hello world, its the "+myfirstaddon.name+" addon\n Doing something after it's tab was clicked!");
}
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 you 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:
myfirstaddon.xpi
/chrome.manifest
/install.rdf
/chrome/
/chrome/content/
/overlay.js
/overlay.xul
/chrome/skin/
/overlay.css
/myfirstaddon-icon.png
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.
More about Extension Writtting
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;
powered by performancing firefox
No comments:
Post a Comment