Customizing Firefox – Autoconfig Files (Continued)

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.

So let’s create our a basic autoconfig file. First, remember that if you are writing the local autoconfig file, your code MUST begin on the second line. If your file is being retrieved remotely, this doesn’t matter. Second, remember that everything in the file is a Javascript function so it is case sensitive.

// 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.

Please note: I reserve the right to delete comments that are offensive or off-topic.

Leave a Reply

Your email address will not be published. Required fields are marked *

14 thoughts on “Customizing Firefox – Autoconfig Files (Continued)

  1. It’d be really awesome if user.js could make use of some of these same features, to check some things locally before setting preferences. For instance, I’d like to retrieve the value of $HOME so I can set some preferences with paths in them.

  2. Hi Mike,

    I have not been working with firefox or thunderbird long but your pages are the best source of info on the web that I’ve found.

    Really like the recent Firefox homepage post.

    I was wondering if you could help me or point me in the right direction with a problem I’m having with defaultPref() in Thunderbird.

    I call a config file from all.js in the usual way and set a number of defaultPref() settings and a couple of lockPref() settings. The cfg is wrapped in a try and catch.

    However what I’m finding is that I’ve set –

    defaultPref(“mailnews.mark_message_read.delay”, true);

    which puts a 5 second delay in marking messages as read. Looking in config editor it is set correctly a default setting. However if a user changes that setting it only persists for that session. I can see the change in config editor to user set and I can see that the setting is written to the prefs.js file in the users profile. However when a user restarts Thunderbird it reverts back to the defaultPref() setting.

    What is the best way of diagnosing these kind of problems? Is there a general problem with defaultPref() in Thunderbird or is the problem due to this one setting? and how would I best go about determining that? I know that defaultPref() works in FireFox as I use it for my default homepage.

    From what I can tell Prefs.js in the user profile should be the last file that is applied and should overwrite setting made in earlier preference files, is this the case?

    Thanks in advance for any help you can offer.

  3. Hi, The unlockPref capability is something I need. Back around FF3.6 a preference was locked for plugin.disable_full_page_plugin_for_types: application/pdf, to keep PDFs from opening within the browser. I am now rolling out 24.1 and that locked setting causes problems changing PDF Actions under the Applications tab, in that they immediate revert to displaying Use Adobe Acrobat (in Firefox) instead of the Use Adobe Reader (default). The lock was created using CCK Wizard. I can’t quite master how to unlock this preference when upgrading a system with the lock in place to 24. Any help is greatly appreciated.

    • Preference locks don’t persist across restarts of Firefox (at least they shouldn’t).

      If you simply don’t lock it in a new CCK, it shouldn’t locked.

      • I did create a new CCK with the pref unlocked and for new Firefox profiles it does exactly that – no locks. But when the same customization is used as an upgrade and the user already has a profile, the pref stays locked with the old value. I’ve found that if I remove that user’s existing frefox-cck.js file from under their profile (in the extensions subfolder), that user will pick up the new values, but the pref is still locked. Is there a way to permanently remove the lock on this pref for all users? I could remove the users’ Firefox profile and see if it comes up unlocked, but I’d probably have to go into the Packagers Protection Program under a new identity.

        Many thanks for all the knowledge shared.

          • Hmmm. I got the sense that the lock retention was happening at the user side. I’ve even uninstalled Firefox completely from the system, cleaned out any files and registry entries left behind, leaving only the users profile. Did a clean new install with the new CCK for 24.1.1 and the existing users about:config still shows that pref as locked. The older CCK used 1.3. This new one is using CCK 1.4, though I’m not sure that would matter.

  4. This info is great Mike have done some changes for Firefox and they worked out great. One thing I am trying to do is make a specific web page come up on a computer that allot of kids use. Of course I can change the homepage after a student logs on but we are talking about a few hundred logons. Would like it so no matter who logs on that firefox opens the same page. The site we use has to us firefox or I would do explorer and group policy. Can this be done?