docs/source/Editor.html

   1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-Editor-method-constructor'><span id='Ext-Editor'>/**
   2 </span></span> * @class Ext.Editor
   3  * @extends Ext.Component
   4  *
   5  * &lt;p&gt;
   6  * The Editor class is used to provide inline editing for elements on the page. The editor
   7  * is backed by a {@link Ext.form.field.Field} that will be displayed to edit the underlying content.
   8  * The editor is a floating Component, when the editor is shown it is automatically aligned to
   9  * display over the top of the bound element it is editing. The Editor contains several options
  10  * for how to handle key presses:
  11  * &lt;ul&gt;
  12  * &lt;li&gt;{@link #completeOnEnter}&lt;/li&gt;
  13  * &lt;li&gt;{@link #cancelOnEsc}&lt;/li&gt;
  14  * &lt;li&gt;{@link #swallowKeys}&lt;/li&gt;
  15  * &lt;/ul&gt;
  16  * It also has options for how to use the value once the editor has been activated:
  17  * &lt;ul&gt;
  18  * &lt;li&gt;{@link #revertInvalid}&lt;/li&gt;
  19  * &lt;li&gt;{@link #ignoreNoChange}&lt;/li&gt;
  20  * &lt;li&gt;{@link #updateEl}&lt;/li&gt;
  21  * &lt;/ul&gt;
  22  * Sample usage:
  23  * &lt;/p&gt;
  24  * &lt;pre&gt;&lt;code&gt;
  25 var editor = new Ext.Editor({
  26     updateEl: true, // update the innerHTML of the bound element when editing completes
  27     field: {
  28         xtype: 'textfield'
  29     }
  30 });
  31 var el = Ext.get('my-text'); // The element to 'edit'
  32 editor.startEdit(el); // The value of the field will be taken as the innerHTML of the element.
  33  * &lt;/code&gt;&lt;/pre&gt;
  34  * {@img Ext.Editor/Ext.Editor.png Ext.Editor component}
  35  *
  36  * @constructor
  37  * Create a new Editor
  38  * @param {Object} config The config object
  39  * @xtype editor
  40  */
  41 Ext.define('Ext.Editor', {
  42
  43     /* Begin Definitions */
  44
  45     extend: 'Ext.Component',
  46
  47     alias: 'widget.editor',
  48
  49     requires: ['Ext.layout.component.Editor'],
  50
  51     /* End Definitions */
  52
  53    componentLayout: 'editor',
  54
  55 <span id='Ext-Editor-cfg-field'>    /**
  56 </span>    * @cfg {Ext.form.field.Field} field
  57     * The Field object (or descendant) or config object for field
  58     */
  59
  60 <span id='Ext-Editor-cfg-allowBlur'>    /**
  61 </span>     * @cfg {Boolean} allowBlur
  62      * True to {@link #completeEdit complete the editing process} if in edit mode when the
  63      * field is blurred. Defaults to &lt;tt&gt;true&lt;/tt&gt;.
  64      */
  65     allowBlur: true,
  66
  67 <span id='Ext-Editor-cfg-autoSize'>    /**
  68 </span>     * @cfg {Boolean/Object} autoSize
  69      * True for the editor to automatically adopt the size of the underlying field. Otherwise, an object
  70      * can be passed to indicate where to get each dimension. The available properties are 'boundEl' and
  71      * 'field'. If a dimension is not specified, it will use the underlying height/width specified on
  72      * the editor object.
  73      * Examples:
  74      * &lt;pre&gt;&lt;code&gt;
  75 autoSize: true // The editor will be sized to the height/width of the field
  76
  77 height: 21,
  78 autoSize: {
  79     width: 'boundEl' // The width will be determined by the width of the boundEl, the height from the editor (21)
  80 }
  81
  82 autoSize: {
  83     width: 'field', // Width from the field
  84     height: 'boundEl' // Height from the boundEl
  85 }
  86      * &lt;/pre&gt;&lt;/code&gt;
  87      */
  88
  89 <span id='Ext-Editor-cfg-revertInvalid'>    /**
  90 </span>     * @cfg {Boolean} revertInvalid
  91      * True to automatically revert the field value and cancel the edit when the user completes an edit and the field
  92      * validation fails (defaults to true)
  93      */
  94     revertInvalid: true,
  95
  96 <span id='Ext-Editor-cfg-ignoreNoChange'>    /**
  97 </span>     * @cfg {Boolean} ignoreNoChange
  98      * True to skip the edit completion process (no save, no events fired) if the user completes an edit and
  99      * the value has not changed (defaults to false).  Applies only to string values - edits for other data types
 100      * will never be ignored.
 101      */
 102
 103 <span id='Ext-Editor-cfg-hideEl'>    /**
 104 </span>     * @cfg {Boolean} hideEl
 105      * False to keep the bound element visible while the editor is displayed (defaults to true)
 106      */
 107
 108 <span id='Ext-Editor-cfg-value'>    /**
 109 </span>     * @cfg {Mixed} value
 110      * The data value of the underlying field (defaults to &quot;&quot;)
 111      */
 112     value : '',
 113
 114 <span id='Ext-Editor-cfg-alignment'>    /**
 115 </span>     * @cfg {String} alignment
 116      * The position to align to (see {@link Ext.core.Element#alignTo} for more details, defaults to &quot;c-c?&quot;).
 117      */
 118     alignment: 'c-c?',
 119
 120 <span id='Ext-Editor-cfg-offsets'>    /**
 121 </span>     * @cfg {Array} offsets
 122      * The offsets to use when aligning (see {@link Ext.core.Element#alignTo} for more details. Defaults to &lt;tt&gt;[0, 0]&lt;/tt&gt;.
 123      */
 124     offsets: [0, 0],
 125
 126 <span id='Ext-Editor-cfg-shadow'>    /**
 127 </span>     * @cfg {Boolean/String} shadow &quot;sides&quot; for sides/bottom only, &quot;frame&quot; for 4-way shadow, and &quot;drop&quot;
 128      * for bottom-right shadow (defaults to &quot;frame&quot;)
 129      */
 130     shadow : 'frame',
 131
 132 <span id='Ext-Editor-cfg-constrain'>    /**
 133 </span>     * @cfg {Boolean} constrain True to constrain the editor to the viewport
 134      */
 135     constrain : false,
 136
 137 <span id='Ext-Editor-cfg-swallowKeys'>    /**
 138 </span>     * @cfg {Boolean} swallowKeys Handle the keydown/keypress events so they don't propagate (defaults to true)
 139      */
 140     swallowKeys : true,
 141
 142 <span id='Ext-Editor-cfg-completeOnEnter'>    /**
 143 </span>     * @cfg {Boolean} completeOnEnter True to complete the edit when the enter key is pressed. Defaults to &lt;tt&gt;true&lt;/tt&gt;.
 144      */
 145     completeOnEnter : true,
 146
 147 <span id='Ext-Editor-cfg-cancelOnEsc'>    /**
 148 </span>     * @cfg {Boolean} cancelOnEsc True to cancel the edit when the escape key is pressed. Defaults to &lt;tt&gt;true&lt;/tt&gt;.
 149      */
 150     cancelOnEsc : true,
 151
 152 <span id='Ext-Editor-cfg-updateEl'>    /**
 153 </span>     * @cfg {Boolean} updateEl True to update the innerHTML of the bound element when the update completes (defaults to false)
 154      */
 155     updateEl : false,
 156
 157 <span id='Ext-Editor-cfg-parentEl'>    /**
 158 </span>     * @cfg {Mixed} parentEl An element to render to. Defaults to the &lt;tt&gt;document.body&lt;/tt&gt;.
 159      */
 160
 161     // private overrides
 162     hidden: true,
 163     baseCls: Ext.baseCSSPrefix + 'editor',
 164
 165     initComponent : function() {
 166         var me = this,
 167             field = me.field = Ext.ComponentManager.create(me.field, 'textfield');
 168
 169         Ext.apply(field, {
 170             inEditor: true,
 171             msgTarget: field.msgTarget == 'title' ? 'title' :  'qtip'
 172         });
 173         me.mon(field, {
 174             scope: me,
 175             blur: {
 176                 fn: me.onBlur,
 177                 // slight delay to avoid race condition with startEdits (e.g. grid view refresh)
 178                 delay: 1
 179             },
 180             specialkey: me.onSpecialKey
 181         });
 182
 183         if (field.grow) {
 184             me.mon(field, 'autosize', me.onAutoSize,  me, {delay: 1});
 185         }
 186         me.floating = {
 187             constrain: me.constrain
 188         };
 189
 190         me.callParent(arguments);
 191
 192         me.addEvents(
 193 <span id='Ext-Editor-event-beforestartedit'>            /**
 194 </span>             * @event beforestartedit
 195              * Fires when editing is initiated, but before the value changes.  Editing can be canceled by returning
 196              * false from the handler of this event.
 197              * @param {Ext.Editor} this
 198              * @param {Ext.core.Element} boundEl The underlying element bound to this editor
 199              * @param {Mixed} value The field value being set
 200              */
 201             'beforestartedit',
 202 <span id='Ext-Editor-event-startedit'>            /**
 203 </span>             * @event startedit
 204              * Fires when this editor is displayed
 205              * @param {Ext.Editor} this
 206              * @param {Ext.core.Element} boundEl The underlying element bound to this editor
 207              * @param {Mixed} value The starting field value
 208              */
 209             'startedit',
 210 <span id='Ext-Editor-event-beforecomplete'>            /**
 211 </span>             * @event beforecomplete
 212              * Fires after a change has been made to the field, but before the change is reflected in the underlying
 213              * field.  Saving the change to the field can be canceled by returning false from the handler of this event.
 214              * Note that if the value has not changed and ignoreNoChange = true, the editing will still end but this
 215              * event will not fire since no edit actually occurred.
 216              * @param {Editor} this
 217              * @param {Mixed} value The current field value
 218              * @param {Mixed} startValue The original field value
 219              */
 220             'beforecomplete',
 221 <span id='Ext-Editor-event-complete'>            /**
 222 </span>             * @event complete
 223              * Fires after editing is complete and any changed value has been written to the underlying field.
 224              * @param {Ext.Editor} this
 225              * @param {Mixed} value The current field value
 226              * @param {Mixed} startValue The original field value
 227              */
 228             'complete',
 229 <span id='Ext-Editor-event-canceledit'>            /**
 230 </span>             * @event canceledit
 231              * Fires after editing has been canceled and the editor's value has been reset.
 232              * @param {Ext.Editor} this
 233              * @param {Mixed} value The user-entered field value that was discarded
 234              * @param {Mixed} startValue The original field value that was set back into the editor after cancel
 235              */
 236             'canceledit',
 237 <span id='Ext-Editor-event-specialkey'>            /**
 238 </span>             * @event specialkey
 239              * Fires when any key related to navigation (arrows, tab, enter, esc, etc.) is pressed.  You can check
 240              * {@link Ext.EventObject#getKey} to determine which key was pressed.
 241              * @param {Ext.Editor} this
 242              * @param {Ext.form.field.Field} The field attached to this editor
 243              * @param {Ext.EventObject} event The event object
 244              */
 245             'specialkey'
 246         );
 247     },
 248
 249     // private
 250     onAutoSize: function(){
 251         this.doComponentLayout();
 252     },
 253
 254     // private
 255     onRender : function(ct, position) {
 256         var me = this,
 257             field = me.field;
 258
 259         me.callParent(arguments);
 260
 261         field.render(me.el);
 262         //field.hide();
 263         // Ensure the field doesn't get submitted as part of any form
 264         field.inputEl.dom.name = '';
 265         if (me.swallowKeys) {
 266             field.inputEl.swallowEvent([
 267                 'keypress', // *** Opera
 268                 'keydown'   // *** all other browsers
 269             ]);
 270         }
 271     },
 272
 273     // private
 274     onSpecialKey : function(field, event) {
 275         var me = this,
 276             key = event.getKey(),
 277             complete = me.completeOnEnter &amp;&amp; key == event.ENTER,
 278             cancel = me.cancelOnEsc &amp;&amp; key == event.ESC;
 279
 280         if (complete || cancel) {
 281             event.stopEvent();
 282             // Must defer this slightly to prevent exiting edit mode before the field's own
 283             // key nav can handle the enter key, e.g. selecting an item in a combobox list
 284             Ext.defer(function() {
 285                 if (complete) {
 286                     me.completeEdit();
 287                 } else {
 288                     me.cancelEdit();
 289                 }
 290                 if (field.triggerBlur) {
 291                     field.triggerBlur();
 292                 }
 293             }, 10);
 294         }
 295
 296         this.fireEvent('specialkey', this, field, event);
 297     },
 298
 299 <span id='Ext-Editor-method-startEdit'>    /**
 300 </span>     * Starts the editing process and shows the editor.
 301      * @param {Mixed} el The element to edit
 302      * @param {String} value (optional) A value to initialize the editor with. If a value is not provided, it defaults
 303       * to the innerHTML of el.
 304      */
 305     startEdit : function(el, value) {
 306         var me = this,
 307             field = me.field;
 308
 309         me.completeEdit();
 310         me.boundEl = Ext.get(el);
 311         value = Ext.isDefined(value) ? value : me.boundEl.dom.innerHTML;
 312
 313         if (!me.rendered) {
 314             me.render(me.parentEl || document.body);
 315         }
 316
 317         if (me.fireEvent('beforestartedit', me, me.boundEl, value) !== false) {
 318             me.startValue = value;
 319             me.show();
 320             field.reset();
 321             field.setValue(value);
 322             me.realign(true);
 323             field.focus(false, 10);
 324             if (field.autoSize) {
 325                 field.autoSize();
 326             }
 327             me.editing = true;
 328         }
 329     },
 330
 331 <span id='Ext-Editor-method-realign'>    /**
 332 </span>     * Realigns the editor to the bound field based on the current alignment config value.
 333      * @param {Boolean} autoSize (optional) True to size the field to the dimensions of the bound element.
 334      */
 335     realign : function(autoSize) {
 336         var me = this;
 337         if (autoSize === true) {
 338             me.doComponentLayout();
 339         }
 340         me.alignTo(me.boundEl, me.alignment, me.offsets);
 341     },
 342
 343 <span id='Ext-Editor-method-completeEdit'>    /**
 344 </span>     * Ends the editing process, persists the changed value to the underlying field, and hides the editor.
 345      * @param {Boolean} remainVisible Override the default behavior and keep the editor visible after edit (defaults to false)
 346      */
 347     completeEdit : function(remainVisible) {
 348         var me = this,
 349             field = me.field,
 350             value;
 351
 352         if (!me.editing) {
 353             return;
 354         }
 355
 356         // Assert combo values first
 357         if (field.assertValue) {
 358             field.assertValue();
 359         }
 360
 361         value = me.getValue();
 362         if (!field.isValid()) {
 363             if (me.revertInvalid !== false) {
 364                 me.cancelEdit(remainVisible);
 365             }
 366             return;
 367         }
 368
 369         if (String(value) === String(me.startValue) &amp;&amp; me.ignoreNoChange) {
 370             me.hideEdit(remainVisible);
 371             return;
 372         }
 373
 374         if (me.fireEvent('beforecomplete', me, value, me.startValue) !== false) {
 375             // Grab the value again, may have changed in beforecomplete
 376             value = me.getValue();
 377             if (me.updateEl &amp;&amp; me.boundEl) {
 378                 me.boundEl.update(value);
 379             }
 380             me.hideEdit(remainVisible);
 381             me.fireEvent('complete', me, value, me.startValue);
 382         }
 383     },
 384
 385     // private
 386     onShow : function() {
 387         var me = this;
 388
 389         me.callParent(arguments);
 390         if (me.hideEl !== false) {
 391             me.boundEl.hide();
 392         }
 393         me.fireEvent(&quot;startedit&quot;, me.boundEl, me.startValue);
 394     },
 395
 396 <span id='Ext-Editor-method-cancelEdit'>    /**
 397 </span>     * Cancels the editing process and hides the editor without persisting any changes.  The field value will be
 398      * reverted to the original starting value.
 399      * @param {Boolean} remainVisible Override the default behavior and keep the editor visible after
 400      * cancel (defaults to false)
 401      */
 402     cancelEdit : function(remainVisible) {
 403         var me = this,
 404             startValue = me.startValue,
 405             value;
 406
 407         if (me.editing) {
 408             value = me.getValue();
 409             me.setValue(startValue);
 410             me.hideEdit(remainVisible);
 411             me.fireEvent('canceledit', me, value, startValue);
 412         }
 413     },
 414
 415     // private
 416     hideEdit: function(remainVisible) {
 417         if (remainVisible !== true) {
 418             this.editing = false;
 419             this.hide();
 420         }
 421     },
 422
 423     // private
 424     onBlur : function() {
 425         var me = this;
 426
 427         // selectSameEditor flag allows the same editor to be started without onBlur firing on itself
 428         if(me.allowBlur === true &amp;&amp; me.editing &amp;&amp; me.selectSameEditor !== true) {
 429             me.completeEdit();
 430         }
 431     },
 432
 433     // private
 434     onHide : function() {
 435         var me = this,
 436             field = me.field;
 437
 438         if (me.editing) {
 439             me.completeEdit();
 440             return;
 441         }
 442         field.blur();
 443         if (field.collapse) {
 444             field.collapse();
 445         }
 446
 447         //field.hide();
 448         if (me.hideEl !== false) {
 449             me.boundEl.show();
 450         }
 451         me.callParent(arguments);
 452     },
 453
 454 <span id='Ext-Editor-method-setValue'>    /**
 455 </span>     * Sets the data value of the editor
 456      * @param {Mixed} value Any valid value supported by the underlying field
 457      */
 458     setValue : function(value) {
 459         this.field.setValue(value);
 460     },
 461
 462 <span id='Ext-Editor-method-getValue'>    /**
 463 </span>     * Gets the data value of the editor
 464      * @return {Mixed} The data value
 465      */
 466     getValue : function() {
 467         return this.field.getValue();
 468     },
 469
 470     beforeDestroy : function() {
 471         var me = this;
 472
 473         Ext.destroy(me.field);
 474         delete me.field;
 475         delete me.parentEl;
 476         delete me.boundEl;
 477
 478         me.callParent(arguments);
 479     }
 480 });</pre></pre></body></html>