canmove, Confirmed users
2,056
edits
Labs/JS Modules: Difference between revisions
document new API methods and changes
(document new API methods and changes) |
|||
| Line 168: | Line 168: | ||
let foo = Preferences.get("extensions.test.foo"); | let foo = Preferences.get("extensions.test.foo"); | ||
Preferences.set("extensions.test.foo", | Preferences.set("extensions.test.foo", "some value"); | ||
As with [http://developer.mozilla.org/en/docs/FUEL:PreferenceBranch FUEL's preferences API], datatypes are auto-detected, and you can pass a default value that the API will return if the pref doesn't have a value: | As with [http://developer.mozilla.org/en/docs/FUEL:PreferenceBranch FUEL's preferences API], datatypes are auto-detected, and you can pass a default value that the API will return if the pref doesn't have a value: | ||
| Line 175: | Line 175: | ||
// foo == "default value" | // foo == "default value" | ||
Unlike FUEL, which returns null in the same situation, the module | Unlike FUEL, which returns null in the same situation, the module returns undefined when you get a nonexistent pref without specifying a default value: | ||
let foo = Preferences.get("extensions.test.nonexistent"); | let foo = Preferences.get("extensions.test.nonexistent"); | ||
| Line 182: | Line 182: | ||
(Although the preferences service doesn't currently store null values, other interfaces like nsIVariant and nsIContentPrefService and embedded storage engines like SQLite distinguish between the null value and "doesn't have a value," as does JavaScript, so it seems more consistent and robust to do so here as well.) | (Although the preferences service doesn't currently store null values, other interfaces like nsIVariant and nsIContentPrefService and embedded storage engines like SQLite distinguish between the null value and "doesn't have a value," as does JavaScript, so it seems more consistent and robust to do so here as well.) | ||
Because we aren't using XPCOM, we can include some interesting API features. First, as you may have noticed already, the interface doesn't require you to create a branch just to get a pref, but you can create one | Because we aren't using XPCOM, we can include some interesting API features. First, as you may have noticed already, the interface doesn't require you to create a branch just to get a pref, but you can create one via an intuitive syntax: | ||
let testBranch = new Preferences("extensions.test."); | let testBranch = new Preferences("extensions.test."); | ||
// Preferences.get("extensions.test.foo") == testBranch.get("foo") | // Preferences.get("extensions.test.foo") == testBranch.get("foo") | ||
<code>get</code> uses polymorphism to enable you to retrieve multiple values in a single call, and, with JS 1.7's destructuring assignment, you can assign those values to individual variables: | |||
let [foo, bar, baz] = testBranch.get(["foo", "bar", "baz"]); | let [foo, bar, baz] = testBranch.get(["foo", "bar", "baz"]); | ||
| Line 194: | Line 194: | ||
testBranch.set({ foo: 1, bar: "awesome", baz: true }); | testBranch.set({ foo: 1, bar: "awesome", baz: true }); | ||
You can also reset preferences (i.e. remove the user-set value) and check if they're set: | |||
Preferences.reset("extensions.test.foo"); | |||
let isSetFoo = Preferences.isSet("extensions.test.foo"); | |||
// isSetFoo == false, since we've just reset it | |||
<code>isSet</code> tells you whether or not the preference has a set value. Some preferences also have default values that apply if the preference doesn't have a set value. To find out if a preference has any value (whether set or default), use the <code>has</code> method: | |||
Preferences.reset("extensions.test.foo"); | |||
let hasFoo = Preferences.has("extensions.test.foo"); | |||
// hasFoo == true, if the pref has a default value | |||
Preferences with default values can be locked to prevent users from changing them. While they are locked, <code>get</code> will always return the default value, even if the user set a value back when the preference was unlocked. | |||
Use the <code>lock</code> and <code>unlock</code> methods to lock and unlock such preferences and the <code>locked</code> method to determine whether or not a preference is locked: | |||
Preferences.lock("extensions.test.foo"); | |||
let lockedFoo = Preferences.locked("extensions.test.foo"); | |||
// lockedFoo == true, since we've just locked it | |||
let foo = Preferences.get("extensions.test.foo"); | |||
// foo == the preference's default value, even if the user changed it | |||
Preferences.unlock("extensions.test.foo"); | |||
lockedFoo = Preferences.locked("extensions.test.foo"); | |||
// lockedFoo == false, since we've just unlocked it | |||
== StringBundle == | == StringBundle == | ||