In my earlier post, I went over the basics of enabling an autoconfig file. In this post, I'm going to give more detail on what is in an autoconfig file, as well as how to debug autoconfig files. Before we get started, though, I need to provide some new information about offline autoconfig.
At the end of my last post, I mentioned two preferences, autoadmin.offline_failover and autoadmin.failover_to_cached. Around the same time, I started getting questions asking how to properly handle cases where the autoconfig file cannot be retrieved from a server. These two preferences are the key to that.
Every time an autoconfig file is retrieved remotely, a backup copy of that file is created in the user's profile directory called failover.jsc. If the preference autoadmin.failover_to_cached is set to false, Firefox reads the cached file and then marks the browser as offline and locks the preference so the user cannot go online. If the preference is set to true, it simply uses the cached file and then continues. The preference autoadmin.offline_failover controls whether or not the cached file is used when the user is simply offline. If it is set to true, the cached file is used.
So based on my reading of the prefs, I believe the best thing to do is to set autoadmin.failover_to_cached to true and to set autoadmin.offline_failover to true.
With that out of the way, let's talk about writing an autoconfig file. What I'd like to do in this post is go over each function available in the autoconfig file individually, and then we'll show a sample of an autoconfig. A quick note about using these functions - when they fail, they always display an error. So while you can use try/catch in your code, it won't prevent errors from these functions from showing up.
You will probably never use getPrefBranch. It is a convenience function used by the other functions.
pref(prefName, value) sets the user value of a preference. If you remember in our first post, I went over the difference between user prefs and default prefs. This function explicitly sets the preference as a user preference. That means that if the user has changed the value, it will get reset every time the browser is started.
defaultPref(prefName, value) sets the default value of a preference. This is the value that a preference has when the user has not set any value.
lockPref(prefName, value) sets the default value of a preference and locks it. This is the function that is most familiar to people when it comes to autoconfig files. Locking a preference prevents a user from changing it, and in most cases, disables the UI in preferences so it is obvious to the user that the preference has been disabled. In cases where you don't see things getting disabled in preference, there are some "disable_button" preferences that when locked, disable buttons. For example, if you lock the pref pref.privacy.disable_button.view_passwords it will disable the "View Passwords" button. You can see a lot of these preferences here. There are tons of examples on the web that show various locking of prefs. There's really no way to create an exhaustive list of all the preferences that can be locked.
unlockPref(prefName, value) unlocks a preference. As an example, there might be cases where you lock a preference for everyone and then unlock it for a particular user.
getPref(prefName) retrieves the value of a preference. As mentioned earlier, if the preference doesn't exist, it displays an error. You should only use this on preferences that you know exist.
clearPref(prefName) removes the user value of a preference, resetting it to its default value.
displayError(funcname, message) displays an error in a specific format.
Netscape.cfg/AutoConfig failed. Please contact your system administrator.
Error: [funcname] failed: [message]
While this can be handy for debugging, It's a very cryptic error. We'll go over better methods for displaying alerts in our next post.
getenv(name) allows you to query environment variables. This can allow you to do things like get things like usernames and other system information.
setLDAPVersion(version), getLDAPAttributes(host, base, filter, attribs) and getLDAPValue(str, key) are LDAP functions that are only available in Thunderbird. I don't know enough about these to do them justice, but there is a great post on A Brundage Web-log that covers them.
// First line pref("a", 1); lockPref("a.a", "2"); defaultPref("a.a.a", true);
If we take a look in about:config, here's what we see:
The first preference is in bold because it is user set, the second preference is locked, and the third preference has been set as a default.
So armed with this information, we can create a basic autoconfig file that locks preferences and more.
One note on debugging your autoconfig files - you should use try/catch blocks liberally. If there is a failure, you will just see the generic message:
Failed to read the configuration file. Please contact your system administrator.
By inserting try/catch and using displayError, you can see exactly what the error is.
I ran out of room in this post, so in our next post, we'll show some advanced techniques for autoconfig files including prompting, creating bookmarks and more.