Compare Revisions

Preferences

Change Revisions

Revision 628819:

Revision 628819 by Masayuki on

Revision 628975:

Revision 628975 by BenjaminSmedberg on

Title:
Preferences
Preferences
Slug:
Mozilla/Developer_guide/Preferences
Mozilla/Developer_guide/Preferences
Content:

Revision 628819
Revision 628975
n39      Preferences which enables or disables a feature, the item nn39      Preferences which enables or disables a feature, the item n
>ame should be <code>"enabled"</code> and the type should be <code>ame should be <code>"enabled"</code> and the type should be <code
>>boolean</code>. Don't define a preferences as <code>"&lt;root&gt>>boolean</code>. Don't define a preferences as <code>"&lt;root&gt
>;.&lt;feature-name&gt;"</code> for the purpose since when somebod>;.&lt;feature-name&gt;"</code> for the purpose since when somebod
>y adds preferences for the feature, <code>".enabled"</code> is mo>y adds preferences for the feature, <code>".enabled"</code> is mo
>re explicit and consistent name with new preferences. If an <code>re explicit and consistent name with new preferences. If an <code
>>"enabled"</code> pref does not always enable or disable the feat>>"enabled"</code> pref does not always enable or disable the feat
>ure, you may need to add another pref which enables or disables t>ure, you may need to add another pref which enables or disables t
>he feature forcibly (i.e., ignoring the condition). The pref name>he feature forcibly (i.e., ignoring the condition). The pref name
> should be <code>"force_disable"</code> or <code>"fore_enable"</c> should be <code>"force_disable"</code> or <code>"force_enable"</
>ode>.>code>.
n41    <h3 id="Root_namespaces">n41    <h2>
42      Root namespaces42      When to use Preferences
43    </h3>43    </h2>
n45      In general, you should <strong>not</strong> add new root nan45      Prefs may/should be used in the following situations:
>mespace for a feature except you're adding a new modules or a lot 
> of preferences for a single feature. Following names are used as 
> root namespace of preferences: 
n47    <dl>n47    <ul>
48      <dt>48      <li>To store a user-visible preference setting. Preferences
 > of this type require UX review.
49        accessibility
50      </dt>49      </li>
51      <dd>50      <li>To enable release drivers to turn a feature off easily 
 >if there is a problem found during the release process. Once a fe
 >ature has shipped, this preference type should probably be remove
 >d.
52        Used by a11y module.
53      </dd>51      </li>
54      <dt>52      <li>To control features which are experimental or not ready
 > to ship to our release users. Per-channel defaults control which
 > experimental features are enabled for each prerelease population
 >.
55        app
56      </dt>53      </li>
57      <dd>54      <li>Other internal usage: for example to facilitate A/B tes
 >ting via telemetry experiments, or to control automated test beha
 >vior. In these cases consider whether it would be better to use a
 > runtime setting instead of a persistent preference to control th
 >e behavior.
58        Used for managing application wide settings. E.g., softwa
>re updater. 
59      </dd>55      </li>
60      <dt>
61        apz
62      </dt>
63      <dd>
64        Used for customizing the behavior of Async-Pan/Zoom.
65      </dd>
66      <dt>
67        bidi
68      </dt>
69      <dd>
70        Used for customizing the behavior of bidirection text nav
>igation and edit. This should've been a sub group of <code>"acces 
>sibility"</code>, <code>"intl"</code> or <code>"ui"</code>. 
71      </dd>
72      <dt>
73        browser
74      </dt>
75      <dd>
76        Used for customizing the behavior of browser UI or storin
>g some information (e.g., the last check time of something) 
77      </dd>
78      <dt>
79        camera
80      </dt>
81      <dd>
82        Used for enabling or disabling features of camera device.
> This should've been a sub group of <code>"device"</code>. 
83      </dd>
84      <dt>
85        canvas
86      </dt>
87      <dd>
88        Used for enabling or disabling features of HTML canvas el
>ement. This should've been a sub group of <code>"dom"</code>. 
89      </dd>
90      <dt>
91        capability
92      </dt>
93      <dd>
94        Used for controling privilege.
95      </dd>
96      <dt>
97        clipboard
98      </dt>
99      <dd>
100        Used for enabling or disabling features about clipboard. 
>This should've been a sub group of <code>"ui"</code>. 
101      </dd>
102      <dt>
103        datareporting
104      </dt>
105      <dd>
106        Used for data reporting (e.g., health report) module.
107      </dd>
108      <dt>
109        device
110      </dt>
111      <dd>
112        Used for enabling or disabling support of some devices.
113      </dd>
114      <dt>
115        devtools
116      </dt>
117      <dd>
118        Used for customizing the behavior of developer tools.
119      </dd>
120      <dt>
121        dom
122      </dt>
123      <dd>
124        Used for enabling or disabling DOM features.
125      </dd>
126      <dt>
127        editor
128      </dt>
129      <dd>
130        Used for customizing the behavior of plaintext or HTML ed
>itor. 
131      </dd>
132      <dt>
133        experiments
134      </dt>
135      <dd>
136        ?
137      </dd>
138      <dt>
139        extensions
140      </dt>
141      <dd>
142        All extenstions (add-ons) should store their settings und
>er this with a sub group named with its name. 
143      </dd>
144      <dt>
145        focusmanager
146      </dt>
147      <dd>
148        Used by automated tests for nsFocusManager. (This should 
>not have been added to {{Source("modules/libpref/src/init/all.js" 
>)}}) 
149      </dd>
150      <dt>
151        font
152      </dt>
153      <dd>
154        Stores some font information. E.g., blacklist of well kno
>wn fonts which have bad font metrics, default fonts and sizes for 
> each language. 
155      </dd>
156      <dt>
157        gecko
158      </dt>
159      <dd>
160        Stores some information of Gecko.
161      </dd>
162      <dt>
163        general
164      </dt>
165      <dd>
166        Stores various information or customizing some features. 
>These prefs should've been a sub group of other root namespaces. 
167      </dd>
168      <dt>
169        geo
170      </dt>
171      <dd>
172        Used for customizing a feature of geo location. This shou
>ld've been a sub group of <code>"device"</code> or <code>"dom"</c 
>ode>. 
173      </dd>
174      <dt>
175        gestures
176      </dt>
177      <dd>
178        Used for enabling a feature of gesture input. This should
>'ve been a sub group of <code>"ui"</code>. 
179      </dd>
180      <dt>
181        gfx
182      </dt>
183      <dd>
184        Used for customizng the behavior of gfx module which is r
>endering everything. 
185      </dd>
186      <dt>
187        gl
188      </dt>
189      <dd>
190        Used for customizng the behavior of WebGL? Perhaps, this 
>should've been a sub group of <code>"gfx"</code>. 
191      </dd>
192      <dt>
193        hangmonitor
194      </dt>
195      <dd>
196        Used for customizing the behavior of hang up monitor. Thi
>s should've been a sub group of <code>"app"</code> or <code>"geck 
>o"</code>. 
197      </dd>
198      <dt>
199        html5
200      </dt>
201      <dd>
202        Used for customizing the behavior of HTML5 module.
203      </dd>
204      <dt>
205        identify
206      </dt>
207      <dd>
208        Used for storing some information about Firefox Account.
209      </dd>
210      <dt>
211        idle
212      </dt>
213      <dd>
214        Used for stroing information of <code>nsIdleService</code
>>. This should've been a sub group of <code>"app"</code> or <code 
>>"gecko"</code>. 
215      </dd>
216      <dt>
217        image
218      </dt>
219      <dd>
220        Used for customizing the behavior of image module of gfx.
221      </dd>
222      <dt>
223        intl
224      </dt>
225      <dd>
226        Used for customizing the behavior of features for interna
>tionalization. E.g., language dpendent settings, IME settings. 
227      </dd>
228      <dt>
229        javascript
230      </dt>
231      <dd>
232        Used for customizing the behavior of Javascript engine.
233      </dd>
234      <dt>
235        jsloader
236      </dt>
237      <dd>
238        Used for customizing the behavior of JS compartment. This
> should've been a sub group of <code>"javascript"</code>. 
239      </dd>
240      <dt>
241        keyword
242      </dt>
243      <dd>
244        Used for enabling or disabling the keyword feature in URL
> bar. This should've been a sub group of <code>"browser"</code>. 
245      </dd>
246      <dt>
247        layers
248      </dt>
249      <dd>
250        Used for customizing the behavior of gfx layers.
251      </dd>
252      <dt>
253        layout
254      </dt>
255      <dd>
256        Used for customizing the behavior and enabling or disabli
>ng some features of layout module. 
257      </dd>
258      <dt>
259        lightweightThemes
260      </dt>
261      <dd>
262        Used by light weight theme.
263      </dd>
264      <dt>
265        loop
266      </dt>
267      <dd>
268        Used for loop server service. This should've been a sub g
>roup of <code>"services"</code>. 
269      </dd>
270      <dt>
271        media
272      </dt>
273      <dd>
274        Used by media module. This customizes the behavior and en
>ables or disables features of video or audio. 
275      </dd>
276      <dt>
277        memory
278      </dt>
279      <dd>
280        Used for customizng the behavior of memory manager.
281      </dd>
282      <dt>
283        memory_info_dumper
284      </dt>
285      <dd>
286        This should've been a sub group of <code>"memory"</code>.
287      </dd>
288      <dt>
289        middlemouse
290      </dt>
291      <dd>
292        Used for customizing the behavior of middle button click 
>of mice. This should've been a sub group of <code>"mouse"</code>  
>or <code>"ui"</code>. 
293      </dd>
294      <dt>
295        mms
296      </dt>
297      <dd>
298        Used by mobile message service module. This should've bee
>n a sub group of "services". 
299      </dd>
300      <dt>
301        mousewheel
302      </dt>
303      <dd>
304        Used for customizing the behavior of mouse wheel. This sh
>ould've been a sub group of <code>"mouse"</code> or <code>"ui"</c 
>ode>. 
305      </dd>
306      <dt>
307        network
308      </dt>
309      <dd>
310        Used by network module.
311      </dd>
312      <dt>
313        nglayout
314      </dt>
315      <dd>
316        Used by layout module. <a href="http://www-archive.mozill
>a.org/newlayout/gecko.html">NGLayout is a legacy project name</a> 
>. 
317      </dd>
318      <dt>
319        notification
320      </dt>
321      <dd>
322        Used for enabling or disabling desktop notification. This
> should've been a sub group of <code>"dom"</code> or <code>"ui"</ 
>code>. 
323      </dd>
324      <dt>
325        offline-apps
326      </dt>
327      <dd>
328        Used for customozing offline application behavior. This s
>hould've been a sub group of <code>"broser"</code>, <code>"dom"</ 
>code> or <code>"network"</code>. 
329      </dd>
330      <dt>
331        pdfjs
332      </dt>
333      <dd>
334        Used by PDF.js.
335      </dd>
336      <dt>
337        permissions
338      </dt>
339      <dd>
340        Used for customizing if allow to load image. This should'
>ve been <code>"dom"</code>, <code>"image"</code> or <code>"networ 
>k"</code>. 
341      </dd>
342      <dt>
343        pfs
344      </dt>
345      <dd>
346        Used by plugin finder service. This should've been a sub 
>group of <code>"services"</code>. 
347      </dd>
348      <dt>
349        places
350      </dt>
351      <dd>
352        Used by places (bookmarks and history).
353      </dd>
354      <dt>
355        plain_text
356      </dt>
357      <dd>
358        Used by layout. This should've been a sub group of <code>
>"layout"</code>. 
359      </dd>
360      <dt>
361        plugin
362      </dt>
363      <dd>
364        Used for customizing the behavior of plugin module.
365      </dd>
366      <dt>
367        plugins
368      </dt>
369      <dd>
370        Used for customizng the behavior of plugin management. Th
>is should've been "plugin". 
371      </dd>
372      <dt>
373        pref
374      </dt>
375      <dd>
376        Used by preferences UI.
377      </dd>
378      <dt>
379        prefs
380      </dt>
381      <dd>
382        Not used? And this should've been <code>"pref"</code>.
383      </dd>
384      <dt>
385        print
386      </dt>
387      <dd>
388        Used for storing printer settings.
389      </dd>
390      <dt>
391        privacy
392      </dt>
393      <dd>
394        Used for customizing the behavior which related to privac
>y data. 
395      </dd>
396      <dt>
397        profile
398      </dt>
399      <dd>
400        Not used?
401      </dd>
402      <dt>
403        profiler
404      </dt>
405      <dd>
406        Not used?
407      </dd>
408      <dt>
409        prompts
410      </dt>
411      <dd>
412        Used for enabling or disabling tab-modal prompt. This sho
>uld've been a sub group of <code>"ui"</code>. 
413      </dd>
414      <dt>
415        ril
416      </dt>
417      <dd>
418        ?
419      </dd>
420      <dt>
421        security
422      </dt>
423      <dd>
424        Used for customizng secury related settings.
425      </dd>
426      <dt>
427        selectioncaret
428      </dt>
429      <dd>
430        Used for enabling or disabling to show selection carets w
>hich is used for selecting text on touch device. 
431      </dd>
432      <dt>
433        services
434      </dt>
435      <dd>
436        Used by various sevices. E.g., Firefox Sync.
437      </dd>
438      <dt>
439        shumway
440      </dt>
441      <dd>
442        Used by <a href="http://mozilla.github.io/shumway/">Shumw
>ay</a>. 
443      </dd>
444      <dt>
445        signed
446      </dt>
447      <dd>
448        ?
449      </dd>
450      <dt>
451        signon
452      </dt>
453      <dd>
454        Used for customizing the behavior of password manager.
455      </dd>
456      <dt>
457        slider
458      </dt>
459      <dd>
460        Used by XUL slider. This should've been a sub group of <c
>ode>"ui"</code>. 
461      </dd>
462      <dt>
463        snav
464      </dt>
465      <dd>
466        Used for enabling or disabling spatial navigation. This s
>hould've been a sub group of <code>"ui"</code>. 
467      </dd>
468      <dt>
469        social
470      </dt>
471      <dd>
472        Used by social API implementation.
473      </dd>
474      <dt>
475        spellchecker
476      </dt>
477      <dd>
478        Used by spellchecker. This should've been <code>"editor"<
>/code> or <code>"ui"</code>. 
479      </dd>
480      <dt>
481        stagefright
482      </dt>
483      <dd>
484        Used for enabling or disabling Stagefright on Android. Th
>is should've been <code>"media"</code>. 
485      </dd>
486      <dt>
487        storage
488      </dt>
489      <dd>
490        Used by storage implemtation for storing its state.
491      </dd>
492      <dt>
493        svg
494      </dt>
495      <dd>
496        Used for enabling or disabling the fetuares of SVG.
497      </dd>
498      <dt>
499        toolkit
500      </dt>
501      <dd>
502        Used for customizing the behavior of toolkit and enabling
> or disabling some features of toolkit. 
503      </dd>
504      <dt>
505        ui
506      </dt>
507      <dd>
508        Used for customizing various GUI behavior, look and feel.
509      </dd>
510      <dt>
511        urlclassifier
512      </dt>
513      <dd>
514        Used for customizing URL classifier of toolkit. This shou
>ld've been <code>"security"</code> or <code>"toolkit"</code>. 
515      </dd>
516      <dt>
517        view-source
518      </dt>
519      <dd>
520        Used for customizing the behavior of view-source window.
521      </dd>
522      <dt>
523        viewmanager
524      </dt>
525      <dd>
526        Not used?
527      </dd>
528      <dt>
529        wap
530      </dt>
531      <dd>
532        Used for customizing mobile message service's UA informat
>ion. This should've been a sub group of <code>"services"</code>. 
533      </dd>
534      <dt>
535        webgl
536      </dt>
537      <dd>
538        Used for customizing the behavior and enabling or disabli
>ng features of WebGL. 
539      </dd>
540      <dt>
541        xpinstall
542      </dt>
543      <dd>
544        Used by XPI impelemtation.
545      </dd>
546      <dt>
547        zoom
548      </dt>
549      <dd>
550        Used for customizing content zoom behavior. This should'v
>e been a sub group of <code>"ui"</code>. 
551      </dd>
552    </dl>56    </ul>
57    <p>
58      Preferences should <em>not</em> be used to expose features 
 >to power users via about:config settings. In order to make suppor
 >t better, it is far better for these users to install an addon to
 > change the default behavior, even if the addon simply changes a 
 >runtime flag. This allows us to see non-default settings in about
 >:support, Firefox Health Report, and crash-stats, and they are pr
 >operly disabled when running in Firefox safe mode.
59    </p>
n557      When you need to add a preference, it must be one of follown64      If a preference is used by core platform/Gecko code, a defa
>ing cases:>ult value should normally be added to {{Source("modules/libpref/s
 >rc/init/all.js")}}. This default is shared all Mozilla products s
 >uch as Firefox, Thunderbird, Firefox for Android and Firefox OS. 
 >If you need to set different initial value for specific product, 
 >you can use {{Source("browser/app/profile/firefox.js")}}, <a href
 >="http://mxr.mozilla.org/comm-central/source/mailnews/mailnews.js
 >">mailnews/mailnews.js</a>, {{Source("mobile/android/app/mobile.j
 >s")}} and/or {{Source("b2g/app/b2g.js")}}.
558    </p>
559    <ol>
560      <li>Needs a pref which should be customizable in preference
>s UI. 
561      </li>
562      <li>Needs a pref which should be only in <code>about:config
></code>. 
563      </li>
564      <li>Needs a pref which should be hidden from even <code>abo
>ut:config</code>. 
565      </li>
566      <li>Needs a pref which defines information of a feature (e.
>g., a URL for a service). 
567      </li>
568      <li>Needs a pref which stores some data.
569      </li>
570      <li>Needs a pref which is used only in automated tests.
571      </li>
572    </ol>
573    <p>
574      Only at #1, you need to ask review to UX team because we sh
>ouldn't make preferences UI messy and users break something easie 
>r. 
n577      At #1 or #2, you need to add initial value to {{Source("modn67      If a preference is used only by application-specific code, 
>ules/libpref/src/init/all.js")}}. The value is shared all Mozilla>the default should live in the relevant app-specific default file
> products such as Firefox, Thunderbird, Firefox for Android and F>.
>irefox OS. If you need to set different initial value for specifi 
>c product, you can use {{Source("browser/app/profile/firefox.js") 
>}}, <a href="http://mxr.mozilla.org/comm-central/source/mailnews/ 
>mailnews.js">mailnews/mailnews.js</a>, {{Source("mobile/android/a 
>pp/mobile.js")}} and/or {{Source("b2g/app/b2g.js")}}. 
578    </p>
579    <p>
580      Otherwise, you should just add a code of getting or setting
> a new preference. Then, you shouldn't add the preference to {{So 
>urce("modules/libpref/src/init/all.js")}} because showing such pr 
>eference in <code>about:config</code> makes users confused. 
t607      The other is to use string preference and using <code>atof(t94      The other is to use string preference and convert to float 
>)</code>.>using <code>parseFloat</code> (JavaScript) or <code>atof</code> (
 >C++).

Back to History