Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / 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>