PrefBar Help    
Introduction Using the Preferences Toolbar What's New? Button List PrefBar FAQ Credits Help/Feedback

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.

Showing the PrefBar
Moving PrefBar buttons to other toolbars
Showing PrefBar contents as menu button
Customizing the PrefBar
Why you shouldn't edit most of the built in buttons
Built in buttons you may edit
Importing/Exporting Items
Hidden preferences


Showing the PrefBar

To show the Preferences Toolbar, either enable it via the "View->Show/Hide" menu (or the "View->Toolbars" menu in Firefox), or by pressing the F8 key. If the second method doesn't work, try the first.

Moving PrefBar buttons to other toolbars

PrefBar starts up as a new toolbar, which may be toggled by any hotkey, you define for it, but this doesn't mean, that you have to keep the buttons on their own toolbar. Starting with PrefBar 5.0, PrefBar is a so called "customizable toolbar". This means, that you may either place foreign buttons to the PrefBar toolbar (and toggle them together with the other PrefBar items using your defined hotkey!) or place the PrefBar button group to any toolbar, you want. If you moved the PrefBar stuff from their own toolbar, you may just hide it to save space. To do this, right click on any Toolbar, despite PrefBar itself, and choose "Customize..." there. This way, you enter "toolbar customize mode", where you may drag&drop items around.

Starting with PrefBar 5.1, you may also place PrefBar's buttons below one single menu button. You find this button, named "PrefBar menu" in the toolbar customize dialog of your browser (see: Moving PrefBar buttons to other toolbars ). After placing this button to anywhere, you like, you may just hide the PrefBar toolbar completely.

Customizing the PrefBar

To customize the PrefBar, right click onto PrefBar and choose "Customize PrefBar..." from there. You may also reach this from the main browser configuration in SeaMonkey and via the Addons manager in SeaMonkey and Firefox, but the context menu is the fastest way.

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, you drag it from the left list to the right list. To remove an item, do it the other way round. You'll also use drag&drop to sort the items in both lists. All additional functions are available via context menu.

When editing existing buttons or creating new ones, you may encounter one or more of the following attributes:

Id
Everything has an Id. You 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 button, to give it to someone, then the person, who gets your button-file, may get problems with existing buttons. This is particularly important, if you like to share your button on the internet.
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 Buttons, Extchecks and the Extlists. These button types are designed specially for scripts. They don't set preferences, but call the script, if the user clicks the button, 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".
Init-function
The Init-function is an optional javascript expression, which may be used to place code, which is required to initialize your button. The code will be called once on startup of the browser and on any prefbar-database-change. This means, that the Init-function may get called more than once in one browser session!
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 "!RESET!", then the preference will be resetted to its default setting (like "Reset" in about:config). 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.
Hotkey
The field "hotkey" enables you to set a hotkey for this button. If this hotkey is pressed in the browser window, then the function of the button gets called, just as if you had clicked the button with your mouse.

Why you shouldn't edit most of the built in buttons

Even as you know now how to edit buttons it's not recommended to do so with most properties of the built in buttons without creating a copy of the button before (right click on button in customize window, choose "Copy" and enter a new ID for your button). The reason is simple: As soon as you get a new PrefBar version and update the buttons, PrefBar will immediately update its built in buttons and your changes are lost!

Exceptions to this rule are:

You may also have a look at the button list to see in detail which buttons you should not edit. If those buttons really have a bug, please tell me. It's the task of the PrefBar team to fix this. You should have no reason to modify the buttons on your own.

Built in buttons you may edit

There are some buttons that are a special case. As they are not usable without editing some things there are some parts excluded from update. Here I want to inform you how to edit those buttons to make them usable for you.

Resize

Here you may add your own screen resolutions using the edit button. The format is:

$WIDTHx$HEIGHT

User Agent
Feel free to add own user agents here. Starting with PrefBar 3.3 there are two ways to do this:
Just entering the User Agent string

As value for your new user agent you may just enter a user agent value of your choice. For example this is the user agent of mozilla 1.7.12 running under Linux:

Mozilla/5.0 (X11; U; Linux i686; de-AT; rv:1.7.12) Gecko/20050923

Using Javascript syntax to specify more than just the agent

This is a new feature which came with PrefBar 3.3. You may now specify each of the following using Javascript: useragent, appname, appversion and platform. This will allow you to pass even more browser selection scripts.

To tell PrefBar you like to use Javascript you have to prefix your value with "js:". For example this would be the string you enter to spoof Internet Explorer on Windows XP:

js:useragent="Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)"; appname="Microsoft Internet Explorer"; appversion="4.0 (compatible; MSIE 6.0; Windows NT 5.1)"; platform="Win32";

Proxy Serverlist

A proxy server list won't help you if you wouldn't be allowed to enter your proxies here ;-) Feel free to add some in the following syntax:

$SERVER:$PORT

Starting with PrefBar 4.2, it's also possible to enter SOCKS proxies into the list, in the following form:

socks:$SERVER:$PORT

In both cases "$SERVER" is the server name or server IP and "$PORT" is the port number. You may mix FTP/HTTP and SOCKS proxies in your list, if you like.

Language list

Feel free to add, delete or move language identifiers, here.

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.

Hidden preferences

There are a few preferences that influence how PrefBar handles some things. Maybe there will be a GUI to edit them, in future, but in the meantime you'll have to use about:config to edit them.

extensions.prefbar.plugintoggle.mode

This one only works with Firefox 23 and above and allows you the following options for all plugin toggle checkboxes (like the builtin Java and Flash checkbox).
0
Toggle between "Never activate" and "Always activate" (default)
1
Toggle between "Never activate" and "Always ask"
2
Toggle between "Always ask" and "Always activate"