mozilla

Compare Revisions

A brief guide to Mozilla preferences

Change Revisions

Revision 439883:

Revision 439883 by kotarofuma on

Revision 441919:

Revision 441919 by BenjaminSmedberg on

Title:
A brief guide to Mozilla preferences
A brief guide to Mozilla preferences
Slug:
Mozilla/Preferences/A_brief_guide_to_Mozilla_preferences
Mozilla/Preferences/A_brief_guide_to_Mozilla_preferences
Tags:
XULRunner, NeedsTechnicalReview, NeedsUpdate, NeedsMarkupWork, Preferences,
"Preferences"
Content:

Revision 439883
Revision 441919
n10      </p>n
11      <p>
12        Feedback and comments to bug <a class="external" href="ht
>tp://bugzilla.mozilla.org/show_bug.cgi?id=158384">158384</a>. 
n38          <span id="files-def">Default <abbr title="preferences">n35          <span id="files-def">Default <abbr title="preferences">
>pref.</abbr> files</span>>preference</abbr> files</span>
n42            In the <code>defaults/pref/</code> directory of the an39            Firefox ships default preferences in several files, a
>pplication installation directory are <span class="term">default >ll in the application directory:
>preferences files</span> with the <code>.js</code> file extension 
>. When the application launches, these files initialize preferenc 
>es with default values. 
n44          <p>n41          <ul>
45            <span id="files-def-special">The directory contains a42            <li>greprefs.js - preferences shared by all applicati
> platform-specific</span> <span class="term">default pref files</>ons using the Mozilla platform
>span>, whose file name depends on the platform: 
46          </p>
47          <div class="note">
48            <p>
49              Unix-like systems used to contain a pref. file call
>ed <code>unix.js</code>. This file has been replaced with <code>c 
>hannel-prefs.js</code> and <code>vendor-gre.js</code>. 
50            </p>43            </li>
44            <li>defaults/pref/services-common.js - preferences fo
 >r some shared services code, this should arguably be included in 
 >some other file
51          </div>45            </li>
52          <table class="table">46            <li>defaults/pref/services-sync.js - default preferen
 >ces for Firefox sync, also oddly misplaced
53            <thead>
54              <tr>
55                <th>
56                  Platform
57                </th>
58                <th>
59                  File name
60                </th>
61              </tr>47            </li>
62            </thead>48            <li>defaults/pref/channel-prefs.js - a file indicatin
 >g the user's update channel. This is kept separate from other pre
 >ferences because it can affect how updates are applied.
63            <tbody>
64              <tr>
65                <td>
66                  Windows
67                </td>
68                <td>
69                  <code>winpref.js</code>
70                </td>
71              </tr>49            </li>
72              <tr>50            <li>browser/defaults/preferences/firefox.js - default
 >s specific to Firefox
73                <td>
74                  Mac OS &amp; Mac OS X
75                </td>
76                <td>
77                  <code>macprefs.js</code>
78                </td>
79              </tr>51            </li>
80              <tr>52            <li>browser/defaults/preferences/firefox-branding.js 
 >- defaults specific to the specific kind of Firefox being install
 >ed (Nightly, Aurora, Beta, Release)
81                <td>
82                  Unix
83                </td>
84                <td>
85                  <code>channel-prefs.js, vendor-gre.js</code>
86                </td>
87              </tr>53            </li>
88              <tr>54            <li>browser/defaults/preferences/firefox-l10n.js - de
 >faults specific to the installed language of Firefox. None of the
 > other preference files contain locale-specific preferences.
89                <td>
90                  Open VMS
91                </td>
92                <td>
93                  <code>openvms.js</code>
94                </td>
95              </tr>55            </li>
96              <tr>
97                <td>
98                  AIX
99                </td>
100                <td>
101                  <code>aix.js</code>
102                </td>
103              </tr>
104              <tr>
105                <td>
106                  OS/2
107                </td>
108                <td>
109                  <code>os2pref.js</code>
110                </td>
111              </tr>
112              <tr>
113                <td>
114                  BeOS
115                </td>
116                <td>
117                  <code>beos.js</code>
118                </td>
119              </tr>
120              <tr>
121                <td>
122                  Photon toolkit build
123                </td>
124                <td>
125                  <code>photon.js</code>
126                </td>
127              </tr>
128            </tbody>
129          </table>56          </ul>
n146          <p>n
147            Netscape 7 has a third <span class="term">user pref f
>ile</span> -<code>liprefs.js</code>, the roaming access preferenc 
>es file. 
148          </p>
n162            Load all <span class="term">default pref files</span>n86            Load all <span class="term">default pref files</span>
>. Non-<a href="#files-def-special">platform-specific</a> <code>.j>.
>s</code> files are loaded first, in reverse case-sensitive alphab 
>etical order. Then the platform-specific file is loaded. 
n191        <strong>Do NOT</strong> edit <code>prefs.js</code> directn115        <strong>Do NOT</strong> edit <code>prefs.js</code> direct
>ly, unless you really know what you are doing, because the file h>ly.
>as a variety of editing restrictions and complicated behaviors, w 
>hich are beyond the scope of this document. 
192      </p>
193      <p>
194        If, for some reason, you ignore this warning and decide t
>o edit <code>prefs.js</code>, save a copy before you make changes 
>. Because <code>prefs.js</code> is overwritten at application exi 
>t, you must edit the file while the application is closed. 
n200        By default, <code>prefs.js</code> is <q>compressed</q>. Wn121        When <code>prefs.js</code> is written, it only saves user
>hen saving each preference, the application compares its value ag> preferences which are different from the default.
>ainst the default loaded from <span class="term">default pref fil 
>es</span> and drop the preference from <code>prefs.js</code> if t 
>hey match. 
n208        You can set user preferences via the advanced preferencesn129        Advanced users can set named preferences via the advanced
> editor, by typing <code>about:config</code> in the Location Bar.> preferences editor, by typing <code>about:config</code> in the L
> This interface modifies the same file as the Preferences UI, <co>ocation Bar. This UI is not recommended for most users. Programma
>de>prefs.js</code>. Normal application users should always use th>tic changes to preferences can be made using the <a href="http://
>is interface to modify their Preferences.>dxr.mozilla.org/mozilla-central/source/toolkit/modules/Preference
 >s.jsm" title="http://dxr.mozilla.org/mozilla-central/source/toolk
 >it/modules/Preferences.jsm">Preferences.jsm</a> module from JS co
 >de, or the mozilla::Preferences static class methods from C++ cod
 >e.
n210      <div class="geckoVersionNote" style="undefined">n
211        <p>
212          {{ gecko_callout_heading("8.0") }}
213        </p>
214        <p>
215          You can optionally include a filter query in your about
>:config URI when you type it, to filter which preferences you see 
>. For example, "about:config?filter=sessionstore" will show only  
>session storage related preferences. 
216        </p>
217      </div>
218      <p>
219        If you intend to edit preferences files manually, make su
>re you understand preference loading and saving as described in p 
>revious sections. 
220      </p>
221      <p class="note">
222        <strong>Do NOT</strong> edit <code>prefs.js</code> direct
>ly, unless you really know what you are doing, because the file h 
>as a variety of editing restrictions and complicated behaviors, w 
>hich are beyond the scope of this document. 
223      </p>
224      <p>
225        If, for some reason, you ignore this warning and decide t
>o edit <code>prefs.js</code>, save a copy before you make changes 
>. Because <code>prefs.js</code> is overwritten at application exi 
>t, you must edit the file while the application is closed. 
226      </p>
227      <p>
228        If you want to manually change preference values for a gi
>ven profile, you should do so by creating <code>user.js</code> in 
> your profile directory. As previously noted, all values set in < 
>code>user.js</code> take effect at program launch irrespective of 
> changes from previous session. The file is a simple text file th 
>at looks like this: 
229      </p>
230      <pre class="codeExample">
231user_pref("mail.server.default.abbreviate",true); <span class="cC
>mt">// no newsgroup abbreviation</span> 
232 
233<span class="cCmt">// use Google instead of Netscape for search</
>span> 
234user_pref("browser.search.defaulturl","http://www.google.com/");
235</pre>
236      <p>
237        For your <code>user.js</code> to take effect, you must fi
>rst restart your application. 
238      </p>
239      <div class="note">
240        <strong>Note:</strong> Preference names are case-sensitiv
>e. 
241      </div>
n249        <li>n138        <li>The administrator may add an <code>all-<em>companynam
 >e</em>.js</code> preference file (<code>install_directory/browser
 >/defaults/preferences/all-<em>companyname</em>.js</code>).&nbsp; 
 >This will be parsed last during the preference loading process.
250          <p>
251            The administrator may edit the <code>all.js</code><su
>p>†</sup> <span class="term">default pref file</span> (<code>inst 
>all_directory/defaults/prefs/all.js</code>). This has the advanta 
>ge of changing the default value for both new and existing profil 
>es. However, note preferences set in the profile will override th 
>e default settings. Also, note due to preferences file <a href="# 
>compression">compression</a>, some preferences are not saved if t 
>hey match the default values, causing the profile to behave diffe 
>rently if used in a different installation. 
252          </p>
253          <p>
254            <sup>†</sup> Because <span class="term">default pref 
>files</span> are loaded in reverse alphabetical order, <code>all. 
>js</code> will be loaded near the end, preventing administrator v 
>alues from being overridden.&nbsp; <code>all.js</code> is no long 
>er installed by Firefox, if you create it, it will be <a class="l 
>ink-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=690 
>370" title="https://bugzilla.mozilla.org/show_bug.cgi?id=690370"> 
>deleted</a> by the next app update, so use a different name. 
255          </p>
n259            The administrator may add an <code>all-<em>companynamn
>e</em>.js</code> preference file (<code>install_directory/default 
>s/prefs/all-<em>companyname</em>.js</code>).&nbsp; This will be p 
>arsed last during the preference loading process. 
260          </p>
261        </li>
262        <li>
263          <p>
264            The administrator may alternatively put a <code>user.142            The administrator may alternatively put a <code>user.
>js</code> file in <code><em>app_dir</em>/defaults/profile/</code>>js</code> file in <code><em>app_dir</em>/defaults/profile/</code>
> ; this will put a copy of the <code>user.js</code> in all new pr> ; this will put a copy of the <code>user.js</code> in all new pr
>ofiles. This method has the advantage of resetting preferences ba>ofiles. This method has the advantage of resetting preferences ba
>ck to administrator defaults at every start-up. Note that, becaus>ck to administrator defaults at every start-up. Note that, becaus
>e a user typically has access privilege to his or her profile dir>e a user typically has access privilege to his or her profile dir
>ectory, he or she can change the default values if he or she know>ectory, he or she can change the default values if he or she know
>s how. Another disadvantage is that existing profiles will not be>s how. Another disadvantage is that existing profiles will not be
> affected.> affected. <em>This method is considered user-hostile. Any use of
 > this technique by software such as Firefox extension to override
 > normal user preference will result in being added to the Firefox
 > blocklist or the preferences being forcibly removed.</em>
tt146      <div class="note">
268      <p>147        <p>
269        Distributors can add default preference files via .XPI pa148          Note: because of abuse of user.js preferences, support 
>ckages. The following is sample <code>install.js</code> code:>for user.js may be removed in a future version of Firefox.
270      </p>149        </p>
271      <pre class="codeExample">150      </div>
272initInstall("CustomPref", "/foo/custompref", "1.0");
273addFile("custompref",           <span class="cCmt">// displayName
> from contents.rdf</span> 
274        "custompref.js",        <span class="cCmt">// source</spa
>n> 
275        getFolder("Defaults"),  <span class="cCmt">// target fold
>er</span> 
276 
277        "pref");                <span class="cCmt">// target subd
>ir</span> 
278 
279if (0 == getLastError())
280         performInstall();
281else
282         cancelInstall();
283</pre>

Back to History