src/widgets/Editor.js

   1 /*!
   2  * Ext JS Library 3.2.0
   3  * Copyright(c) 2006-2010 Ext JS, Inc.
   4  * licensing@extjs.com
   5  * http://www.extjs.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             if(Ext.isGecko2 || Ext.isOpera){
 269                 // prevent layer scrollbars
 270                 this.el.setSize(w, h);
 271             }
 272             this.el.sync();
 273         }
 274     },
 275
 276     /**
 277      * Realigns the editor to the bound field based on the current alignment config value.
 278      * @param {Boolean} autoSize (optional) True to size the field to the dimensions of the bound element.
 279      */
 280     realign : function(autoSize){
 281         if(autoSize === true){
 282             this.doAutoSize();
 283         }
 284         this.el.alignTo(this.boundEl, this.alignment, this.offsets);
 285     },
 286
 287     /**
 288      * Ends the editing process, persists the changed value to the underlying field, and hides the editor.
 289      * @param {Boolean} remainVisible Override the default behavior and keep the editor visible after edit (defaults to false)
 290      */
 291     completeEdit : function(remainVisible){
 292         if(!this.editing){
 293             return;
 294         }
 295         // Assert combo values first
 296         if (this.field.assertValue) {
 297             this.field.assertValue();
 298         }
 299         var v = this.getValue();
 300         if(!this.field.isValid()){
 301             if(this.revertInvalid !== false){
 302                 this.cancelEdit(remainVisible);
 303             }
 304             return;
 305         }
 306         if(String(v) === String(this.startValue) && this.ignoreNoChange){
 307             this.hideEdit(remainVisible);
 308             return;
 309         }
 310         if(this.fireEvent("beforecomplete", this, v, this.startValue) !== false){
 311             v = this.getValue();
 312             if(this.updateEl && this.boundEl){
 313                 this.boundEl.update(v);
 314             }
 315             this.hideEdit(remainVisible);
 316             this.fireEvent("complete", this, v, this.startValue);
 317         }
 318     },
 319
 320     // private
 321     onShow : function(){
 322         this.el.show();
 323         if(this.hideEl !== false){
 324             this.boundEl.hide();
 325         }
 326         this.field.show().focus(false, true);
 327         this.fireEvent("startedit", this.boundEl, this.startValue);
 328     },
 329
 330     /**
 331      * Cancels the editing process and hides the editor without persisting any changes.  The field value will be
 332      * reverted to the original starting value.
 333      * @param {Boolean} remainVisible Override the default behavior and keep the editor visible after
 334      * cancel (defaults to false)
 335      */
 336     cancelEdit : function(remainVisible){
 337         if(this.editing){
 338             var v = this.getValue();
 339             this.setValue(this.startValue);
 340             this.hideEdit(remainVisible);
 341             this.fireEvent("canceledit", this, v, this.startValue);
 342         }
 343     },
 344
 345     // private
 346     hideEdit: function(remainVisible){
 347         if(remainVisible !== true){
 348             this.editing = false;
 349             this.hide();
 350         }
 351     },
 352
 353     // private
 354     onBlur : function(){
 355         // selectSameEditor flag allows the same editor to be started without onBlur firing on itself
 356         if(this.allowBlur === true && this.editing && this.selectSameEditor !== true){
 357             this.completeEdit();
 358         }
 359     },
 360
 361     // private
 362     onHide : function(){
 363         if(this.editing){
 364             this.completeEdit();
 365             return;
 366         }
 367         this.field.blur();
 368         if(this.field.collapse){
 369             this.field.collapse();
 370         }
 371         this.el.hide();
 372         if(this.hideEl !== false){
 373             this.boundEl.show();
 374         }
 375     },
 376
 377     /**
 378      * Sets the data value of the editor
 379      * @param {Mixed} value Any valid value supported by the underlying field
 380      */
 381     setValue : function(v){
 382         this.field.setValue(v);
 383     },
 384
 385     /**
 386      * Gets the data value of the editor
 387      * @return {Mixed} The data value
 388      */
 389     getValue : function(){
 390         return this.field.getValue();
 391     },
 392
 393     beforeDestroy : function(){
 394         Ext.destroyMembers(this, 'field');
 395
 396         delete this.parentEl;
 397         delete this.boundEl;
 398     }
 399 });
 400 Ext.reg('editor', Ext.Editor);