Using content preferences

  • Revision slug: Using_content_preferences
  • Revision title: Using content preferences
  • Revision id: 71933
  • Created:
  • Creator: arenevier
  • Is current revision? No
  • Comment 82 words added

Revision Content

{{ Fx_minversion_header("3") }} Firefox 3 introduces the concept of content preferences. This permits code running within chrome (in other words: extensions and the browser itself, not web sites) to locally save preferences on a per-site basis. This makes it possible to write an extension that lets the user customize the appearance of specific web sites (setting the font size larger on sites that use obnoxiously small fonts, for instance).

The content preferences service, implemented by {{ Interface("nsIContentPrefService") }}, offers functions for setting and retrieving preferences for specific sites or in the global preference space; global preferences are used whenever a site-specific preference isn't available.

Site-specific content preferences are stored in the profile folder, in the database file "content-prefs.sqlite".

Example: Setting and retrieving preferences

This example demonstrates how to save a preference and then retrieve its value.

var ioSvc = Components.classes["@mozilla.org/network/io-service;1"]
            .getService(Components.interfaces.nsIIOService);
var prefService = Components.classes["@mozilla.org/content-pref/service;1"]
                  .getService(Components.interfaces.nsIContentPrefService);

// Create a URI object referencing the site to save a preference for
var uri = ioSvc.newURI("http://developer.mozilla.org/", null, null);

// Set the value of the "devmo.somesetting" preference to "foo".

prefService.setPref(uri, "devmo.somesetting", "foo");

...

// Retrieve the value of the "devmo.somesetting" preference.

var value = prefService.getPref(uri, "devmo.somesetting");

Built-in site-specific preferences

Preference Name Menu Equivalent Values Notes

browser.content.full-zoom
{{ fx_minversion_inline("3") }}

View / Zoom Example: "1.10000002384186"
(Rounding variant of "1.1")
Related about:config preferences:
  • browser.zoom.full
    Boolean, set by the menu item
    View / Zoom / Zoom Text Only.
    Despite the confusion in names, this preference is not site-specific.
  • browser.zoom.siteSpecific
  • toolkit.zoomManager.zoomValues
  • zoom.maxPercent and zoom.minPercent

browser.download.lastDir
{{ fx_minversion_inline("7") }}

  Path of a filesystem directory Related about:config preferences:
  • browser.download.lastDir
    The last directory for any site

Use DownloadLastDir.jsm for access to these preferences.

browser.upload.lastDir
{{ fx_minversion_inline("4") }}
  Path of a filesystem directory This preference is stored and retrieved automatically by file upload controls.

See also

  • {{ Interface("nsIContentPrefService") }}
  • {{ Interface("nsIContentPrefObserver") }}
  • toSource() (potentially useful for serializing objects for later use with eval())

 

{{ h1_gecko_minversion("Private browsing", "9.0") }}

In pre firefox 9.0, content preference service always stores preferences on disk. So, in private mode browsing, users of the service must take care not to call content pref service, and either store informations in memory, or not use preferences. Since Firefox 9.0, when in private mode, content preferences service will store preferences in memory only, and forget them when leaving private mode.

{{ languages( { "es": "es/Usar_las_preferencias_de_contenido", "fr": "fr/Utilisation_des_pr\u00e9f\u00e9rences_de_contenu", "ja": "ja/Using_content_preferences" } ) }}

Revision Source

<p>{{ Fx_minversion_header("3") }} Firefox 3 introduces the concept of content preferences. This permits code running within chrome (in other words: extensions and the browser itself, not web sites) to locally save preferences on a per-site basis. This makes it possible to write an extension that lets the user customize the appearance of specific web sites (setting the font size larger on sites that use obnoxiously small fonts, for instance).</p>
<p>The content preferences service, implemented by {{ Interface("nsIContentPrefService") }}, offers functions for setting and retrieving preferences for specific sites or in the global preference space; global preferences are used whenever a site-specific preference isn't available.</p>
<p>Site-specific content preferences are stored in the profile folder, in the database file "content-prefs.sqlite".</p>
<h3 name="Example:_Setting_and_retrieving_preferences">Example: Setting and retrieving preferences</h3>
<p>This example demonstrates how to save a preference and then retrieve its value.</p>
<pre class="eval">var ioSvc = Components.classes["@mozilla.org/network/io-service;1"]
            .getService(Components.interfaces.nsIIOService);
var prefService = Components.classes["@mozilla.org/content-pref/service;1"]
                  .getService(Components.interfaces.nsIContentPrefService);

// Create a URI object referencing the site to save a preference for
var uri = ioSvc.newURI("<span class="nowiki">http://developer.mozilla.org/</span>", null, null);

// Set the value of the "devmo.somesetting" preference to "foo".

prefService.setPref(uri, "devmo.somesetting", "foo");

...

// Retrieve the value of the "devmo.somesetting" preference.

var value = prefService.getPref(uri, "devmo.somesetting");
</pre>
<h3>Built-in site-specific preferences</h3>
<table class="standard-table"> <tbody> <tr> <td class="header">Preference Name</td> <td class="header">Menu Equivalent</td> <td class="header">Values</td> <td class="header">Notes</td> </tr> <tr> <td> <p><code>browser.content.full-zoom</code><br> {{ fx_minversion_inline("3") }}</p> </td> <td>View / Zoom</td> <td><em>Example:</em> "1.10000002384186"<br> (Rounding variant of "1.1")</td> <td>Related about:config preferences: <ul> <li><code>browser.zoom.full</code><br> Boolean, set by the menu item<br> View / Zoom / Zoom Text Only.<br> Despite the confusion in names, this preference is not site-specific.</li> <li><code>browser.zoom.siteSpecific</code></li> <li><code>toolkit.zoomManager.zoomValues</code></li> <li> <p><code>zoom.maxPercent and </code><code>zoom.minPercent</code></p> </li> </ul> </td> </tr> <tr> <td> <p><code>browser.download.lastDir</code><br> {{ fx_minversion_inline("7") }}</p> </td> <td> </td> <td>Path of a filesystem directory</td> <td>Related about:config preferences: <ul> <li><code>browser.download.lastDir</code><br> The last directory for any site</li> </ul> <p>Use <a href="/en/JavaScript_code_modules/DownloadLastDir.jsm" title="https://developer.mozilla.org/en/JavaScript/Code_modules/DownloadLastDir.jsm">DownloadLastDir.jsm</a> for access to these preferences.</p> </td> </tr> <tr> <td><code>browser.upload.lastDir</code><br> {{ fx_minversion_inline("4") }}</td> <td> </td> <td>Path of a filesystem directory</td> <td>This preference is stored and retrieved automatically by file upload controls.</td> </tr> </tbody>
</table>
<h3 name="See_also">See also</h3>
<ul> <li>{{ Interface("nsIContentPrefService") }}</li> <li>{{ Interface("nsIContentPrefObserver") }}</li> <li><a href="/en/JavaScript/Reference/Global_Objects/Object/toSource" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Object/toSource">toSource()</a> (potentially useful for serializing objects for later use with <a href="/en/Core_JavaScript_1.5_Reference/Functions/eval" title="en/Core_JavaScript_1.5_Reference/Functions/eval">eval()</a>)</li>
</ul>
<p> </p>
<p id="private-browsing">{{ h1_gecko_minversion("Private browsing", "9.0") }}</p>
<p>In pre firefox 9.0, content preference service always stores preferences on disk. So, in private mode browsing, users of the service must take care not to call content pref service, and either store informations in memory, or not use preferences. Since Firefox 9.0, when in private mode, content preferences service will store preferences in memory only, and forget them when leaving private mode.</p>
<p>{{ languages( { "es": "es/Usar_las_preferencias_de_contenido", "fr": "fr/Utilisation_des_pr\u00e9f\u00e9rences_de_contenu", "ja": "ja/Using_content_preferences" } ) }}</p>
Revert to this revision