Home

# Class goog.editor.Field

This class encapsulates an editable field. event: load Fires when the field is loaded event: unload Fires when the field is unloaded (made not editable) event: beforechange Fires before the content of the field might change event: delayedchange Fires a short time after field has changed. If multiple change events happen really close to each other only the last one will trigger the delayedchange event. event: beforefocus Fires before the field becomes active event: focus Fires when the field becomes active. Fires after the blur event event: blur Fires when the field becomes inactive TODO: figure out if blur or beforefocus fires first in IE and make FF match

extends goog.events.EventTarget

Instance Method Summary
| `addListener((Array.<string>|null|string) type, ?Function listener, boolean= opt_capture, ?Object= opt_handler)` Registers a keyboard event listener on the field. This is necessary for Gecko since the fields are contained in an iFrame and there is no way to auto-propagate key events up to the main window.
| `attachIframe(?HTMLIFrameElement iframe)` Given the original field element, and the iframe that is destined to become the editable field, styles them appropriately and add the iframe to the dom.
| `attachWrapper(?goog.Disposable wrapper)` Attach an wrapper to this field, to be thrown out when the field is disposed.
| `clearDelayedChange()` Don't wait for the timer and just fire the delayed change event if it's pending.
| `clearFieldLoadListener_()` Clears fieldLoadListener for a field. Must be called even (especially?) if the field is not yet loaded and therefore not in this.fieldMap_
| `clearListeners_()` Stops all listeners and timers.

`debounceEvent(?goog.editor.Field.EventType eventType)`

Block an event for a short amount of time. Intended for the situation where an event pair fires in quick succession (e.g., mousedown/mouseup, keydown/keyup, focus/blur), and we want the second event in the pair to get "debounced." WARNING: This should never be used to solve race conditions or for mission-critical actions. It should only be used for UI improvements, where it's okay if the behavior is non-deterministic.

| `dispatchBeforeChange()` This dispatches the beforechange event on the editable field
| `dispatchBeforeFocus_()` Dispatches a before focus event.
| `dispatchBeforeTab_(?goog.events.BrowserEvent e) ⇒ boolean` This dispatches the beforetab event on the editable field. If this event is cancelled, then the default tab behavior is prevented.
| `dispatchBlur()` Dispatches a blur event.
| `dispatchChange(boolean= opt_noDelay)` Dispatches the appropriate set of change events. This only fires synchronous change events in blended-mode, iframe-using mozilla. It just starts the appropriate timer for goog.editor.Field.EventType.DELAYEDCHANGE. This also starts up change events again if they were stopped.
| `dispatchCommandValueChange(?Array.<string>= opt_commands)` Dispatches a command value change event.
| `dispatchDelayedChange_()` Dispatch a delayed change event.
| `dispatchFocusAndBeforeFocus_()` Dispatch beforefocus and focus for FF. Note that both of these actually happen in the document's "focus" event. Unfortunately, we don't actually have a way of getting in before the focus event in FF (boo! hiss!). In IE, we use onfocusin for before focus and onfocus for focus.
| `dispatchFocus_()` Dispatches a focus event.
| `dispatchLoadEvent_()` Signal that the field is loaded and ready to use. Change events now are in effect.
| `dispatchSelectionChangeEvent(?goog.events.BrowserEvent= opt_e, ?Node= opt_target)` Dispatch a selection change event, optionally caused by the given browser event or selecting the given target.

`disposeInternal()`

Unattach listeners from this object. Classes that extend EventTarget may need to override this method in order to remove references to DOM Elements and additional listeners, it should be something like this:

    MyClass.prototype.disposeInternal = function() {
    MyClass.superClass_.disposeInternal.call(this);
    // Dispose logic for MyClass
    };

| `execCommand(string command, <Any Type> var_args) ⇒ <Any Type>` Executes an editing command as per the registered plugins.
| `focus()` Gives the field focus.
| `focusAndPlaceCursorAtStart()` Gives the field focus and places the cursor at the start of the field.
| `getAppWindow() ⇒ !Window` Returns the "application" window, where dialogs and bubbles should be rendered.
| `getBaseZindex() ⇒ number` Returns the zindex of the base level of the field.
| `getCleanContents() ⇒ string` Retrieve the HTML contents of a field. Do NOT just get the innerHTML of a field directly--there's a lot of processing that needs to happen.
| `getEditableDomHelper() ⇒ ?goog.dom.DomHelper`
| `getEditableIframe() ⇒ ?HTMLIFrameElement`
| `getElement() ⇒ ?Element` Returns the editable DOM element or null if this field is not editable. On IE or Safari this is the element with contentEditable=true (in whitebox mode, the iFrame body). On Gecko this is the iFrame body TODO(user): How do we word this for subclass version?
| `getFieldCopy() ⇒ ?Element` Get the copy of the editable field element, which has the innerHTML set correctly.
| `getFieldFormatInfo(?Object extraStyles) ⇒ ?goog.editor.icontent.FieldFormatInfo`
| `getHashCode() ⇒ string` Returns a string usable as a hash code for this field. For field's that were created with an id, the hash code is guaranteed to be the id. TODO(user): I think we can get rid of this. Seems only used from editor.
| `getIframeAttributes() ⇒ ?Object`
| `getInjectableContents(?string contents, ?Object styles) ⇒ string` Returns prepared contents that can be injected into the editable field.
| `getOriginalElement() ⇒ ?Element` Returns original DOM element that is being made editable by Trogedit or null if that element has not yet been found in the appropriate document.
| `getPluginByClassId(string classId) ⇒ ?goog.editor.Plugin` Returns the registered plugin with the given classId.
| `getRange() ⇒ ?goog.dom.AbstractRange`
| `handleBeforeChangeKeyEvent_(?goog.events.BrowserEvent e) ⇒ boolean` Handle before change key events and fire the beforetab event if appropriate. This needs to happen on keydown in IE and keypress in FF.
| `handleChange()` Handle a change in the Editable Field. Marks the field has modified, dispatches the change event on the editable field (moz only), starts the timer for the delayed change event. Note that these actions only occur if the proper events are not stopped.
| `handleDomAttrChange(?Function handler, ?goog.events.BrowserEvent browserEvent)` Fires a change event only if the attribute change effects the editiable field. We ignore events that are internal browser events (ie scrollbar state change)
| `handleDrop_(?goog.events.BrowserEvent e)` Handle drop events. Deal with focus/selection issues and set the document as changed.
| `handleFieldLoad()` Handle the loading of the field (e.g. once the field is ready to setup). TODO(user): this should probably just be moved into dispatchLoadEvent_.
| `handleKeyDown_(?goog.events.BrowserEvent e)` Handles keydown on the field.
| `handleKeyPress_(?goog.events.BrowserEvent e)` Handles keypress on the field.
| `handleKeyUp_(?goog.events.BrowserEvent e)` Handles keyup on the field.
| `handleKeyboardShortcut_(?goog.events.BrowserEvent e)` Handles keyboard shortcuts on the field. Note that we bake this into our handleKeyPress/handleKeyDown rather than using goog.events.KeyHandler or goog.ui.KeyboardShortcutHandler for performance reasons. Since these are handled on every key stroke, we do not want to be going out to the event system every time.
| `handleMouseDown_(?goog.events.BrowserEvent e)` Handle mouse down inside the editable field.
| `handleMouseUp_(?goog.events.BrowserEvent e)` Handle mouse up inside the editable field.
| `handleMutationEventGecko_((Event|goog.events.BrowserEvent|null) e)` Handle a mutation event.
| `handleSelectionChangeTimer_()` Dispatch a selection change event using a browser event that was asynchronously saved earlier.
| `iframeFieldLoadHandler(?HTMLIFrameElement iframe, string innerHtml, ?Object styles)` The function to call when the editable iframe loads.
| `inModalMode() ⇒ boolean`
| `injectContents(?string contents, ?Element field)` Prepare the given contents, then inject them into the editable field.
| `installStyles()` Installs styles if needed. Only writes styles when they can't be written inline directly into the field.
| `invokeOp_(?goog.editor.Plugin.Op op, <Any Type> var_args)` Invoke this operation on all plugins with the given arguments.
| `invokeShortCircuitingOp_(?goog.editor.Plugin.Op op, <Any Type> var_args) ⇒ boolean` Calls all the plugins of the given operation, in sequence, with the given arguments. This is short-circuiting: once one plugin cancels the event, no more plugins will be invoked.
| `isEventStopped(?goog.editor.Field.EventType eventType) ⇒ boolean` Checks if the event of the given type has stopped being dispatched
| `isLoaded() ⇒ boolean`
| `isLoading() ⇒ boolean`
| `isModified(boolean= opt_useIsEverModified) ⇒ boolean` Checks the modified state of the field. Note: Changes that take place while the goog.editor.Field.EventType.CHANGE event is stopped do not effect the modified state.
| `isSelectionEditable() ⇒ boolean`
| `isUneditable() ⇒ boolean`
| `makeEditable(string= opt_iframeSrc)` Makes a field editable.
| `makeEditableInternal(string= opt_iframeSrc)` Handles actually making something editable - creating necessary nodes, injecting content, etc.
| `makeIframeField_(string= opt_iframeSrc)` Start the editable iframe creation process for Mozilla or IE whitebox. The iframes load asynchronously.
| `makeUneditable(boolean= opt_skipRestore)` Closes the field and cancels all pending change timers. Note that this means that if a change event has not fired yet, it will not fire. Clients should check fieldOj.isModified() if they depend on the final change event. Throws an error if the field is already uneditable.

`manipulateDom(function (): ? func, boolean= opt_preventDelayedChange, ?Object= opt_handler)`

Calls a function to manipulate the dom of this field. This method should be used whenever Trogedit clients need to modify the dom of the field, so that delayed change events are handled appropriately. Extra delayed change events will cause undesired states to be added to the undo-redo stack. This method will always fire at most one delayed change event, depending on the value of {@code opt_preventDelayedChange}.

| `placeCursorAtStart()` Place the cursor at the start of this field. It's recommended that you only use this method (and manipulate the selection in general) when there is not an existing selection in the field.
| `queryCommandValue((Array.<string>|null|string) commands) ⇒ <Any Type>` Gets the value of command(s).
| `queryCommandValueInternal_(string command, boolean isEditable) ⇒ <Any Type>` Gets the value of this command.
| `reduceOp_(?goog.editor.Plugin.Op op, string arg, <Any Type> var_args) ⇒ string` Reduce this argument over all plugins. The result of each plugin invocation will be passed to the next plugin invocation. See goog.array.reduce.
| `registerPlugin(?goog.editor.Plugin plugin)` Registers the plugin with the editable field.
| `removeAllWrappers()` Removes all wrappers and destroys them.
| `resetOriginalElemProperties()` Reset the properties on the original field element to how it was before it was made editable.
| `restoreDom()` Restores the dom to how it was before being made editable.
| `setAppWindow(!Window appWindow)` Sets the application window.
| `setBaseZindex(number zindex)` Sets the zIndex that the field should be based off of. TODO(user): Get rid of this completely. Here for Sites. Should this be set directly on UI plugins?
| `setHtml(boolean addParas, ?string html, boolean= opt_dontFireDelayedChange, boolean= opt_applyLorem)` Sets the contents of the field.
| `setInitialStyle(string cssText)` Sets the value that will replace the style attribute of this field's element when the field is made non-editable. This method is called with the current value of the style attribute when the field is made editable.
| `setInnerHtml_(?string html)` Sets the inner HTML of the field. Works on both editable and uneditable fields.
| `setModalMode(boolean inModalMode)`
| `setupChangeListeners_()` Initialize listeners on the field.
| `setupFieldObject(?Element field)` Sets up the field object and window util of this field, and enables this editable field with all registered plugins. This is essential to the initialization of the field. It must be called when the field becomes fully loaded and editable.
| `setupMutationEventHandlersGecko()` Mutation events tell us when something has changed for mozilla.
| `shouldLoadAsynchronously() ⇒ boolean` Returns true if the field needs to be loaded asynchrnously.
| `startChangeEvents(boolean= opt_fireChange, boolean= opt_fireDelayedChange)` Start change events again and fire once if desired.
| `startEvent(?goog.editor.Field.EventType eventType)` Re-starts the event of the given type being dispatched, if it had previously been stopped with stopEvent().
| `stopChangeEvents(boolean= opt_stopChange, boolean= opt_stopDelayedChange)` Temporarily ignore change events. If the time has already been set, it will fire immediately now. Further setting of the timer is stopped and dispatching of events is stopped until startChangeEvents is called.
| `stopEvent(?goog.editor.Field.EventType eventType)` Stops the event of the given type from being dispatched.
| `tearDownFieldObject_()` Help make the field not editable by setting internal data structures to null, and disabling this field with all registered plugins.
| `turnOnDesignModeGecko()` Attemps to turn on designMode for a document. This function can fail under certain circumstances related to the load event, and will throw an exception.
| `unregisterPlugin(?goog.editor.Plugin plugin)` Unregisters the plugin with this field.
| `writeIframeContent(?HTMLIFrameElement iframe, string innerHtml, ?Object extraStyles)` Writes the html content into the iframe. Handles writing any aditional styling as well.

Static Method Summary
| `cancelLinkClick_(?goog.events.BrowserEvent e)` Event handler for clicks in browsers that will follow a link when the user clicks, even if it's editable. We stop the click manually
| `getActiveFieldId() ⇒ ?string`
| `isGeneratingKey_(?goog.events.BrowserEvent e, boolean testAllKeys) ⇒ boolean` Returns true if the keypress generates a change in contents.
| `isSpecialGeneratingKey_(?goog.events.BrowserEvent e) ⇒ boolean` Returns true if the keypress generates a change in the contents. due to a special key listed in goog.editor.Field.KEYS_CAUSING_CHANGES_
| `setActiveFieldId(?string fieldId)` Sets the active field id.