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 An abstract superclass for TrogEdit dialog plugins. Each
17
 * Trogedit dialog has its own plugin.
18
 *
19
 * @author [email protected] (Nick Santos)
20
 */
21

22
goog.provide('goog.editor.plugins.AbstractDialogPlugin');
23
goog.provide('goog.editor.plugins.AbstractDialogPlugin.EventType');
24

25
goog.require('goog.dom');
26
goog.require('goog.dom.Range');
27
goog.require('goog.editor.Field');
28
goog.require('goog.editor.Plugin');
29
goog.require('goog.editor.range');
30
goog.require('goog.events');
31
goog.require('goog.ui.editor.AbstractDialog');
32

33

34
// *** Public interface ***************************************************** //
35

36

37

38
/**
39
 * An abstract superclass for a Trogedit plugin that creates exactly one
40
 * dialog. By default dialogs are not reused -- each time execCommand is called,
41
 * a new instance of the dialog object is created (and the old one disposed of).
42
 * To enable reusing of the dialog object, subclasses should call
43
 * setReuseDialog() after calling the superclass constructor.
44
 * @param {string} command The command that this plugin handles.
45
 * @constructor
46
 * @extends {goog.editor.Plugin}
47
 */
48
goog.editor.plugins.AbstractDialogPlugin = function(command) {
49
  goog.editor.plugins.AbstractDialogPlugin.base(this, 'constructor');
50

51
  /**
52
   * The command that this plugin handles.
53
   * @private {string}
54
   */
55
  this.command_ = command;
56

57
  /** @private {function()} */
58
  this.restoreScrollPosition_ = function() {};
59

60
  /**
61
   * The current dialog that was created and opened by this plugin.
62
   * @private {?goog.ui.editor.AbstractDialog}
63
   */
64
  this.dialog_ = null;
65

66
  /**
67
   * Whether this plugin should reuse the same instance of the dialog each time
68
   * execCommand is called or create a new one.
69
   * @private {boolean}
70
   */
71
  this.reuseDialog_ = false;
72

73
  /**
74
   * Mutex to prevent recursive calls to disposeDialog_.
75
   * @private {boolean}
76
   */
77
  this.isDisposingDialog_ = false;
78

79
  /**
80
   * SavedRange representing the selection before the dialog was opened.
81
   * @private {?goog.dom.SavedRange}
82
   */
83
  this.savedRange_ = null;
84
};
85
goog.inherits(goog.editor.plugins.AbstractDialogPlugin, goog.editor.Plugin);
86

87

88
/** @override */
89
goog.editor.plugins.AbstractDialogPlugin.prototype.isSupportedCommand =
90
    function(command) {
91
  return command == this.command_;
92
};
93

94

95
/**
96
 * Handles execCommand. Dialog plugins don't make any changes when they open a
97
 * dialog, just when the dialog closes (because only modal dialogs are
98
 * supported). Hence this method does not dispatch the change events that the
99
 * superclass method does.
100
 * @param {string} command The command to execute.
101
 * @param {...*} var_args Any additional parameters needed to
102
 *     execute the command.
103
 * @return {*} The result of the execCommand, if any.
104
 * @override
105
 */
106
goog.editor.plugins.AbstractDialogPlugin.prototype.execCommand = function(
107
    command, var_args) {
108
  return this.execCommandInternal.apply(this, arguments);
109
};
110

111

112
// *** Events *************************************************************** //
113

114

115
/**
116
 * Event type constants for events the dialog plugins fire.
117
 * @enum {string}
118
 */
119
goog.editor.plugins.AbstractDialogPlugin.EventType = {
120
  // This event is fired when a dialog has been opened.
121
  OPENED: 'dialogOpened',
122
  // This event is fired when a dialog has been closed.
123
  CLOSED: 'dialogClosed'
124
};
125

126

127
// *** Protected interface ************************************************** //
128

129

130
/**
131
 * Creates a new instance of this plugin's dialog. Must be overridden by
132
 * subclasses.
133
 * Implementations should expect that the editor is inactive and cannot be
134
 * focused, nor will its caret position (or selection) be determinable until
135
 * after the dialogs goog.ui.PopupBase.EventType.HIDE event has been handled.
136
 * @param {!goog.dom.DomHelper} dialogDomHelper The dom helper to be used to
137
 *     create the dialog.
138
 * @param {*=} opt_arg The dialog specific argument. Concrete subclasses should
139
 *     declare a specific type.
140
 * @return {goog.ui.editor.AbstractDialog} The newly created dialog.
141
 * @protected
142
 */
143
goog.editor.plugins.AbstractDialogPlugin.prototype.createDialog =
144
    goog.abstractMethod;
145

146

147
/**
148
 * Returns the current dialog that was created and opened by this plugin.
149
 * @return {goog.ui.editor.AbstractDialog} The current dialog that was created
150
 *     and opened by this plugin.
151
 * @protected
152
 */
153
goog.editor.plugins.AbstractDialogPlugin.prototype.getDialog = function() {
154
  return this.dialog_;
155
};
156

157

158
/**
159
 * Sets whether this plugin should reuse the same instance of the dialog each
160
 * time execCommand is called or create a new one. This is intended for use by
161
 * subclasses only, hence protected.
162
 * @param {boolean} reuse Whether to reuse the dialog.
163
 * @protected
164
 */
165
goog.editor.plugins.AbstractDialogPlugin.prototype.setReuseDialog = function(
166
    reuse) {
167
  this.reuseDialog_ = reuse;
168
};
169

170

171
/**
172
 * Handles execCommand by opening the dialog. Dispatches
173
 * {@link goog.editor.plugins.AbstractDialogPlugin.EventType.OPENED} after the
174
 * dialog is shown.
175
 * @param {string} command The command to execute.
176
 * @param {*=} opt_arg The dialog specific argument. Should be the same as
177
 *     {@link createDialog}.
178
 * @return {*} Always returns true, indicating the dialog was shown.
179
 * @protected
180
 * @override
181
 */
182
goog.editor.plugins.AbstractDialogPlugin.prototype.execCommandInternal =
183
    function(command, opt_arg) {
184
  // If this plugin should not reuse dialog instances, first dispose of the
185
  // previous dialog.
186
  if (!this.reuseDialog_) {
187
    this.disposeDialog_();
188
  }
189
  // If there is no dialog yet (or we aren't reusing the previous one), create
190
  // one.
191
  if (!this.dialog_) {
192
    this.dialog_ = this.createDialog(
193
        // TODO(user): Add Field.getAppDomHelper. (Note dom helper will
194
        // need to be updated if setAppWindow is called by clients.)
195
        goog.dom.getDomHelper(this.getFieldObject().getAppWindow()), opt_arg);
196
  }
197

198
  // Since we're opening a dialog, we need to clear the selection because the
199
  // focus will be going to the dialog, and if we leave an selection in the
200
  // editor while another selection is active in the dialog as the user is
201
  // typing, some browsers will screw up the original selection. But first we
202
  // save it so we can restore it when the dialog closes.
203
  // getRange may return null if there is no selection in the field.
204
  var tempRange = this.getFieldObject().getRange();
205
  // saveUsingDom() did not work as well as saveUsingNormalizedCarets(),
206
  // not sure why.
207

208
  this.restoreScrollPosition_ = this.saveScrollPosition();
209
  this.savedRange_ =
210
      tempRange && goog.editor.range.saveUsingNormalizedCarets(tempRange);
211
  goog.dom.Range.clearSelection(
212
      this.getFieldObject().getEditableDomHelper().getWindow());
213

214
  // Listen for the dialog closing so we can clean up.
215
  goog.events.listenOnce(
216
      this.dialog_, goog.ui.editor.AbstractDialog.EventType.AFTER_HIDE,
217
      this.handleAfterHide, false, this);
218

219
  this.getFieldObject().setModalMode(true);
220
  this.dialog_.show();
221
  this.dispatchEvent(goog.editor.plugins.AbstractDialogPlugin.EventType.OPENED);
222

223
  // Since the selection has left the document, dispatch a selection
224
  // change event.
225
  this.getFieldObject().dispatchSelectionChangeEvent();
226

227
  return true;
228
};
229

230

231
/**
232
 * Cleans up after the dialog has closed, including restoring the selection to
233
 * what it was before the dialog was opened. If a subclass modifies the editable
234
 * field's content such that the original selection is no longer valid (usually
235
 * the case when the user clicks OK, and sometimes also on Cancel), it is that
236
 * subclass' responsibility to place the selection in the desired place during
237
 * the OK or Cancel (or other) handler. In that case, this method will leave the
238
 * selection in place.
239
 * @param {goog.events.Event} e The AFTER_HIDE event object.
240
 * @protected
241
 */
242
goog.editor.plugins.AbstractDialogPlugin.prototype.handleAfterHide = function(
243
    e) {
244
  this.getFieldObject().setModalMode(false);
245
  this.restoreOriginalSelection();
246
  this.restoreScrollPosition_();
247

248
  if (!this.reuseDialog_) {
249
    this.disposeDialog_();
250
  }
251

252
  this.dispatchEvent(goog.editor.plugins.AbstractDialogPlugin.EventType.CLOSED);
253

254
  // Since the selection has returned to the document, dispatch a selection
255
  // change event.
256
  this.getFieldObject().dispatchSelectionChangeEvent();
257

258
  // When the dialog closes due to pressing enter or escape, that happens on the
259
  // keydown event. But the browser will still fire a keyup event after that,
260
  // which is caught by the editable field and causes it to try to fire a
261
  // selection change event. To avoid that, we "debounce" the selection change
262
  // event, meaning the editable field will not fire that event if the keyup
263
  // that caused it immediately after this dialog was hidden ("immediately"
264
  // means a small number of milliseconds defined by the editable field).
265
  this.getFieldObject().debounceEvent(
266
      goog.editor.Field.EventType.SELECTIONCHANGE);
267
};
268

269

270
/**
271
 * Restores the selection in the editable field to what it was before the dialog
272
 * was opened. This is not guaranteed to work if the contents of the field
273
 * have changed.
274
 * @protected
275
 */
276
goog.editor.plugins.AbstractDialogPlugin.prototype.restoreOriginalSelection =
277
    function() {
278
  this.getFieldObject().restoreSavedRange(this.savedRange_);
279
  this.savedRange_ = null;
280
};
281

282

283
/**
284
 * Cleans up the structure used to save the original selection before the dialog
285
 * was opened. Should be used by subclasses that don't restore the original
286
 * selection via restoreOriginalSelection.
287
 * @protected
288
 */
289
goog.editor.plugins.AbstractDialogPlugin.prototype.disposeOriginalSelection =
290
    function() {
291
  if (this.savedRange_) {
292
    this.savedRange_.dispose();
293
    this.savedRange_ = null;
294
  }
295
};
296

297

298
/** @override */
299
goog.editor.plugins.AbstractDialogPlugin.prototype.disposeInternal =
300
    function() {
301
  this.disposeDialog_();
302
  goog.editor.plugins.AbstractDialogPlugin.base(this, 'disposeInternal');
303
};
304

305

306
// *** Private implementation *********************************************** //
307

308

309
/**
310
 * Disposes of the dialog if needed. It is this abstract class' responsibility
311
 * to dispose of the dialog. The "if needed" refers to the fact this method
312
 * might be called twice (nested calls, not sequential) in the dispose flow, so
313
 * if the dialog was already disposed once it should not be disposed again.
314
 * @private
315
 */
316
goog.editor.plugins.AbstractDialogPlugin.prototype.disposeDialog_ = function() {
317
  // Wrap disposing the dialog in a mutex. Otherwise disposing it would cause it
318
  // to get hidden (if it is still open) and fire AFTER_HIDE, which in
319
  // turn would cause the dialog to be disposed again (closure only flags an
320
  // object as disposed after the dispose call chain completes, so it doesn't
321
  // prevent recursive dispose calls).
322
  if (this.dialog_ && !this.isDisposingDialog_) {
323
    this.isDisposingDialog_ = true;
324
    this.dialog_.dispose();
325
    this.dialog_ = null;
326
    this.isDisposingDialog_ = false;
327
  }
328
};
329

330