docs/source/Editor.html

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