src/widgets/Editor.js

   1 /*!
   2  * Ext JS Library 3.3.1
   3  * Copyright(c) 2006-2010 Sencha Inc.
   4  * licensing@sencha.com
   5  * http://www.sencha.com/license
   6  */
   7 /**
   8  * @class Ext.Editor
   9  * @extends Ext.Component
  10  * A base editor field that handles displaying/hiding on demand and has some built-in sizing and event handling logic.
  11  * @constructor
  12  * Create a new Editor
  13  * @param {Object} config The config object
  14  * @xtype editor
  15  */
  16 Ext.Editor = function(field, config){
  17     if(field.field){
  18         this.field = Ext.create(field.field, 'textfield');
  19         config = Ext.apply({}, field); // copy so we don't disturb original config
  20         delete config.field;
  21     }else{
  22         this.field = field;
  23     }
  24     Ext.Editor.superclass.constructor.call(this, config);
  25 };
  26
  27 Ext.extend(Ext.Editor, Ext.Component, {
  28     /**
  29     * @cfg {Ext.form.Field} field
  30     * The Field object (or descendant) or config object for field
  31     */
  32     /**
  33      * @cfg {Boolean} allowBlur
  34      * True to {@link #completeEdit complete the editing process} if in edit mode when the
  35      * field is blurred. Defaults to <tt>true</tt>.
  36      */
  37     allowBlur: true,
  38     /**
  39      * @cfg {Boolean/String} autoSize
  40      * True for the editor to automatically adopt the size of the underlying field, "width" to adopt the width only,
  41      * or "height" to adopt the height only, "none" to always use the field dimensions. (defaults to false)
  42      */
  43     /**
  44      * @cfg {Boolean} revertInvalid
  45      * True to automatically revert the field value and cancel the edit when the user completes an edit and the field
  46      * validation fails (defaults to true)
  47      */
  48     /**
  49      * @cfg {Boolean} ignoreNoChange
  50      * True to skip the edit completion process (no save, no events fired) if the user completes an edit and
  51      * the value has not changed (defaults to false).  Applies only to string values - edits for other data types
  52      * will never be ignored.
  53      */
  54     /**
  55      * @cfg {Boolean} hideEl
  56      * False to keep the bound element visible while the editor is displayed (defaults to true)
  57      */
  58     /**
  59      * @cfg {Mixed} value
  60      * The data value of the underlying field (defaults to "")
  61      */
  62     value : "",
  63     /**
  64      * @cfg {String} alignment
  65      * The position to align to (see {@link Ext.Element#alignTo} for more details, defaults to "c-c?").
  66      */
  67     alignment: "c-c?",
  68     /**
  69      * @cfg {Array} offsets
  70      * The offsets to use when aligning (see {@link Ext.Element#alignTo} for more details. Defaults to <tt>[0, 0]</tt>.
  71      */
  72     offsets: [0, 0],
  73     /**
  74      * @cfg {Boolean/String} shadow "sides" for sides/bottom only, "frame" for 4-way shadow, and "drop"
  75      * for bottom-right shadow (defaults to "frame")
  76      */
  77     shadow : "frame",
  78     /**
  79      * @cfg {Boolean} constrain True to constrain the editor to the viewport
  80      */
  81     constrain : false,
  82     /**
  83      * @cfg {Boolean} swallowKeys Handle the keydown/keypress events so they don't propagate (defaults to true)
  84      */
  85     swallowKeys : true,
  86     /**
  87      * @cfg {Boolean} completeOnEnter True to complete the edit when the enter key is pressed. Defaults to <tt>true</tt>.
  88      */
  89     completeOnEnter : true,
  90     /**
  91      * @cfg {Boolean} cancelOnEsc True to cancel the edit when the escape key is pressed. Defaults to <tt>true</tt>.
  92      */
  93     cancelOnEsc : true,
  94     /**
  95      * @cfg {Boolean} updateEl True to update the innerHTML of the bound element when the update completes (defaults to false)
  96      */
  97     updateEl : false,
  98
  99     initComponent : function(){
 100         Ext.Editor.superclass.initComponent.call(this);
 101         this.addEvents(
 102             /**
 103              * @event beforestartedit
 104              * Fires when editing is initiated, but before the value changes.  Editing can be canceled by returning
 105              * false from the handler of this event.
 106              * @param {Editor} this
 107              * @param {Ext.Element} boundEl The underlying element bound to this editor
 108              * @param {Mixed} value The field value being set
 109              */
 110             "beforestartedit",
 111             /**
 112              * @event startedit
 113              * Fires when this editor is displayed
 114              * @param {Ext.Element} boundEl The underlying element bound to this editor
 115              * @param {Mixed} value The starting field value
 116              */
 117             "startedit",
 118             /**
 119              * @event beforecomplete
 120              * Fires after a change has been made to the field, but before the change is reflected in the underlying
 121              * field.  Saving the change to the field can be canceled by returning false from the handler of this event.
 122              * Note that if the value has not changed and ignoreNoChange = true, the editing will still end but this
 123              * event will not fire since no edit actually occurred.
 124              * @param {Editor} this
 125              * @param {Mixed} value The current field value
 126              * @param {Mixed} startValue The original field value
 127              */
 128             "beforecomplete",
 129             /**
 130              * @event complete
 131              * Fires after editing is complete and any changed value has been written to the underlying field.
 132              * @param {Editor} this
 133              * @param {Mixed} value The current field value
 134              * @param {Mixed} startValue The original field value
 135              */
 136             "complete",
 137             /**
 138              * @event canceledit
 139              * Fires after editing has been canceled and the editor's value has been reset.
 140              * @param {Editor} this
 141              * @param {Mixed} value The user-entered field value that was discarded
 142              * @param {Mixed} startValue The original field value that was set back into the editor after cancel
 143              */
 144             "canceledit",
 145             /**
 146              * @event specialkey
 147              * Fires when any key related to navigation (arrows, tab, enter, esc, etc.) is pressed.  You can check
 148              * {@link Ext.EventObject#getKey} to determine which key was pressed.
 149              * @param {Ext.form.Field} this
 150              * @param {Ext.EventObject} e The event object
 151              */
 152             "specialkey"
 153         );
 154     },
 155
 156     // private
 157     onRender : function(ct, position){
 158         this.el = new Ext.Layer({
 159             shadow: this.shadow,
 160             cls: "x-editor",
 161             parentEl : ct,
 162             shim : this.shim,
 163             shadowOffset: this.shadowOffset || 4,
 164             id: this.id,
 165             constrain: this.constrain
 166         });
 167         if(this.zIndex){
 168             this.el.setZIndex(this.zIndex);
 169         }
 170         this.el.setStyle("overflow", Ext.isGecko ? "auto" : "hidden");
 171         if(this.field.msgTarget != 'title'){
 172             this.field.msgTarget = 'qtip';
 173         }
 174         this.field.inEditor = true;
 175         this.mon(this.field, {
 176             scope: this,
 177             blur: this.onBlur,
 178             specialkey: this.onSpecialKey
 179         });
 180         if(this.field.grow){
 181             this.mon(this.field, "autosize", this.el.sync,  this.el, {delay:1});
 182         }
 183         this.field.render(this.el).show();
 184         this.field.getEl().dom.name = '';
 185         if(this.swallowKeys){
 186             this.field.el.swallowEvent([
 187                 'keypress', // *** Opera
 188                 'keydown'   // *** all other browsers
 189             ]);
 190         }
 191     },
 192
 193     // private
 194     onSpecialKey : function(field, e){
 195         var key = e.getKey(),
 196             complete = this.completeOnEnter && key == e.ENTER,
 197             cancel = this.cancelOnEsc && key == e.ESC;
 198         if(complete || cancel){
 199             e.stopEvent();
 200             if(complete){
 201                 this.completeEdit();
 202             }else{
 203                 this.cancelEdit();
 204             }
 205             if(field.triggerBlur){
 206                 field.triggerBlur();
 207             }
 208         }
 209         this.fireEvent('specialkey', field, e);
 210     },
 211
 212     /**
 213      * Starts the editing process and shows the editor.
 214      * @param {Mixed} el The element to edit
 215      * @param {String} value (optional) A value to initialize the editor with. If a value is not provided, it defaults
 216       * to the innerHTML of el.
 217      */
 218     startEdit : function(el, value){
 219         if(this.editing){
 220             this.completeEdit();
 221         }
 222         this.boundEl = Ext.get(el);
 223         var v = value !== undefined ? value : this.boundEl.dom.innerHTML;
 224         if(!this.rendered){
 225             this.render(this.parentEl || document.body);
 226         }
 227         if(this.fireEvent("beforestartedit", this, this.boundEl, v) !== false){
 228             this.startValue = v;
 229             this.field.reset();
 230             this.field.setValue(v);
 231             this.realign(true);
 232             this.editing = true;
 233             this.show();
 234         }
 235     },
 236
 237     // private
 238     doAutoSize : function(){
 239         if(this.autoSize){
 240             var sz = this.boundEl.getSize(),
 241                 fs = this.field.getSize();
 242
 243             switch(this.autoSize){
 244                 case "width":
 245                     this.setSize(sz.width, fs.height);
 246                     break;
 247                 case "height":
 248                     this.setSize(fs.width, sz.height);
 249                     break;
 250                 case "none":
 251                     this.setSize(fs.width, fs.height);
 252                     break;
 253                 default:
 254                     this.setSize(sz.width, sz.height);
 255             }
 256         }
 257     },
 258
 259     /**
 260      * Sets the height and width of this editor.
 261      * @param {Number} width The new width
 262      * @param {Number} height The new height
 263      */
 264     setSize : function(w, h){
 265         delete this.field.lastSize;
 266         this.field.setSize(w, h);
 267         if(this.el){
 268             // IE7 in strict mode doesn't size properly.
 269             if(Ext.isGecko2 || Ext.isOpera || (Ext.isIE7 && Ext.isStrict)){
 270                 // prevent layer scrollbars
 271                 this.el.setSize(w, h);
 272             }
 273             this.el.sync();
 274         }
 275     },
 276
 277     /**
 278      * Realigns the editor to the bound field based on the current alignment config value.
 279      * @param {Boolean} autoSize (optional) True to size the field to the dimensions of the bound element.
 280      */
 281     realign : function(autoSize){
 282         if(autoSize === true){
 283             this.doAutoSize();
 284         }
 285         this.el.alignTo(this.boundEl, this.alignment, this.offsets);
 286     },
 287
 288     /**
 289      * Ends the editing process, persists the changed value to the underlying field, and hides the editor.
 290      * @param {Boolean} remainVisible Override the default behavior and keep the editor visible after edit (defaults to false)
 291      */
 292     completeEdit : function(remainVisible){
 293         if(!this.editing){
 294             return;
 295         }
 296         // Assert combo values first
 297         if (this.field.assertValue) {
 298             this.field.assertValue();
 299         }
 300         var v = this.getValue();
 301         if(!this.field.isValid()){
 302             if(this.revertInvalid !== false){
 303                 this.cancelEdit(remainVisible);
 304             }
 305             return;
 306         }
 307         if(String(v) === String(this.startValue) && this.ignoreNoChange){
 308             this.hideEdit(remainVisible);
 309             return;
 310         }
 311         if(this.fireEvent("beforecomplete", this, v, this.startValue) !== false){
 312             v = this.getValue();
 313             if(this.updateEl && this.boundEl){
 314                 this.boundEl.update(v);
 315             }
 316             this.hideEdit(remainVisible);
 317             this.fireEvent("complete", this, v, this.startValue);
 318         }
 319     },
 320
 321     // private
 322     onShow : function(){
 323         this.el.show();
 324         if(this.hideEl !== false){
 325             this.boundEl.hide();
 326         }
 327         this.field.show().focus(false, true);
 328         this.fireEvent("startedit", this.boundEl, this.startValue);
 329     },
 330
 331     /**
 332      * Cancels the editing process and hides the editor without persisting any changes.  The field value will be
 333      * reverted to the original starting value.
 334      * @param {Boolean} remainVisible Override the default behavior and keep the editor visible after
 335      * cancel (defaults to false)
 336      */
 337     cancelEdit : function(remainVisible){
 338         if(this.editing){
 339             var v = this.getValue();
 340             this.setValue(this.startValue);
 341             this.hideEdit(remainVisible);
 342             this.fireEvent("canceledit", this, v, this.startValue);
 343         }
 344     },
 345
 346     // private
 347     hideEdit: function(remainVisible){
 348         if(remainVisible !== true){
 349             this.editing = false;
 350             this.hide();
 351         }
 352     },
 353
 354     // private
 355     onBlur : function(){
 356         // selectSameEditor flag allows the same editor to be started without onBlur firing on itself
 357         if(this.allowBlur === true && this.editing && this.selectSameEditor !== true){
 358             this.completeEdit();
 359         }
 360     },
 361
 362     // private
 363     onHide : function(){
 364         if(this.editing){
 365             this.completeEdit();
 366             return;
 367         }
 368         this.field.blur();
 369         if(this.field.collapse){
 370             this.field.collapse();
 371         }
 372         this.el.hide();
 373         if(this.hideEl !== false){
 374             this.boundEl.show();
 375         }
 376     },
 377
 378     /**
 379      * Sets the data value of the editor
 380      * @param {Mixed} value Any valid value supported by the underlying field
 381      */
 382     setValue : function(v){
 383         this.field.setValue(v);
 384     },
 385
 386     /**
 387      * Gets the data value of the editor
 388      * @return {Mixed} The data value
 389      */
 390     getValue : function(){
 391         return this.field.getValue();
 392     },
 393
 394     beforeDestroy : function(){
 395         Ext.destroyMembers(this, 'field');
 396
 397         delete this.parentEl;
 398         delete this.boundEl;
 399     }
 400 });
 401 Ext.reg('editor', Ext.Editor);