docs/source/Labelable.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-form.Labelable'>/**
   2 </span> * @class Ext.form.Labelable
   3
   4 A mixin which allows a component to be configured and decorated with a label and/or error message as is
   5 common for form fields. This is used by e.g. {@link Ext.form.field.Base} and {@link Ext.form.FieldContainer}
   6 to let them be managed by the Field layout.
   7
   8 **NOTE**: This mixin is mainly for internal library use and most users should not need to use it directly. It
   9 is more likely you will want to use one of the component classes that import this mixin, such as
  10 {@link Ext.form.field.Base} or {@link Ext.form.FieldContainer}.
  11
  12 Use of this mixin does not make a component a field in the logical sense, meaning it does not provide any
  13 logic or state related to values or validation; that is handled by the related {@link Ext.form.field.Field}
  14 mixin. These two mixins may be used separately (for example {@link Ext.form.FieldContainer} is Labelable but not a
  15 Field), or in combination (for example {@link Ext.form.field.Base} implements both and has logic for connecting the
  16 two.)
  17
  18 Component classes which use this mixin should use the Field layout
  19 or a derivation thereof to properly size and position the label and message according to the component config.
  20 They must also call the {@link #initLabelable} method during component initialization to ensure the mixin gets
  21 set up correctly.
  22
  23  * @markdown
  24  * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
  25  */
  26 Ext.define(&quot;Ext.form.Labelable&quot;, {
  27     requires: ['Ext.XTemplate'],
  28
  29 <span id='Ext-form.Labelable-cfg-labelableRenderTpl'>    /**
  30 </span>     * @cfg {Array/String/Ext.XTemplate} labelableRenderTpl
  31      * The rendering template for the field decorations. Component classes using this mixin should include
  32      * logic to use this as their {@link Ext.AbstractComponent#renderTpl renderTpl}, and implement the
  33      * {@link #getSubTplMarkup} method to generate the field body content.
  34      */
  35     labelableRenderTpl: [
  36         '&lt;tpl if=&quot;!hideLabel &amp;&amp; !(!fieldLabel &amp;&amp; hideEmptyLabel)&quot;&gt;',
  37             '&lt;label&lt;tpl if=&quot;inputId&quot;&gt; for=&quot;{inputId}&quot;&lt;/tpl&gt; class=&quot;{labelCls}&quot;&lt;tpl if=&quot;labelStyle&quot;&gt; style=&quot;{labelStyle}&quot;&lt;/tpl&gt;&gt;',
  38                 '&lt;tpl if=&quot;fieldLabel&quot;&gt;{fieldLabel}{labelSeparator}&lt;/tpl&gt;',
  39             '&lt;/label&gt;',
  40         '&lt;/tpl&gt;',
  41         '&lt;div class=&quot;{baseBodyCls} {fieldBodyCls}&quot;&lt;tpl if=&quot;inputId&quot;&gt; id=&quot;{baseBodyCls}-{inputId}&quot;&lt;/tpl&gt; role=&quot;presentation&quot;&gt;{subTplMarkup}&lt;/div&gt;',
  42         '&lt;div class=&quot;{errorMsgCls}&quot; style=&quot;display:none&quot;&gt;&lt;/div&gt;',
  43         '&lt;div class=&quot;{clearCls}&quot; role=&quot;presentation&quot;&gt;&lt;!-- --&gt;&lt;/div&gt;',
  44         {
  45             compiled: true,
  46             disableFormats: true
  47         }
  48     ],
  49
  50 <span id='Ext-form.Labelable-cfg-activeErrorsTpl'>    /**
  51 </span>     * @cfg {Ext.XTemplate} activeErrorsTpl
  52      * The template used to format the Array of error messages passed to {@link #setActiveErrors}
  53      * into a single HTML string. By default this renders each message as an item in an unordered list.
  54      */
  55     activeErrorsTpl: [
  56         '&lt;tpl if=&quot;errors &amp;&amp; errors.length&quot;&gt;',
  57             '&lt;ul&gt;&lt;tpl for=&quot;errors&quot;&gt;&lt;li&lt;tpl if=&quot;xindex == xcount&quot;&gt; class=&quot;last&quot;&lt;/tpl&gt;&gt;{.}&lt;/li&gt;&lt;/tpl&gt;&lt;/ul&gt;',
  58         '&lt;/tpl&gt;'
  59     ],
  60
  61 <span id='Ext-form.Labelable-property-isFieldLabelable'>    /**
  62 </span>     * @property isFieldLabelable
  63      * @type Boolean
  64      * Flag denoting that this object is labelable as a field. Always true.
  65      */
  66     isFieldLabelable: true,
  67
  68 <span id='Ext-form.Labelable-cfg-formItemCls'>    /**
  69 </span>     * @cfg {String} formItemCls
  70      * A CSS class to be applied to the outermost element to denote that it is participating in the form
  71      * field layout. Defaults to 'x-form-item'.
  72      */
  73     formItemCls: Ext.baseCSSPrefix + 'form-item',
  74
  75 <span id='Ext-form.Labelable-cfg-labelCls'>    /**
  76 </span>     * @cfg {String} labelCls
  77      * The CSS class to be applied to the label element. Defaults to 'x-form-item-label'.
  78      */
  79     labelCls: Ext.baseCSSPrefix + 'form-item-label',
  80
  81 <span id='Ext-form.Labelable-cfg-errorMsgCls'>    /**
  82 </span>     * @cfg {String} errorMsgCls
  83      * The CSS class to be applied to the error message element. Defaults to 'x-form-error-msg'.
  84      */
  85     errorMsgCls: Ext.baseCSSPrefix + 'form-error-msg',
  86
  87 <span id='Ext-form.Labelable-cfg-baseBodyCls'>    /**
  88 </span>     * @cfg {String} baseBodyCls
  89      * The CSS class to be applied to the body content element. Defaults to 'x-form-item-body'.
  90      */
  91     baseBodyCls: Ext.baseCSSPrefix + 'form-item-body',
  92
  93 <span id='Ext-form.Labelable-cfg-fieldBodyCls'>    /**
  94 </span>     * @cfg {String} fieldBodyCls
  95      * An extra CSS class to be applied to the body content element in addition to {@link #fieldBodyCls}.
  96      * Defaults to empty.
  97      */
  98     fieldBodyCls: '',
  99
 100 <span id='Ext-form.Labelable-cfg-clearCls'>    /**
 101 </span>     * @cfg {String} clearCls
 102      * The CSS class to be applied to the special clearing div rendered directly after the field
 103      * contents wrapper to provide field clearing (defaults to &lt;tt&gt;'x-clear'&lt;/tt&gt;).
 104      */
 105     clearCls: Ext.baseCSSPrefix + 'clear',
 106
 107 <span id='Ext-form.Labelable-cfg-invalidCls'>    /**
 108 </span>     * @cfg {String} invalidCls
 109      * The CSS class to use when marking the component invalid (defaults to 'x-form-invalid')
 110      */
 111     invalidCls : Ext.baseCSSPrefix + 'form-invalid',
 112
 113 <span id='Ext-form.Labelable-cfg-fieldLabel'>    /**
 114 </span>     * @cfg {String} fieldLabel
 115      * The label for the field. It gets appended with the {@link #labelSeparator}, and its position
 116      * and sizing is determined by the {@link #labelAlign}, {@link #labelWidth}, and {@link #labelPad}
 117      * configs. Defaults to undefined.
 118      */
 119     fieldLabel: undefined,
 120
 121 <span id='Ext-form.Labelable-cfg-labelAlign'>    /**
 122 </span>     * @cfg {String} labelAlign
 123      * &lt;p&gt;Controls the position and alignment of the {@link #fieldLabel}. Valid values are:&lt;/p&gt;
 124      * &lt;ul&gt;
 125      * &lt;li&gt;&lt;tt&gt;&quot;left&quot;&lt;/tt&gt; (the default) - The label is positioned to the left of the field, with its text
 126      * aligned to the left. Its width is determined by the {@link #labelWidth} config.&lt;/li&gt;
 127      * &lt;li&gt;&lt;tt&gt;&quot;top&quot;&lt;/tt&gt; - The label is positioned above the field.&lt;/li&gt;
 128      * &lt;li&gt;&lt;tt&gt;&quot;right&quot;&lt;/tt&gt; - The label is positioned to the left of the field, with its text aligned
 129      * to the right. Its width is determined by the {@link #labelWidth} config.&lt;/li&gt;
 130      * &lt;/ul&gt;
 131      */
 132     labelAlign : 'left',
 133
 134 <span id='Ext-form.Labelable-cfg-labelWidth'>    /**
 135 </span>     * @cfg {Number} labelWidth
 136      * The width of the {@link #fieldLabel} in pixels. Only applicable if the {@link #labelAlign} is set
 137      * to &quot;left&quot; or &quot;right&quot;. Defaults to &lt;tt&gt;100&lt;/tt&gt;.
 138      */
 139     labelWidth: 100,
 140
 141 <span id='Ext-form.Labelable-cfg-labelPad'>    /**
 142 </span>     * @cfg {Number} labelPad
 143      * The amount of space in pixels between the {@link #fieldLabel} and the input field. Defaults to &lt;tt&gt;5&lt;/tt&gt;.
 144      */
 145     labelPad : 5,
 146
 147 <span id='Ext-form.Labelable-cfg-labelSeparator'>    /**
 148 </span>     * @cfg {String} labelSeparator
 149      * Character(s) to be inserted at the end of the {@link #fieldLabel label text}.
 150      */
 151     labelSeparator : ':',
 152
 153 <span id='Ext-form.Labelable-cfg-labelStyle'>    /**
 154 </span>     * @cfg {String} labelStyle
 155      * &lt;p&gt;A CSS style specification string to apply directly to this field's label. Defaults to undefined.&lt;/p&gt;
 156      */
 157
 158 <span id='Ext-form.Labelable-cfg-hideLabel'>    /**
 159 </span>     * @cfg {Boolean} hideLabel
 160      * &lt;p&gt;Set to &lt;tt&gt;true&lt;/tt&gt; to completely hide the label element ({@link #fieldLabel} and {@link #labelSeparator}).
 161      * Defaults to &lt;tt&gt;false&lt;/tt&gt;.&lt;/p&gt;
 162      * &lt;p&gt;Also see {@link #hideEmptyLabel}, which controls whether space will be reserved for an empty fieldLabel.&lt;/p&gt;
 163      */
 164     hideLabel: false,
 165
 166 <span id='Ext-form.Labelable-cfg-hideEmptyLabel'>    /**
 167 </span>     * @cfg {Boolean} hideEmptyLabel
 168      * &lt;p&gt;When set to &lt;tt&gt;true&lt;/tt&gt;, the label element ({@link #fieldLabel} and {@link #labelSeparator}) will be
 169      * automatically hidden if the {@link #fieldLabel} is empty. Setting this to &lt;tt&gt;false&lt;/tt&gt; will cause the empty
 170      * label element to be rendered and space to be reserved for it; this is useful if you want a field without a label
 171      * to line up with other labeled fields in the same form. Defaults to &lt;tt&gt;true&lt;/tt&gt;.&lt;/p&gt;
 172      * &lt;p&gt;If you wish to unconditionall hide the label even if a non-empty fieldLabel is configured, then set
 173      * the {@link #hideLabel} config to &lt;tt&gt;true&lt;/tt&gt;.&lt;/p&gt;
 174      */
 175     hideEmptyLabel: true,
 176
 177 <span id='Ext-form.Labelable-cfg-preventMark'>    /**
 178 </span>     * @cfg {Boolean} preventMark
 179      * &lt;tt&gt;true&lt;/tt&gt; to disable displaying any {@link #setActiveError error message} set on this object.
 180      * Defaults to &lt;tt&gt;false&lt;/tt&gt;.
 181      */
 182     preventMark: false,
 183
 184 <span id='Ext-form.Labelable-cfg-autoFitErrors'>    /**
 185 </span>     * @cfg {Boolean} autoFitErrors
 186      * Whether to adjust the component's body area to make room for 'side' or 'under'
 187      * {@link #msgTarget error messages}. Defaults to &lt;tt&gt;true&lt;/tt&gt;.
 188      */
 189     autoFitErrors: true,
 190
 191 <span id='Ext-form.Labelable-cfg-msgTarget'>    /**
 192 </span>     * @cfg {String} msgTarget &lt;p&gt;The location where the error message text should display.
 193      * Must be one of the following values:&lt;/p&gt;
 194      * &lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
 195      * &lt;li&gt;&lt;code&gt;qtip&lt;/code&gt; Display a quick tip containing the message when the user hovers over the field. This is the default.
 196      * &lt;div class=&quot;subdesc&quot;&gt;&lt;b&gt;{@link Ext.tip.QuickTipManager#init Ext.tip.QuickTipManager.init} must have been called for this setting to work.&lt;/b&gt;&lt;/div&gt;&lt;/li&gt;
 197      * &lt;li&gt;&lt;code&gt;title&lt;/code&gt; Display the message in a default browser title attribute popup.&lt;/li&gt;
 198      * &lt;li&gt;&lt;code&gt;under&lt;/code&gt; Add a block div beneath the field containing the error message.&lt;/li&gt;
 199      * &lt;li&gt;&lt;code&gt;side&lt;/code&gt; Add an error icon to the right of the field, displaying the message in a popup on hover.&lt;/li&gt;
 200      * &lt;li&gt;&lt;code&gt;none&lt;/code&gt; Don't display any error message. This might be useful if you are implementing custom error display.&lt;/li&gt;
 201      * &lt;li&gt;&lt;code&gt;[element id]&lt;/code&gt; Add the error message directly to the innerHTML of the specified element.&lt;/li&gt;
 202      * &lt;/ul&gt;&lt;/div&gt;
 203      */
 204     msgTarget: 'qtip',
 205
 206 <span id='Ext-form.Labelable-cfg-activeError'>    /**
 207 </span>     * @cfg {String} activeError
 208      * If specified, then the component will be displayed with this value as its active error when
 209      * first rendered. Defaults to undefined. Use {@link #setActiveError} or {@link #unsetActiveError} to
 210      * change it after component creation.
 211      */
 212
 213
 214 <span id='Ext-form.Labelable-method-initLabelable'>    /**
 215 </span>     * Performs initialization of this mixin. Component classes using this mixin should call this method
 216      * during their own initialization.
 217      */
 218     initLabelable: function() {
 219         this.addCls(this.formItemCls);
 220
 221         this.addEvents(
 222 <span id='Ext-form.Labelable-event-errorchange'>            /**
 223 </span>             * @event errorchange
 224              * Fires when the active error message is changed via {@link #setActiveError}.
 225              * @param {Ext.form.Labelable} this
 226              * @param {String} error The active error message
 227              */
 228             'errorchange'
 229         );
 230     },
 231
 232 <span id='Ext-form.Labelable-method-getFieldLabel'>    /**
 233 </span>     * Returns the label for the field. Defaults to simply returning the {@link #fieldLabel} config. Can be
 234      * overridden to provide
 235      * @return {String} The configured field label, or empty string if not defined
 236      */
 237     getFieldLabel: function() {
 238         return this.fieldLabel || '';
 239     },
 240
 241 <span id='Ext-form.Labelable-method-getLabelableRenderData'>    /**
 242 </span>     * @protected
 243      * Generates the arguments for the field decorations {@link #labelableRenderTpl rendering template}.
 244      * @return {Object} The template arguments
 245      */
 246     getLabelableRenderData: function() {
 247         var me = this,
 248             labelAlign = me.labelAlign,
 249             labelPad = me.labelPad,
 250             labelStyle;
 251
 252         // Calculate label styles up front rather than in the Field layout for speed; this
 253         // is safe because label alignment/width/pad are not expected to change.
 254         if (labelAlign === 'top') {
 255             labelStyle = 'margin-bottom:' + labelPad + 'px;';
 256         } else {
 257             labelStyle = 'margin-right:' + labelPad + 'px;';
 258             // Add the width for border-box browsers; will be set by the Field layout for content-box
 259             if (Ext.isBorderBox) {
 260                 labelStyle += 'width:' + me.labelWidth + 'px;';
 261             }
 262         }
 263
 264         return Ext.copyTo(
 265             {
 266                 inputId: me.getInputId(),
 267                 fieldLabel: me.getFieldLabel(),
 268                 labelStyle: labelStyle + (me.labelStyle || ''),
 269                 subTplMarkup: me.getSubTplMarkup()
 270             },
 271             me,
 272             'hideLabel,hideEmptyLabel,labelCls,fieldBodyCls,baseBodyCls,errorMsgCls,clearCls,labelSeparator',
 273             true
 274         );
 275     },
 276
 277 <span id='Ext-form.Labelable-method-getLabelableSelectors'>    /**
 278 </span>     * @protected
 279      * Returns the additional {@link Ext.AbstractComponent#renderSelectors} for selecting the field
 280      * decoration elements from the rendered {@link #labelableRenderTpl}. Component classes using this mixin should
 281      * be sure and merge this method's result into the component's {@link Ext.AbstractComponent#renderSelectors}
 282      * before rendering.
 283      */
 284     getLabelableSelectors: function() {
 285         return {
 286 <span id='Ext-form.Labelable-property-labelEl'>            /**
 287 </span>             * @property labelEl
 288              * @type Ext.core.Element
 289              * The label Element for this component. Only available after the component has been rendered.
 290              */
 291             labelEl: 'label.' + this.labelCls,
 292
 293 <span id='Ext-form.Labelable-property-bodyEl'>            /**
 294 </span>             * @property bodyEl
 295              * @type Ext.core.Element
 296              * The div Element wrapping the component's contents. Only available after the component has been rendered.
 297              */
 298             bodyEl: '.' + this.baseBodyCls,
 299
 300 <span id='Ext-form.Labelable-property-errorEl'>            /**
 301 </span>             * @property errorEl
 302              * @type Ext.core.Element
 303              * The div Element that will contain the component's error message(s). Note that depending on the
 304              * configured {@link #msgTarget}, this element may be hidden in favor of some other form of
 305              * presentation, but will always be present in the DOM for use by assistive technologies.
 306              */
 307             errorEl: '.' + this.errorMsgCls
 308         };
 309     },
 310
 311 <span id='Ext-form.Labelable-method-getSubTplMarkup'>    /**
 312 </span>     * @protected
 313      * Gets the markup to be inserted into the outer template's bodyEl. Defaults to empty string, should
 314      * be implemented by classes including this mixin as needed.
 315      * @return {String} The markup to be inserted
 316      */
 317     getSubTplMarkup: function() {
 318         return '';
 319     },
 320
 321 <span id='Ext-form.Labelable-method-getInputId'>    /**
 322 </span>     * Get the input id, if any, for this component. This is used as the &quot;for&quot; attribute on the label element.
 323      * Implementing subclasses may also use this as e.g. the id for their own &lt;tt&gt;input&lt;/tt&gt; element.
 324      * @return {String} The input id
 325      */
 326     getInputId: function() {
 327         return '';
 328     },
 329
 330 <span id='Ext-form.Labelable-method-getActiveError'>    /**
 331 </span>     * Gets the active error message for this component, if any. This does not trigger
 332      * validation on its own, it merely returns any message that the component may already hold.
 333      * @return {String} The active error message on the component; if there is no error, an empty string is returned.
 334      */
 335     getActiveError : function() {
 336         return this.activeError || '';
 337     },
 338
 339 <span id='Ext-form.Labelable-method-hasActiveError'>    /**
 340 </span>     * Tells whether the field currently has an active error message. This does not trigger
 341      * validation on its own, it merely looks for any message that the component may already hold.
 342      * @return {Boolean}
 343      */
 344     hasActiveError: function() {
 345         return !!this.getActiveError();
 346     },
 347
 348 <span id='Ext-form.Labelable-method-setActiveError'>    /**
 349 </span>     * Sets the active error message to the given string. This replaces the entire error message
 350      * contents with the given string. Also see {@link #setActiveErrors} which accepts an Array of
 351      * messages and formats them according to the {@link #activeErrorsTpl}.
 352      * @param {String} msg The error message
 353      */
 354     setActiveError: function(msg) {
 355         this.activeError = msg;
 356         this.activeErrors = [msg];
 357         this.renderActiveError();
 358     },
 359
 360 <span id='Ext-form.Labelable-method-getActiveErrors'>    /**
 361 </span>     * Gets an Array of any active error messages currently applied to the field. This does not trigger
 362      * validation on its own, it merely returns any messages that the component may already hold.
 363      * @return {Array} The active error messages on the component; if there are no errors, an empty Array is returned.
 364      */
 365     getActiveErrors: function() {
 366         return this.activeErrors || [];
 367     },
 368
 369 <span id='Ext-form.Labelable-method-setActiveErrors'>    /**
 370 </span>     * Set the active error message to an Array of error messages. The messages are formatted into
 371      * a single message string using the {@link #activeErrorsTpl}. Also see {@link #setActiveError}
 372      * which allows setting the entire error contents with a single string.
 373      * @param {Array} errors The error messages
 374      */
 375     setActiveErrors: function(errors) {
 376         this.activeErrors = errors;
 377         this.activeError = this.getTpl('activeErrorsTpl').apply({errors: errors});
 378         this.renderActiveError();
 379     },
 380
 381 <span id='Ext-form.Labelable-method-unsetActiveError'>    /**
 382 </span>     * Clears the active error.
 383      */
 384     unsetActiveError: function() {
 385         delete this.activeError;
 386         delete this.activeErrors;
 387         this.renderActiveError();
 388     },
 389
 390 <span id='Ext-form.Labelable-method-renderActiveError'>    /**
 391 </span>     * @private
 392      * Updates the rendered DOM to match the current activeError. This only updates the content and
 393      * attributes, you'll have to call doComponentLayout to actually update the display.
 394      */
 395     renderActiveError: function() {
 396         var me = this,
 397             activeError = me.getActiveError(),
 398             hasError = !!activeError;
 399
 400         if (activeError !== me.lastActiveError) {
 401             me.fireEvent('errorchange', me, activeError);
 402             me.lastActiveError = activeError;
 403         }
 404
 405         if (me.rendered &amp;&amp; !me.isDestroyed &amp;&amp; !me.preventMark) {
 406             // Add/remove invalid class
 407             me.el[hasError ? 'addCls' : 'removeCls'](me.invalidCls);
 408
 409             // Update the aria-invalid attribute
 410             me.getActionEl().dom.setAttribute('aria-invalid', hasError);
 411
 412             // Update the errorEl with the error message text
 413             me.errorEl.dom.innerHTML = activeError;
 414         }
 415     },
 416
 417 <span id='Ext-form.Labelable-method-setFieldDefaults'>    /**
 418 </span>     * Applies a set of default configuration values to this Labelable instance. For each of the
 419      * properties in the given object, check if this component hasOwnProperty that config; if not
 420      * then it's inheriting a default value from its prototype and we should apply the default value.
 421      * @param {Object} defaults The defaults to apply to the object.
 422      */
 423     setFieldDefaults: function(defaults) {
 424         var me = this;
 425         Ext.iterate(defaults, function(key, val) {
 426             if (!me.hasOwnProperty(key)) {
 427                 me[key] = val;
 428             }
 429         });
 430     },
 431
 432 <span id='Ext-form.Labelable-method-getBodyNaturalWidth'>    /**
 433 </span>     * @protected Calculate and return the natural width of the bodyEl. Override to provide custom logic.
 434      * Note for implementors: if at all possible this method should be overridden with a custom implementation
 435      * that can avoid anything that would cause the browser to reflow, e.g. querying offsetWidth.
 436      */
 437     getBodyNaturalWidth: function() {
 438         return this.bodyEl.getWidth();
 439     }
 440
 441 });
 442 </pre></pre></body></html>