Contributing to Toolbar Buttons

First up thanks for your interest in contributing to Toolbar Buttons! If you actally end up contributing that is extreamlly apriciated. If not thanks for the thought.

At the end of this there are some suggestions on things that could be done, so before you start you might feel like jumping down the page and having a look over that.

Translations

Over half of Toolbar Button's users are non English speakers, so the translations are a very important part of the extension. There are two options for sending me new translations.

BabelZilla
BabelZilla has a web interface that allows you to translate the extension, it is easy to use and where most of the translations are contributed though.
Using the files
You can also just download the files off the web and translate them. If your sending new strings for a partially complete local put them into a new file, so I can see easily what has been added. Please use the contact page or the forum to get in contact with me to get the files added.

New Buttons/Features

If you feel more technially inclined it is possiable to easily add new buttons to the extension. There is however a few steps to getting set up.

Setup

First you need to get two programs to be able to get started (if you don't already have them).

Getting a copy of the extension

Now you need to get a copy of the extension source code. This includes both the code that is put inside the extension, the build system, and a web interface for building the extension. To do this on the command line run the following (this will create a new sub folder called ToolbarButtons).

svn checkout http://codefisher.org/svn/toolbar-buttons/trunk/ ToolbarButtons

You will need to edit the config/settings.py file. This is a text file so any decient text editor will do (NotePad may not work). You can go though and change any of the settings as you like, though it might be best to leave them in their default state if possible. You will however need to change profile_folder to either the location of your profile folder, or the value None (with out any quotes). This will help parts of the extension to be copied their when built, so you can have changes applied by simply restarting the browser. You also need to change image_path to the location of the icon set to be used by the extension. The latest copy of mine is a good idea.

Now return the the command line and run the following (you should be inside the folder that contains the build.py before you do, it will be in the folder where the code was downloaded to): python build.py

You should then get a copy of the extension inside the extensions folder. If you can't get this far it is time to ask for help on the Forum.

What development work can be done

There are three parts of the extension that you can work on.

I would assume that most people are interested in the last option, adding new buttons.

Creating a new button

I will be assumeing that you know a little bit about developing extensions in some Mozilla baised application, though someone with the ability to write a little JavaScript and some stuff that looks kind of like HTML (XUL) and follow the examples given should be able to follow along fine. The build system hides much of the complexity of creating an extension from you.

The first thing you need to do is create a new folder to put your new button in. The folder should be put inside the data folder. It's name should be the id that you intend to give the button. For new buttons I have begun to prefix them with tb- to guard against name conflicts. It is apriciated if you follow this convention.

At this point you might want to change the settings.py so the buttons setting is a comar seperated list of the buttons you intend to work on. All the other buttons will then be left out.

Inside this new folder you need to create a number of specially named text files. You can see what these need to be by looking at those of already existing button. For an example I am going to use the Full Screen button. It contains 5 files.

image

This file contains a listing of all the image files used by the button. It should use match the name of an icon in the icon set being used. At its simplist this means a single file name on a single line, and that will do for most buttons. However the file name can be seperated by a space from another selector like [disabled="true"] to use a different icon when the disabled attribute is added. There are also two commands for createing psudo images. If a file name is prefixed with - (hyphon) it will cause it be to grayscaled, often used for icons that control a setting to indicate the setting is turned off. If prefixed with * the image will be grayscaled and made partly transpartent. I use this for the icons of button when they are disabled.

description

A one line text description of what the button does. Not used in the extension itself, but is used online wherever a bit of a description is needed.

preferences (optional)

The new preferenced the button depends upon. The format is one per line separated from their value by a colon. A prefix will be automatically added. Use toolbar_buttons.interfaces.ExtensionPrefBranch when you need to access the setting from a script.

browser.js

This file can have a number of names depening on what application it will target. To get a complete list of possible names (not including the .js) look at the file_to_application setting in the config/settings.py file. Currently this gives:

  • browser - for Firefox/Flock's main window
  • messenger - for the main, read email and compose email windows of Thunerbird
  • mail - for the main window of Thunerbird
  • compose - for the compose email window of Thunderbird
  • read - for the read email window of Thunerbird
  • calendar - for Sunbird and Lightning
  • lightning - for only the Lightning extension
  • button - not in the list, implies all of the above

Mutiple files are posible. Inside any of these anything formatted as:

functionName: function(arg1, arg2,) { /* some code here */ }

Will be copied inside the toolbar_buttons object (prevents naming collisions, which is important to prevent conflicts with other extensions). Other code (like initialisation code) is just copied to the end of the generated file.

browser.xul

A small fragment of xul, for the toolbar button and all its attributes. The same rules about what names the file can have given above applies

strings
Not used in any of the offical buttons. But strings can be placed inside a file by this name. Put one string per line, the name of the string and its value seperated by an equals sign (=).

There are other possiable files/folders that can be added but I will leave them undocumented for now. For examples see the Stop Flash and Translate buttons.

As an alternative to usings the strings you can place any strings your button needs in a file in locale/en-US/ folder. The file name is arbitrary and matters little as they are all merged. The file type - dtd for those used in the xul, and properties for those used in the javascript - does matter. You are incourage to add a new file for any new buttons created.

If you then either save the output of svn diff or the zipped up files. I will add it in provided the following (which will easly be fulfiled in most cases):

Ideas for things to start on

I would think most people have their own little button to add, but if your just looking to get into some simple extension devolopment you can try the following.

The list of button requests.

There have been lots of stuff others have asked for, if anyone added any of the requested buttons for me that would be much appriciated.

Adding keyboard shortcuts

The extension supports having keyboard shortcuts assigned to buttons. Problem is adding them all in. Only one button currently has one, the Toggle Popup Blocker because that was a button contributed by someone else. What needs to be done is a key file needs to be added to each button. The thing is the decision needs to made individually for each button. Some buttons don't need it, for example the "Bookmark this Page..." as that is Ctrl+D, others might not work with it and would have to be fixed (I would not expect anyone else to do that though, just give me the list) and others might not make sense. Then you have to actually spend time working out what letter and modifiers would work, for which XUL Attribute modifiers would help a little. The file's format is simple enough, just a letter (or a translation string mapping to a letter, see the example button above) seperated from a list of modifiers by a : (colon). Currently they are disabled and you need to set use_keyboard_shortcuts to True in the settings.py