jedb

One 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 theme for PFF.

Getting Started

1) First, grab the following three themes, and copy them to your hard drive:

• Black Theme
• Naked Theme (a.k.a No theme)
• PFF Default Template Theme
  

2) Open up PFF into a Tab in firefox or flock  (right click the toolbar icon and choose to open in tab)

3) Click on the “Settings” nav bar button then the ‘Theme’ tab

3) Click on the ‘Add’ button, or drag and drop the .css files onto the tab one by one.
You should then see all 4 themes installed.

4) Select the diferent themes and enable them to see them in action.

5) Decide what theme you would like to start off with. I recommend starting with the ‘Template Theme’ so you can see what the pff css looks like and what you can modify.

6) Copy the template_theme.css file to a new location and rename it.
    For this example I’m calling mine ‘mytheme.css‘.

7) Open the mytheme.css file in your favorite text editor (Mine is jEdit).

8) Leaving it in the exact format it’s in now, change the the following:


####################################
# @type: PFF Skin
####################################
# @name: My Theme
# @author: Jed Brown
# @desc: My First Theme
# @ver: 1.0
# @lddef: true
# @ver: 1.0
# @pffver: 1.3
####################################


You’ll notice I only changed the values of ‘@name’, ‘@Author’ and ‘@desc’
Please change those values and only those values for the time being.

9) Now add the mytheme.css file to the pff theme list (drag and drop or using the ‘add’ button.

8) Select your theme (“My Theme” in my example) and enable it.

9) Locate your Firefox Profile (see Locate your profile folder)
    then go to the performancing\skins\ directory.
     i.e. On windows mine looks something like this:

C:\Documents and Settings\Jed\Application Data\Mozilla\Firefox\Profiles\ajybcm75.pff\performancing\skins\

10)  You should see mytheme.css there now. Close your old version of mytheme.css and open the version from this directory.
You are done, you have now created your first PFF Theme!

Understanding the CSS file

Now that you have the mytheme.css open in your favorite editor, let the fun begin.
The template theme is heavily documented at the begining of the file, however I will go over the basics in details here.

The Requirements:

For a css file to be a PFF Theme, it must contain 7 key information bits.

1. @type – This says it’s a pff theme, the value has to be “PFF Theme”
2. @name– This is the Theme’s name (i.e. My Theme)
3. @author – This is your name (i.e. Jed Brown)
4. @desc – This a description of the Theme(i.e. My FIrst PFF Theme)
5. @ver – This the version number (i.e. 1.0)
6. @lddef – This defines if the default pff theme should be on or not. (defaults to true)
7. @pffver – Specifies the lowest version of PFF this theme is compatible with.

Let me explain #6 a bit more with an example.

If you are only going to make minor changes to the theme, like I have in the ‘Black’ theme, you would want to keep lddef (load default) on, as it will load the default pff theme first, then your custom theme. For example, I will do this in the mytheme.css file as I only want to add some small changes, effectivley overwritting some of the default theme, as opposed to recreating it from scratch.

This is great so that you don’t have to re-code every element in pff to get a functional theme.
If however you do want to start from zero set lddef to false.
This is what the ‘naked‘ theme has done. lddef is false and does not have any css at all (empty).

Open it up if you don’t believe me :).

So for the sake of this tutorial, lets assume I want to keep the PFF Default theme loaded and I want to make some changes to it.

Finding elements to style

The theme we are editing (Template theme now called ‘My Theme’), has the exact code from the default pff theme. It’s there for you to look over and get an idea of what is styled, etc.

For this tutorial I am going to remove all the styles from this mytheme.css file and start adding my own css.

Now with PFF in a tab in my firefox browser (right click the toolbar icon and choose to open in tab or type in the url: chrome://performancing/content/editor.xul )

Either hit “Ctrl-Shift-i” or go to “Tools->Dom inspector”.

This will launch Firefox’s Dom Inspector with PFF as the target

(if you don’t have the dom inspector, re-install firefox and select “custom” from the install options and enable the ‘Dome inspector’ from the tools section.)

Inspect an element

So for this tutorial, I want to change the Navigational button on the left side of PFF.
From the dom inspector window i click on the inspection () icon and click on the navbar tab I want to see.
(In the image below, I clicked on the ‘editor’ tab to inspect it)

So now i see a bunch of very usefull information

1. The xul:box’s parent id is ‘performancing-editor-tab’.
2. It’s class is ‘performancing-navbuttons-small’

Cool. Now I could search for these properties in the template theme to see what is already there, or, in this example of mytheme.css I’m going to dive right in and see what I can do.

In my editor, I paste in the following:
Code:



.performancing-navbuttons-small{
font-size: x-small;
color: red;
background-color: blue;
}




jEdit Screenshot:

I save the file then hit refresh () in firefox (refresh button or F5) and..

… we see the changes live. Wasn’t that easy?!

I can do other nifty stuff like:



.performancing-navbuttons-small:hover{
  font-size: large;
  color: yellow;
  background-color: black;
}


Now when i hover over a navbar I get this (yeah it’s ugly, but it’s an example):

I can do other cool stuff from information I get from the dom inspector like say,
any child of the navbar vbox that is a box should have a black background.
code:


#performancing-navbar-tabs > box{
 background-color: black;
}

result:

Remember, Firefox supports a whole boat load of CSS 1, 2 and 3 features.
So go ahead and use Type selectors, Child Selectors, Descendant Selectors, and all the other goodies. to make your life easier.

Using Images in your css file

So, now I showed you how to make a plain jane .css theme for PFF, but what about images?

Well you have two choices

1. Use urls to an image from a site or your harddrive
2. Packed images with your theme

Ideally you want to do #2, however for sake of easyness or testing you might want to do #1 first before you decide to package it.

In my theme, I want to change the insert image toolbar icon () with this one

code:



#image-button{
list-style-image: url('http://performancing.com/files/insertimage-icon2.png');
}


Done, damn that was easy!

Now, assuming i want to package my theme and give it to someone, I don’t want them downloing that image from my server every time they open up PFF.

So let’s make a theme package for PFF!

Making a Theme Package

While we are in our theme folder in our profile, it’s easy to add local files.
First, for a valid package, we need to create a new folder that has the same name as our .css file

My Theme’s file name is mytheme.css, so I create a directory called mytheme\
(..\performancing\skins\mytheme\)


I drop the insertimage-icon2.png in there and change mytheme.css to the following:
#image-button{
list-style-image: url('mytheme/insertimage-icon2.png');
}

Cool. So what does that mean?
It means anything I drop into that directory, all I need to access it is mythemename/someimage.png
You can also have folders inside of there. I might have this for example:
 i.e. mytheme/ui-images/myicon.png

and all I’d have to do is:
#image-button{
list-style-image: url('mytheme/ui-images/myicon.png');
}

Awesome, but what about the package?
All you have to do is zip up the mytheme.css file with it’s corresponding folder.
As an example, my new zip file looks like this:
        mytheme.zip
                  \mytheme.css
                  \mytheme\insertimage-icon2.png

So to refrase, the requirements for a theme package are;

1. The .css file name and directory name have to be the same
2. Only said .css and directory can be in the parent level

You can download my packaged mytheme.zip theme and a modified version of my black theme ‘black_byjed.zip’. They both contain the new ‘toolbar image’ icon.

That’s it!
Easy to distribute .css or .zip files for your new PFF theme!

To install your theme and test it out, all you have to do is either drag and drop it onto the Theme settings or use the ‘add’ button and select the zip file.

Any questions, comments or corrections please post here!

Enjoy

powered by performancing firefox