Debian Codegraph @

closure-library/closure/goog/ui/editor/abstractdialog.js

raw
1 // Copyright 2008 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 Wrapper around {@link goog.ui.Dialog}, to provide
17 * dialogs that are smarter about interacting with a rich text editor.
18 *
19 * @author [email protected] (Nick Santos)
20 */
21
22 goog.provide('goog.ui.editor.AbstractDialog');
23 goog.provide('goog.ui.editor.AbstractDialog.Builder');
24 goog.provide('goog.ui.editor.AbstractDialog.EventType');
25
26 goog.require('goog.asserts');
27 goog.require('goog.dom');
28 goog.require('goog.dom.classlist');
29 goog.require('goog.events.EventTarget');
30 goog.require('goog.string');
31 goog.require('goog.ui.Dialog');
32 goog.require('goog.ui.PopupBase');
33
34
35 // *** Public interface ***************************************************** //
36
37
38
39 /**
40 * Creates an object that represents a dialog box.
41 * @param {goog.dom.DomHelper} domHelper DomHelper to be used to create the
42 * dialog's dom structure.
43 * @constructor
44 * @extends {goog.events.EventTarget}
45 */
46 goog.ui.editor.AbstractDialog = function(domHelper) {
47 goog.ui.editor.AbstractDialog.base(this, 'constructor');
48 this.dom = domHelper;
49
50 /** @private {?goog.ui.Dialog} */
51 this.dialogInternal_ = null;
52 };
53 goog.inherits(goog.ui.editor.AbstractDialog, goog.events.EventTarget);
54
55
56 /**
57 * Causes the dialog box to appear, centered on the screen. Lazily creates the
58 * dialog if needed.
59 */
60 goog.ui.editor.AbstractDialog.prototype.show = function() {
61 // Lazily create the wrapped dialog to be shown.
62 if (!this.dialogInternal_) {
63 this.dialogInternal_ = this.createDialogControl();
64 this.dialogInternal_.listen(
65 goog.ui.PopupBase.EventType.HIDE, this.handleAfterHide_, false, this);
66 }
67
68 this.dialogInternal_.setVisible(true);
69 };
70
71
72 /**
73 * Hides the dialog, causing AFTER_HIDE to fire.
74 */
75 goog.ui.editor.AbstractDialog.prototype.hide = function() {
76 if (this.dialogInternal_) {
77 // This eventually fires the wrapped dialog's AFTER_HIDE event, calling our
78 // handleAfterHide_().
79 this.dialogInternal_.setVisible(false);
80 }
81 };
82
83
84 /**
85 * @return {boolean} Whether the dialog is open.
86 */
87 goog.ui.editor.AbstractDialog.prototype.isOpen = function() {
88 return !!this.dialogInternal_ && this.dialogInternal_.isVisible();
89 };
90
91
92 /**
93 * Runs the handler registered on the OK button event and closes the dialog if
94 * that handler succeeds.
95 * This is useful in cases such as double-clicking an item in the dialog is
96 * equivalent to selecting it and clicking the default button.
97 * @protected
98 */
99 goog.ui.editor.AbstractDialog.prototype.processOkAndClose = function() {
100 // Fake an OK event from the wrapped dialog control.
101 var evt = new goog.ui.Dialog.Event(goog.ui.Dialog.DefaultButtonKeys.OK, null);
102 if (this.handleOk(evt)) {
103 // handleOk calls dispatchEvent, so if any listener calls preventDefault it
104 // will return false and we won't hide the dialog.
105 this.hide();
106 }
107 };
108
109
110 // *** Dialog events ******************************************************** //
111
112
113 /**
114 * Event type constants for events the dialog fires.
115 * @enum {string}
116 */
117 goog.ui.editor.AbstractDialog.EventType = {
118 // This event is fired after the dialog is hidden, no matter if it was closed
119 // via OK or Cancel or is being disposed without being hidden first.
120 AFTER_HIDE: 'afterhide',
121 // Either the cancel or OK events can be canceled via preventDefault or by
122 // returning false from their handlers to stop the dialog from closing.
123 CANCEL: 'cancel',
124 OK: 'ok'
125 };
126
127
128 // *** Inner helper class *************************************************** //
129
130
131
132 /**
133 * A builder class for the dialog control. All methods except build return this.
134 * @param {goog.ui.editor.AbstractDialog} editorDialog Editor dialog object
135 * that will wrap the wrapped dialog object this builder will create.
136 * @constructor
137 */
138 goog.ui.editor.AbstractDialog.Builder = function(editorDialog) {
139 // We require the editor dialog to be passed in so that the builder can set up
140 // ok/cancel listeners by default, making it easier for most dialogs.
141 this.editorDialog_ = editorDialog;
142 this.wrappedDialog_ = new goog.ui.Dialog('', true, this.editorDialog_.dom);
143 this.buttonSet_ = new goog.ui.Dialog.ButtonSet(this.editorDialog_.dom);
144 this.buttonHandlers_ = {};
145 this.addClassName(goog.getCssName('tr-dialog'));
146 };
147
148
149 /**
150 * Sets the title of the dialog.
151 * @param {string} title Title HTML (escaped).
152 * @return {!goog.ui.editor.AbstractDialog.Builder} This.
153 */
154 goog.ui.editor.AbstractDialog.Builder.prototype.setTitle = function(title) {
155 this.wrappedDialog_.setTitle(title);
156 return this;
157 };
158
159
160 /**
161 * Adds an OK button to the dialog. Clicking this button will cause {@link
162 * handleOk} to run, subsequently dispatching an OK event.
163 * @param {string=} opt_label The caption for the button, if not "OK".
164 * @return {!goog.ui.editor.AbstractDialog.Builder} This.
165 */
166 goog.ui.editor.AbstractDialog.Builder.prototype.addOkButton = function(
167 opt_label) {
168 var key = goog.ui.Dialog.DefaultButtonKeys.OK;
169 /** @desc Label for an OK button in an editor dialog. */
170 var MSG_TR_DIALOG_OK = goog.getMsg('OK');
171 // True means this is the default/OK button.
172 this.buttonSet_.set(key, opt_label || MSG_TR_DIALOG_OK, true);
173 this.buttonHandlers_[key] =
174 goog.bind(this.editorDialog_.handleOk, this.editorDialog_);
175 return this;
176 };
177
178
179 /**
180 * Adds a Cancel button to the dialog. Clicking this button will cause {@link
181 * handleCancel} to run, subsequently dispatching a CANCEL event.
182 * @param {string=} opt_label The caption for the button, if not "Cancel".
183 * @return {!goog.ui.editor.AbstractDialog.Builder} This.
184 */
185 goog.ui.editor.AbstractDialog.Builder.prototype.addCancelButton = function(
186 opt_label) {
187 var key = goog.ui.Dialog.DefaultButtonKeys.CANCEL;
188 /** @desc Label for a cancel button in an editor dialog. */
189 var MSG_TR_DIALOG_CANCEL = goog.getMsg('Cancel');
190 // False means it's not the OK button, true means it's the Cancel button.
191 this.buttonSet_.set(key, opt_label || MSG_TR_DIALOG_CANCEL, false, true);
192 this.buttonHandlers_[key] =
193 goog.bind(this.editorDialog_.handleCancel, this.editorDialog_);
194 return this;
195 };
196
197
198 /**
199 * Adds a custom button to the dialog.
200 * @param {string} label The caption for the button.
201 * @param {function(goog.ui.Dialog.EventType):*} handler Function called when
202 * the button is clicked. It is recommended that this function be a method
203 * in the concrete subclass of AbstractDialog using this Builder, and that
204 * it dispatch an event (see {@link handleOk}).
205 * @param {string=} opt_buttonId Identifier to be used to access the button when
206 * calling AbstractDialog.getButtonElement().
207 * @return {!goog.ui.editor.AbstractDialog.Builder} This.
208 */
209 goog.ui.editor.AbstractDialog.Builder.prototype.addButton = function(
210 label, handler, opt_buttonId) {
211 // We don't care what the key is, just that we can match the button with the
212 // handler function later.
213 var key = opt_buttonId || goog.string.createUniqueString();
214 this.buttonSet_.set(key, label);
215 this.buttonHandlers_[key] = handler;
216 return this;
217 };
218
219
220 /**
221 * Puts a CSS class on the dialog's main element.
222 * @param {string} className The class to add.
223 * @return {!goog.ui.editor.AbstractDialog.Builder} This.
224 */
225 goog.ui.editor.AbstractDialog.Builder.prototype.addClassName = function(
226 className) {
227 goog.dom.classlist.add(
228 goog.asserts.assert(this.wrappedDialog_.getDialogElement()), className);
229 return this;
230 };
231
232
233 /**
234 * Sets the content element of the dialog.
235 * @param {Element} contentElem An element for the main body.
236 * @return {!goog.ui.editor.AbstractDialog.Builder} This.
237 */
238 goog.ui.editor.AbstractDialog.Builder.prototype.setContent = function(
239 contentElem) {
240 goog.dom.appendChild(this.wrappedDialog_.getContentElement(), contentElem);
241 return this;
242 };
243
244
245 /**
246 * Builds the wrapped dialog control. May only be called once, after which
247 * no more methods may be called on this builder.
248 * @return {!goog.ui.Dialog} The wrapped dialog control.
249 */
250 goog.ui.editor.AbstractDialog.Builder.prototype.build = function() {
251 if (this.buttonSet_.isEmpty()) {
252 // If caller didn't set any buttons, add an OK and Cancel button by default.
253 this.addOkButton();
254 this.addCancelButton();
255 }
256 this.wrappedDialog_.setButtonSet(this.buttonSet_);
257
258 var handlers = this.buttonHandlers_;
259 this.buttonHandlers_ = null;
260 this.wrappedDialog_.listen(
261 goog.ui.Dialog.EventType.SELECT,
262 // Listen for the SELECT event, which means a button was clicked, and
263 // call the handler associated with that button via the key property.
264 function(e) {
265 if (handlers[e.key]) {
266 return handlers[e.key](e);
267 }
268 });
269
270 // All editor dialogs are modal.
271 this.wrappedDialog_.setModal(true);
272
273 var dialog = this.wrappedDialog_;
274 this.wrappedDialog_ = null;
275 return dialog;
276 };
277
278
279 /**
280 * Editor dialog that will wrap the wrapped dialog this builder will create.
281 * @type {goog.ui.editor.AbstractDialog}
282 * @private
283 */
284 goog.ui.editor.AbstractDialog.Builder.prototype.editorDialog_;
285
286
287 /**
288 * wrapped dialog control being built by this builder.
289 * @type {goog.ui.Dialog}
290 * @private
291 */
292 goog.ui.editor.AbstractDialog.Builder.prototype.wrappedDialog_;
293
294
295 /**
296 * Set of buttons to be added to the wrapped dialog control.
297 * @type {goog.ui.Dialog.ButtonSet}
298 * @private
299 */
300 goog.ui.editor.AbstractDialog.Builder.prototype.buttonSet_;
301
302
303 /**
304 * Map from keys that will be returned in the wrapped dialog SELECT events to
305 * handler functions to be called to handle those events.
306 * @type {Object}
307 * @private
308 */
309 goog.ui.editor.AbstractDialog.Builder.prototype.buttonHandlers_;
310
311
312 // *** Protected interface ************************************************** //
313
314
315 /**
316 * The DOM helper for the parent document.
317 * @type {goog.dom.DomHelper}
318 * @protected
319 */
320 goog.ui.editor.AbstractDialog.prototype.dom;
321
322
323 /**
324 * Creates and returns the goog.ui.Dialog control that is being wrapped
325 * by this object.
326 * @return {!goog.ui.Dialog} Created Dialog control.
327 * @protected
328 */
329 goog.ui.editor.AbstractDialog.prototype.createDialogControl =
330 goog.abstractMethod;
331
332
333 /**
334 * Returns the HTML Button element for the OK button in this dialog.
335 * @return {Element} The button element if found, else null.
336 * @protected
337 */
338 goog.ui.editor.AbstractDialog.prototype.getOkButtonElement = function() {
339 return this.getButtonElement(goog.ui.Dialog.DefaultButtonKeys.OK);
340 };
341
342
343 /**
344 * Returns the HTML Button element for the Cancel button in this dialog.
345 * @return {Element} The button element if found, else null.
346 * @protected
347 */
348 goog.ui.editor.AbstractDialog.prototype.getCancelButtonElement = function() {
349 return this.getButtonElement(goog.ui.Dialog.DefaultButtonKeys.CANCEL);
350 };
351
352
353 /**
354 * Returns the HTML Button element for the button added to this dialog with
355 * the given button id.
356 * @param {string} buttonId The id of the button to get.
357 * @return {Element} The button element if found, else null.
358 * @protected
359 */
360 goog.ui.editor.AbstractDialog.prototype.getButtonElement = function(buttonId) {
361 return this.dialogInternal_.getButtonSet().getButton(buttonId);
362 };
363
364
365 /**
366 * Creates and returns the event object to be used when dispatching the OK
367 * event to listeners, or returns null to prevent the dialog from closing.
368 * Subclasses should override this to return their own subclass of
369 * goog.events.Event that includes all data a plugin would need from the dialog.
370 * @param {goog.events.Event} e The event object dispatched by the wrapped
371 * dialog.
372 * @return {goog.events.Event} The event object to be used when dispatching the
373 * OK event to listeners.
374 * @protected
375 */
376 goog.ui.editor.AbstractDialog.prototype.createOkEvent = goog.abstractMethod;
377
378
379 /**
380 * Handles the event dispatched by the wrapped dialog control when the user
381 * clicks the OK button. Attempts to create the OK event object and dispatches
382 * it if successful.
383 * @param {goog.ui.Dialog.Event} e wrapped dialog OK event object.
384 * @return {boolean} Whether the default action (closing the dialog) should
385 * still be executed. This will be false if the OK event could not be
386 * created to be dispatched, or if any listener to that event returs false
387 * or calls preventDefault.
388 * @protected
389 */
390 goog.ui.editor.AbstractDialog.prototype.handleOk = function(e) {
391 var eventObj = this.createOkEvent(e);
392 if (eventObj) {
393 return this.dispatchEvent(eventObj);
394 } else {
395 return false;
396 }
397 };
398
399
400 /**
401 * Handles the event dispatched by the wrapped dialog control when the user
402 * clicks the Cancel button. Simply dispatches a CANCEL event.
403 * @return {boolean} Returns false if any of the handlers called prefentDefault
404 * on the event or returned false themselves.
405 * @protected
406 */
407 goog.ui.editor.AbstractDialog.prototype.handleCancel = function() {
408 return this.dispatchEvent(goog.ui.editor.AbstractDialog.EventType.CANCEL);
409 };
410
411
412 /**
413 * Disposes of the dialog. If the dialog is open, it will be hidden and
414 * AFTER_HIDE will be dispatched.
415 * @override
416 * @protected
417 */
418 goog.ui.editor.AbstractDialog.prototype.disposeInternal = function() {
419 if (this.dialogInternal_) {
420 this.hide();
421
422 this.dialogInternal_.dispose();
423 this.dialogInternal_ = null;
424 }
425
426 goog.ui.editor.AbstractDialog.superClass_.disposeInternal.call(this);
427 };
428
429
430 // *** Private implementation *********************************************** //
431
432
433 /**
434 * Cleans up after the dialog is hidden and fires the AFTER_HIDE event. Should
435 * be a listener for the wrapped dialog's AFTER_HIDE event.
436 * @private
437 */
438 goog.ui.editor.AbstractDialog.prototype.handleAfterHide_ = function() {
439 this.dispatchEvent(goog.ui.editor.AbstractDialog.EventType.AFTER_HIDE);
440 };