Using the PrefBar

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 toolbar
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 toolbar

To show the PrefBar 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 PrefBar is fairly straight forward. The buttons, currently on the PrefBar, are shown in the right tree, and the available buttons, not on the PrefBar, in the left tree. To add an existing button to the PrefBar, 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!
Framescript: The Framescript is, so far, only needed in very few situations and will be documented more in detail as soon as there is more need for it. In short this is the first step to make PrefBar compatible to Mozilla's attempt to run the content in tabs in separate processes. The "Framescript" is meant to run in this "content-process". There is only one Framescript, so you have to call it using "CallFrameScript" from the other event-functions. The name of the function, who called, is passed to the "Framescript" via the caller variable. The first argument to the "CallFrameScript" function is forwared to the Framescript via a variable named argument. You may use an array or object to pass more than one value. The second argument to "CallFrameScript" may be a callback function which is called as soon as your Framescript is finished. If you write something to the variable reply in your Framescript, then this value is passed to your callback. To make asynchronous stuff like this work in Get-functions, a function called "SetValue" is available, there. If you don't need to modify anything in the value, you may pass "SetValue" directly as second argument to "CallFrameScript".
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:

Things discussed in Built in buttons you may edit
The label property. This one isn't touched by the update process, so feel free to give each button a shorter name or just give it a name you like better
Of course everything that isn't built in such as self-created buttons or imported buttons

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

If you only want to set the width or the height of the window, you may leave out one of the values. For example, a value "1024x" will only set the width of the window.

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" entries of the context menu of the PrefBar Buttons customization 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 right click on the list and choose "Export". 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 by right clicking into one of the two lists and choosing "Import" in this menu. This opens a dialog where you may 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"