Debian Codegraph @

closure-library/closure/goog/tweak/registry.js

raw
1 // Copyright 2009 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Definition for goog.tweak.Registry.
17 * Most clients should not use this class directly, but instead use the API
18 * defined in tweak.js. One possible use case for directly using TweakRegistry
19 * is to register tweaks that are not known at compile time.
20 *
21 * @author [email protected] (Andrew Grieve)
22 */
23
24 goog.provide('goog.tweak.Registry');
25
26 goog.require('goog.array');
27 goog.require('goog.asserts');
28 goog.require('goog.log');
29 goog.require('goog.string');
30 goog.require('goog.tweak.BasePrimitiveSetting');
31 goog.require('goog.tweak.BaseSetting');
32 goog.require('goog.tweak.BooleanSetting');
33 goog.require('goog.tweak.NumericSetting');
34 goog.require('goog.tweak.StringSetting');
35 goog.require('goog.uri.utils');
36
37
38
39 /**
40 * Singleton that manages all tweaks. This should be instantiated only from
41 * goog.tweak.getRegistry().
42 * @param {string} queryParams Value of window.location.search.
43 * @param {!Object<string|number|boolean>} compilerOverrides Default value
44 * overrides set by the compiler.
45 * @constructor
46 * @final
47 */
48 goog.tweak.Registry = function(queryParams, compilerOverrides) {
49 /**
50 * A map of entry id -> entry object
51 * @type {!Object<!goog.tweak.BaseEntry>}
52 * @private
53 */
54 this.entryMap_ = {};
55
56 /**
57 * The map of query params to use when initializing entry settings.
58 * @type {!Object<string>}
59 * @private
60 */
61 this.parsedQueryParams_ = goog.tweak.Registry.parseQueryParams(queryParams);
62
63 /**
64 * List of callbacks to call when a new entry is registered.
65 * @type {!Array<!Function>}
66 * @private
67 */
68 this.onRegisterListeners_ = [];
69
70 /**
71 * A map of entry ID -> default value override for overrides set by the
72 * compiler.
73 * @type {!Object<string|number|boolean>}
74 * @private
75 */
76 this.compilerDefaultValueOverrides_ = compilerOverrides;
77
78 /**
79 * A map of entry ID -> default value override for overrides set by
80 * goog.tweak.overrideDefaultValue().
81 * @type {!Object<string|number|boolean>}
82 * @private
83 */
84 this.defaultValueOverrides_ = {};
85 };
86
87
88 /**
89 * The logger for this class.
90 * @type {goog.log.Logger}
91 * @private
92 */
93 goog.tweak.Registry.prototype.logger_ =
94 goog.log.getLogger('goog.tweak.Registry');
95
96
97 /**
98 * Simple parser for query params. Makes all keys lower-case.
99 * @param {string} queryParams The part of the url between the ? and the #.
100 * @return {!Object<string>} map of key->value.
101 */
102 goog.tweak.Registry.parseQueryParams = function(queryParams) {
103 // Strip off the leading ? and split on &.
104 var parts = queryParams.substr(1).split('&');
105 var ret = {};
106
107 for (var i = 0, il = parts.length; i < il; ++i) {
108 var entry = parts[i].split('=');
109 if (entry[0]) {
110 ret[goog.string.urlDecode(entry[0]).toLowerCase()] =
111 goog.string.urlDecode(entry[1] || '');
112 }
113 }
114 return ret;
115 };
116
117
118 /**
119 * Registers the given tweak setting/action.
120 * @param {goog.tweak.BaseEntry} entry The entry.
121 */
122 goog.tweak.Registry.prototype.register = function(entry) {
123 var id = entry.getId();
124 var oldBaseEntry = this.entryMap_[id];
125 if (oldBaseEntry) {
126 if (oldBaseEntry == entry) {
127 goog.log.warning(this.logger_, 'Tweak entry registered twice: ' + id);
128 return;
129 }
130 goog.asserts.fail(
131 'Tweak entry registered twice and with different types: ' + id);
132 }
133
134 // Check for a default value override, either from compiler flags or from a
135 // call to overrideDefaultValue().
136 var defaultValueOverride = (id in this.compilerDefaultValueOverrides_) ?
137 this.compilerDefaultValueOverrides_[id] :
138 this.defaultValueOverrides_[id];
139 if (goog.isDef(defaultValueOverride)) {
140 goog.asserts.assertInstanceof(
141 entry, goog.tweak.BasePrimitiveSetting,
142 'Cannot set the default value of non-primitive setting %s',
143 entry.label);
144 entry.setDefaultValue(defaultValueOverride);
145 }
146
147 // Set its value from the query params.
148 if (entry instanceof goog.tweak.BaseSetting) {
149 if (entry.getParamName()) {
150 entry.setInitialQueryParamValue(
151 this.parsedQueryParams_[entry.getParamName()]);
152 }
153 }
154
155 this.entryMap_[id] = entry;
156 // Call all listeners.
157 for (var i = 0, callback; callback = this.onRegisterListeners_[i]; ++i) {
158 callback(entry);
159 }
160 };
161
162
163 /**
164 * Adds a callback to be called whenever a new tweak is added.
165 * @param {!Function} func The callback.
166 */
167 goog.tweak.Registry.prototype.addOnRegisterListener = function(func) {
168 this.onRegisterListeners_.push(func);
169 };
170
171
172 /**
173 * @param {string} id The unique string that identifies this entry.
174 * @return {boolean} Whether a tweak with the given ID is registered.
175 */
176 goog.tweak.Registry.prototype.hasEntry = function(id) {
177 return id in this.entryMap_;
178 };
179
180
181 /**
182 * Returns the BaseEntry with the given ID. Asserts if it does not exists.
183 * @param {string} id The unique string that identifies this entry.
184 * @return {!goog.tweak.BaseEntry} The entry.
185 */
186 goog.tweak.Registry.prototype.getEntry = function(id) {
187 var ret = this.entryMap_[id];
188 goog.asserts.assert(ret, 'Tweak not registered: %s', id);
189 return ret;
190 };
191
192
193 /**
194 * Returns the boolean setting with the given ID. Asserts if the ID does not
195 * refer to a registered entry or if it refers to one of the wrong type.
196 * @param {string} id The unique string that identifies this entry.
197 * @return {!goog.tweak.BooleanSetting} The entry.
198 */
199 goog.tweak.Registry.prototype.getBooleanSetting = function(id) {
200 var entry = this.getEntry(id);
201 goog.asserts.assertInstanceof(
202 entry, goog.tweak.BooleanSetting,
203 'getBooleanSetting called on wrong type of BaseSetting');
204 return /** @type {!goog.tweak.BooleanSetting} */ (entry);
205 };
206
207
208 /**
209 * Returns the string setting with the given ID. Asserts if the ID does not
210 * refer to a registered entry or if it refers to one of the wrong type.
211 * @param {string} id The unique string that identifies this entry.
212 * @return {!goog.tweak.StringSetting} The entry.
213 */
214 goog.tweak.Registry.prototype.getStringSetting = function(id) {
215 var entry = this.getEntry(id);
216 goog.asserts.assertInstanceof(
217 entry, goog.tweak.StringSetting,
218 'getStringSetting called on wrong type of BaseSetting');
219 return /** @type {!goog.tweak.StringSetting} */ (entry);
220 };
221
222
223 /**
224 * Returns the numeric setting with the given ID. Asserts if the ID does not
225 * refer to a registered entry or if it refers to one of the wrong type.
226 * @param {string} id The unique string that identifies this entry.
227 * @return {!goog.tweak.NumericSetting} The entry.
228 */
229 goog.tweak.Registry.prototype.getNumericSetting = function(id) {
230 var entry = this.getEntry(id);
231 goog.asserts.assertInstanceof(
232 entry, goog.tweak.NumericSetting,
233 'getNumericSetting called on wrong type of BaseSetting');
234 return /** @type {!goog.tweak.NumericSetting} */ (entry);
235 };
236
237
238 /**
239 * Creates and returns an array of all BaseSetting objects with an associted
240 * query parameter.
241 * @param {boolean} excludeChildEntries Exclude BooleanInGroupSettings.
242 * @param {boolean} excludeNonSettings Exclude entries that are not subclasses
243 * of BaseSetting.
244 * @return {!Array<!goog.tweak.BaseSetting>} The settings.
245 */
246 goog.tweak.Registry.prototype.extractEntries = function(
247 excludeChildEntries, excludeNonSettings) {
248 var entries = [];
249 for (var id in this.entryMap_) {
250 var entry = this.entryMap_[id];
251 if (entry instanceof goog.tweak.BaseSetting) {
252 if (excludeChildEntries && !entry.getParamName()) {
253 continue;
254 }
255 } else if (excludeNonSettings) {
256 continue;
257 }
258 entries.push(entry);
259 }
260 return entries;
261 };
262
263
264 /**
265 * Returns the query part of the URL that will apply all set tweaks.
266 * @param {string=} opt_existingSearchStr The part of the url between the ? and
267 * the #. Uses window.location.search if not given.
268 * @return {string} The query string.
269 */
270 goog.tweak.Registry.prototype.makeUrlQuery = function(opt_existingSearchStr) {
271 var existingParams = opt_existingSearchStr == undefined ?
272 window.location.search :
273 opt_existingSearchStr;
274
275 var sortedEntries = this.extractEntries(
276 true /* excludeChildEntries */, true /* excludeNonSettings */);
277 // Sort the params so that the urlQuery has stable ordering.
278 sortedEntries.sort(function(a, b) {
279 return goog.array.defaultCompare(a.getParamName(), b.getParamName());
280 });
281
282 // Add all values that are not set to their defaults.
283 var keysAndValues = [];
284 for (var i = 0, entry; entry = sortedEntries[i]; ++i) {
285 var encodedValue = entry.getNewValueEncoded();
286 if (encodedValue != null) {
287 keysAndValues.push(entry.getParamName(), encodedValue);
288 }
289 // Strip all tweak query params from the existing query string. This will
290 // make the final query string contain only the tweak settings that are set
291 // to their non-default values and also maintain non-tweak related query
292 // parameters.
293 existingParams = goog.uri.utils.removeParam(
294 existingParams,
295 encodeURIComponent(/** @type {string} */ (entry.getParamName())));
296 }
297
298 var tweakParams = goog.uri.utils.buildQueryData(keysAndValues);
299 // Decode spaces and commas in order to make the URL more readable.
300 tweakParams = tweakParams.replace(/%2C/g, ',').replace(/%20/g, '+');
301 return !tweakParams ? existingParams : existingParams ?
302 existingParams + '&' + tweakParams :
303 '?' + tweakParams;
304 };
305
306
307 /**
308 * Sets a default value to use for the given tweak instead of the one passed
309 * to the register* function. This function must be called before the tweak is
310 * registered.
311 * @param {string} id The unique string that identifies the entry.
312 * @param {string|number|boolean} value The replacement value to be used as the
313 * default value for the setting.
314 */
315 goog.tweak.Registry.prototype.overrideDefaultValue = function(id, value) {
316 goog.asserts.assert(
317 !this.hasEntry(id),
318 'goog.tweak.overrideDefaultValue must be called before the tweak is ' +
319 'registered. Tweak: %s',
320 id);
321 this.defaultValueOverrides_[id] = value;
322 };