1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/services/common/stringbundle.js Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,203 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +this.EXPORTED_SYMBOLS = ["StringBundle"];
1.9 +
1.10 +const {classes: Cc, interfaces: Ci, results: Cr, utils: Cu} = Components;
1.11 +
1.12 +/**
1.13 + * A string bundle.
1.14 + *
1.15 + * This object presents two APIs: a deprecated one that is equivalent to the API
1.16 + * for the stringbundle XBL binding, to make it easy to switch from that binding
1.17 + * to this module, and a new one that is simpler and easier to use.
1.18 + *
1.19 + * The benefit of this module over the XBL binding is that it can also be used
1.20 + * in JavaScript modules and components, not only in chrome JS.
1.21 + *
1.22 + * To use this module, import it, create a new instance of StringBundle,
1.23 + * and then use the instance's |get| and |getAll| methods to retrieve strings
1.24 + * (you can get both plain and formatted strings with |get|):
1.25 + *
1.26 + * let strings =
1.27 + * new StringBundle("chrome://example/locale/strings.properties");
1.28 + * let foo = strings.get("foo");
1.29 + * let barFormatted = strings.get("bar", [arg1, arg2]);
1.30 + * for each (let string in strings.getAll())
1.31 + * dump (string.key + " = " + string.value + "\n");
1.32 + *
1.33 + * @param url {String}
1.34 + * the URL of the string bundle
1.35 + */
1.36 +this.StringBundle = function StringBundle(url) {
1.37 + this.url = url;
1.38 +}
1.39 +
1.40 +StringBundle.prototype = {
1.41 + /**
1.42 + * the locale associated with the application
1.43 + * @type nsILocale
1.44 + * @private
1.45 + */
1.46 + get _appLocale() {
1.47 + try {
1.48 + return Cc["@mozilla.org/intl/nslocaleservice;1"].
1.49 + getService(Ci.nsILocaleService).
1.50 + getApplicationLocale();
1.51 + }
1.52 + catch(ex) {
1.53 + return null;
1.54 + }
1.55 + },
1.56 +
1.57 + /**
1.58 + * the wrapped nsIStringBundle
1.59 + * @type nsIStringBundle
1.60 + * @private
1.61 + */
1.62 + get _stringBundle() {
1.63 + let stringBundle = Cc["@mozilla.org/intl/stringbundle;1"].
1.64 + getService(Ci.nsIStringBundleService).
1.65 + createBundle(this.url, this._appLocale);
1.66 + this.__defineGetter__("_stringBundle", function() stringBundle);
1.67 + return this._stringBundle;
1.68 + },
1.69 +
1.70 +
1.71 + // the new API
1.72 +
1.73 + /**
1.74 + * the URL of the string bundle
1.75 + * @type String
1.76 + */
1.77 + _url: null,
1.78 + get url() {
1.79 + return this._url;
1.80 + },
1.81 + set url(newVal) {
1.82 + this._url = newVal;
1.83 + delete this._stringBundle;
1.84 + },
1.85 +
1.86 + /**
1.87 + * Get a string from the bundle.
1.88 + *
1.89 + * @param key {String}
1.90 + * the identifier of the string to get
1.91 + * @param args {array} [optional]
1.92 + * an array of arguments that replace occurrences of %S in the string
1.93 + *
1.94 + * @returns {String} the value of the string
1.95 + */
1.96 + get: function(key, args) {
1.97 + if (args)
1.98 + return this.stringBundle.formatStringFromName(key, args, args.length);
1.99 + else
1.100 + return this.stringBundle.GetStringFromName(key);
1.101 + },
1.102 +
1.103 + /**
1.104 + * Get all the strings in the bundle.
1.105 + *
1.106 + * @returns {Array}
1.107 + * an array of objects with key and value properties
1.108 + */
1.109 + getAll: function() {
1.110 + let strings = [];
1.111 +
1.112 + // FIXME: for performance, return an enumerable array that wraps the string
1.113 + // bundle's nsISimpleEnumerator (does JavaScript already support this?).
1.114 +
1.115 + let enumerator = this.stringBundle.getSimpleEnumeration();
1.116 +
1.117 + while (enumerator.hasMoreElements()) {
1.118 + // We could simply return the nsIPropertyElement objects, but I think
1.119 + // it's better to return standard JS objects that behave as consumers
1.120 + // expect JS objects to behave (f.e. you can modify them dynamically).
1.121 + let string = enumerator.getNext().QueryInterface(Ci.nsIPropertyElement);
1.122 + strings.push({ key: string.key, value: string.value });
1.123 + }
1.124 +
1.125 + return strings;
1.126 + },
1.127 +
1.128 +
1.129 + // the deprecated XBL binding-compatible API
1.130 +
1.131 + /**
1.132 + * the URL of the string bundle
1.133 + * @deprecated because its name doesn't make sense outside of an XBL binding
1.134 + * @type String
1.135 + */
1.136 + get src() {
1.137 + return this.url;
1.138 + },
1.139 + set src(newVal) {
1.140 + this.url = newVal;
1.141 + },
1.142 +
1.143 + /**
1.144 + * the locale associated with the application
1.145 + * @deprecated because it has never been used outside the XBL binding itself,
1.146 + * and consumers should obtain it directly from the locale service anyway.
1.147 + * @type nsILocale
1.148 + */
1.149 + get appLocale() {
1.150 + return this._appLocale;
1.151 + },
1.152 +
1.153 + /**
1.154 + * the wrapped nsIStringBundle
1.155 + * @deprecated because this module should provide all necessary functionality
1.156 + * @type nsIStringBundle
1.157 + *
1.158 + * If you do ever need to use this, let the authors of this module know why
1.159 + * so they can surface functionality for your use case in the module itself
1.160 + * and you don't have to access this underlying XPCOM component.
1.161 + */
1.162 + get stringBundle() {
1.163 + return this._stringBundle;
1.164 + },
1.165 +
1.166 + /**
1.167 + * Get a string from the bundle.
1.168 + * @deprecated use |get| instead
1.169 + *
1.170 + * @param key {String}
1.171 + * the identifier of the string to get
1.172 + *
1.173 + * @returns {String}
1.174 + * the value of the string
1.175 + */
1.176 + getString: function(key) {
1.177 + return this.get(key);
1.178 + },
1.179 +
1.180 + /**
1.181 + * Get a formatted string from the bundle.
1.182 + * @deprecated use |get| instead
1.183 + *
1.184 + * @param key {string}
1.185 + * the identifier of the string to get
1.186 + * @param args {array}
1.187 + * an array of arguments that replace occurrences of %S in the string
1.188 + *
1.189 + * @returns {String}
1.190 + * the formatted value of the string
1.191 + */
1.192 + getFormattedString: function(key, args) {
1.193 + return this.get(key, args);
1.194 + },
1.195 +
1.196 + /**
1.197 + * Get an enumeration of the strings in the bundle.
1.198 + * @deprecated use |getAll| instead
1.199 + *
1.200 + * @returns {nsISimpleEnumerator}
1.201 + * a enumeration of the strings in the bundle
1.202 + */
1.203 + get strings() {
1.204 + return this.stringBundle.getSimpleEnumeration();
1.205 + }
1.206 +}
