Using the Preferences Toolbar
This is the PrefBar User's Guide. Everything you need to know about using the PrefBar is right here in this file. Well, maybe not everything, but pretty darn close.
Installing the PrefBar
Showing the PrefBar
Customizing the PrefBar
Importing/Exporting Items
Known Bugs
Installing the PrefBar
The Preferences Toolbar was designed to work without errors on Mozilla builds 1.5-1.8 and Firefox release 1.0. Use on future Mozilla or Firefox releases should also work, unless the developers of said browsers change something major. The PrefBar has not been tested on any Netscape releases, so it may or may not work on them.
To install the PrefBar, click on the "Install Now" link on the prefbar installation page. You have to have the "JavaScript" and "Software Installation" preferences turned on in order for this to work.
If you are on an operating system with file permissions (such as any unix variant) be sure that you have permission to write to your mozilla chrome directory when you try to install the PrefBar. The most common installation problem with the PrefBar is linux users installing mozilla from root, and then trying to install the PrefBar as a regular user. Don't do this. It won't work.
After installation you will need to restart mozilla before you can use the PrefBar.
Showing the PrefBar
To show the Preferences Toolbar, either enable it via the "View->Show/Hide" menu (or the "View" menu in Phoenix), or by pressing the F8 key. If the second method doesn't work, try the first. If the PrefBar is not listed in the "View->Show/Hide" menu it probably means the install was not successful. See the previous section.
Customizing the PrefBar
To customize the PrefBar, click the Customize button on its far right, or go into the main preferences dialog and select "Preferences Toolbar" from the Advanced catagory.
The UI for customizing the toolbar is fairly straight forward. The buttons currently on the toolbar are shown in the right tree, and the available buttons not on the toolbar in the left tree. To add an existing button to the toolbar, select it in the left tree and click on "Add Item". To remove an item from the toolbar, select it in the right tree and click on "Remove Item". To reposition a toolbar item, selct it in either tree and click on "Move Up" or "Move Down". To create a new toolbar item, click on "New Item". To edit or delete an existing item, select it and click on "Edit Item" or "Delete Item"
Since version 3.0 you are also able to move the entries via drag&drop.
When editing existing buttons or creating new ones, you may encounter one or more of the following attributes:
- Id
- Everything has an Id, but they are used behind the scenes so you really don't have to worry about them much. Just use any old string. You only need to be sure that the Id is unique. Use an Id that tells what your button does in one little word. If your Id is not equal and you export the Item to give it to someone, then the person who gets your button-file may get problems with existing buttons.
- Label
- This is the label that will appear on the button and in the customization dialog.
- Onclick
- For a button, this is the code that is executed when someone clicks the button. The built in buttons have built in functions and therefore have very short onclick values. If you add your own buttons, you can use the multiline code editor to add multiline code with comments.
- Prefstring
-
This is the name of the preference the widget deals with. These aren't exactly documented anywhere, so the best way to find the prefstring of a new preference you want to add would be to look at the XUL source code for whatever preferences panel sets it normally.
- fromPref & topPref
-
This applies only the Pref checks. Because there are multiple types of prefs (int, bool, string, etc.) and because some of them take weird values, the prefbar maps them to the on and off state of the checkboxes using the frompref and topref attributes.
The frompref attribute is a javascript expression which, when evaluated, will return the state the checkbox is to be set to (i.e. either true or false.) The variable ‘value' holds the current state of the preference, so common frompref values are "value" and "!value". (Or "Boolean(value)" and "Boolean(!value)" if value is an int. Remember, the end result must be a bool.) Char prefs usually require weirder topref and frompref values.)
The topref attribute is the reverse of the frompref attribute. It is used to turn the boolean checkbox state variable into the appropriate pref value. Like frompref, topref must be a javascript expression which evaluates to the correct preference value, which must be of the same type as the preference involved. The "value" variable holds the "true" or "false" state of the checkbox in question. Common topref values are "value", "!value" and "2*Number(!value)".
Once again, the preferences are not very well documented, so the best way to find out what values a certain preference takes is by examining the XUL source code of the UI for that preference. If the preference in question doesn't have a UI, then you're pretty much on your own. - Get-function & Set-function
-
This applies only the Extchecks and the Extlists. These two button types are designed specially for scripts. They don't set preferences but calls the script if the user sets the checkbox/list or if Mozilla wants to get the current state.
The Get-function is a javascript expression which is called everytime when the PrefBar needs update. Here PrefBar wants to know what the current state of the item is. You have to set the variable 'value' to the current value.
The Set-function is a javascript expression which is called whenever the user changes the state of your item (selects item in list or checks/unchecks the checkbox). The new state is in the variable 'value'. - Label & Value
- When dealing with menulists, each option has a corresponding value which the preference defined in prefstring will be set to when that option is chosen. If the value for an option is "PREFBARDEFAULT" then the preference will be removed when that option is chosen. If both the value and label for a given option are empty, then those items will be ignored if you accept the dialog window.
- Url
- For a link, this is the url you will be taken to if you click on the link. Just like a bookmark, only less powerful.
Importing/Exporting Items
You can use the "Import" and "Export" Button on the preferences dialog to export buttons to "btn"-files and to import buttons from those files. This makes it possible to easily give buttons to others or to share buttons or button collections on the internet.
- Exporting
- To export buttons you first have to select the buttons you want to export in one of the lists in the preferences dialog. You can't export buttons from both lists at once! Then click the "Export" button. Now you'll be asked where you want to save the "btn"-file to. After clicking on "save" the file gets created.
- Importing
- If you get a "btn"-file you can easily import it using the "Import" button. After clicking on it you'll get a dialog where you have to navigate to your btn file. After clicking on "open" the file gets imported. You may be asked if you want to override existing items if one oft the buttons you want to import has the same "Id" as an existing button on prefbar.
Known Bugs
- none so far...