/**
* @class Ext.form.Labelable
A mixin which allows a component to be configured and decorated with a label and/or error message as is
@@ -26,7 +43,7 @@ set up correctly.
Ext.define("Ext.form.Labelable", {
requires: ['Ext.XTemplate'],
- /**
+ /**
* @cfg {Array/String/Ext.XTemplate} labelableRenderTpl
* The rendering template for the field decorations. Component classes using this mixin should include
* logic to use this as their {@link Ext.AbstractComponent#renderTpl renderTpl}, and implement the
@@ -47,7 +64,7 @@ Ext.define("Ext.form.Labelable", {
}
],
- /**
+ /**
* @cfg {Ext.XTemplate} activeErrorsTpl
* The template used to format the Array of error messages passed to {@link #setActiveErrors}
* into a single HTML string. By default this renders each message as an item in an unordered list.
@@ -58,59 +75,59 @@ Ext.define("Ext.form.Labelable", {
'</tpl>'
],
- /**
+ /**
* @property isFieldLabelable
* @type Boolean
* Flag denoting that this object is labelable as a field. Always true.
*/
isFieldLabelable: true,
- /**
+ /**
* @cfg {String} formItemCls
* A CSS class to be applied to the outermost element to denote that it is participating in the form
* field layout. Defaults to 'x-form-item'.
*/
formItemCls: Ext.baseCSSPrefix + 'form-item',
- /**
+ /**
* @cfg {String} labelCls
* The CSS class to be applied to the label element. Defaults to 'x-form-item-label'.
*/
labelCls: Ext.baseCSSPrefix + 'form-item-label',
- /**
+ /**
* @cfg {String} errorMsgCls
* The CSS class to be applied to the error message element. Defaults to 'x-form-error-msg'.
*/
errorMsgCls: Ext.baseCSSPrefix + 'form-error-msg',
- /**
+ /**
* @cfg {String} baseBodyCls
* The CSS class to be applied to the body content element. Defaults to 'x-form-item-body'.
*/
baseBodyCls: Ext.baseCSSPrefix + 'form-item-body',
- /**
+ /**
* @cfg {String} fieldBodyCls
* An extra CSS class to be applied to the body content element in addition to {@link #fieldBodyCls}.
* Defaults to empty.
*/
fieldBodyCls: '',
- /**
+ /**
* @cfg {String} clearCls
* The CSS class to be applied to the special clearing div rendered directly after the field
* contents wrapper to provide field clearing (defaults to <tt>'x-clear'</tt>).
*/
clearCls: Ext.baseCSSPrefix + 'clear',
- /**
+ /**
* @cfg {String} invalidCls
* The CSS class to use when marking the component invalid (defaults to 'x-form-invalid')
*/
invalidCls : Ext.baseCSSPrefix + 'form-invalid',
- /**
+ /**
* @cfg {String} fieldLabel
* The label for the field. It gets appended with the {@link #labelSeparator}, and its position
* and sizing is determined by the {@link #labelAlign}, {@link #labelWidth}, and {@link #labelPad}
@@ -118,7 +135,7 @@ Ext.define("Ext.form.Labelable", {
*/
fieldLabel: undefined,
- /**
+ /**
* @cfg {String} labelAlign
* <p>Controls the position and alignment of the {@link #fieldLabel}. Valid values are:</p>
* <ul>
@@ -131,31 +148,31 @@ Ext.define("Ext.form.Labelable", {
*/
labelAlign : 'left',
- /**
+ /**
* @cfg {Number} labelWidth
* The width of the {@link #fieldLabel} in pixels. Only applicable if the {@link #labelAlign} is set
* to "left" or "right". Defaults to <tt>100</tt>.
*/
labelWidth: 100,
- /**
+ /**
* @cfg {Number} labelPad
* The amount of space in pixels between the {@link #fieldLabel} and the input field. Defaults to <tt>5</tt>.
*/
labelPad : 5,
- /**
+ /**
* @cfg {String} labelSeparator
* Character(s) to be inserted at the end of the {@link #fieldLabel label text}.
*/
labelSeparator : ':',
- /**
+ /**
* @cfg {String} labelStyle
* <p>A CSS style specification string to apply directly to this field's label. Defaults to undefined.</p>
*/
- /**
+ /**
* @cfg {Boolean} hideLabel
* <p>Set to <tt>true</tt> to completely hide the label element ({@link #fieldLabel} and {@link #labelSeparator}).
* Defaults to <tt>false</tt>.</p>
@@ -163,7 +180,7 @@ Ext.define("Ext.form.Labelable", {
*/
hideLabel: false,
- /**
+ /**
* @cfg {Boolean} hideEmptyLabel
* <p>When set to <tt>true</tt>, the label element ({@link #fieldLabel} and {@link #labelSeparator}) will be
* automatically hidden if the {@link #fieldLabel} is empty. Setting this to <tt>false</tt> will cause the empty
@@ -174,21 +191,21 @@ Ext.define("Ext.form.Labelable", {
*/
hideEmptyLabel: true,
- /**
+ /**
* @cfg {Boolean} preventMark
* <tt>true</tt> to disable displaying any {@link #setActiveError error message} set on this object.
* Defaults to <tt>false</tt>.
*/
preventMark: false,
- /**
+ /**
* @cfg {Boolean} autoFitErrors
* Whether to adjust the component's body area to make room for 'side' or 'under'
* {@link #msgTarget error messages}. Defaults to <tt>true</tt>.
*/
autoFitErrors: true,
- /**
+ /**
* @cfg {String} msgTarget <p>The location where the error message text should display.
* Must be one of the following values:</p>
* <div class="mdetail-params"><ul>
@@ -203,7 +220,7 @@ Ext.define("Ext.form.Labelable", {
*/
msgTarget: 'qtip',
- /**
+ /**
* @cfg {String} activeError
* If specified, then the component will be displayed with this value as its active error when
* first rendered. Defaults to undefined. Use {@link #setActiveError} or {@link #unsetActiveError} to
@@ -211,7 +228,7 @@ Ext.define("Ext.form.Labelable", {
*/
- /**
+ /**
* Performs initialization of this mixin. Component classes using this mixin should call this method
* during their own initialization.
*/
@@ -219,7 +236,7 @@ Ext.define("Ext.form.Labelable", {
this.addCls(this.formItemCls);
this.addEvents(
- /**
+ /**
* @event errorchange
* Fires when the active error message is changed via {@link #setActiveError}.
* @param {Ext.form.Labelable} this
@@ -229,7 +246,7 @@ Ext.define("Ext.form.Labelable", {
);
},
- /**
+ /**
* Returns the label for the field. Defaults to simply returning the {@link #fieldLabel} config. Can be
* overridden to provide
* @return {String} The configured field label, or empty string if not defined
@@ -238,7 +255,7 @@ Ext.define("Ext.form.Labelable", {
return this.fieldLabel || '';
},
- /**
+ /**
* @protected
* Generates the arguments for the field decorations {@link #labelableRenderTpl rendering template}.
* @return {Object} The template arguments
@@ -274,7 +291,7 @@ Ext.define("Ext.form.Labelable", {
);
},
- /**
+ /**
* @protected
* Returns the additional {@link Ext.AbstractComponent#renderSelectors} for selecting the field
* decoration elements from the rendered {@link #labelableRenderTpl}. Component classes using this mixin should
@@ -283,21 +300,21 @@ Ext.define("Ext.form.Labelable", {
*/
getLabelableSelectors: function() {
return {
- /**
+ /**
* @property labelEl
* @type Ext.core.Element
* The label Element for this component. Only available after the component has been rendered.
*/
labelEl: 'label.' + this.labelCls,
- /**
+ /**
* @property bodyEl
* @type Ext.core.Element
* The div Element wrapping the component's contents. Only available after the component has been rendered.
*/
bodyEl: '.' + this.baseBodyCls,
- /**
+ /**
* @property errorEl
* @type Ext.core.Element
* The div Element that will contain the component's error message(s). Note that depending on the
@@ -308,7 +325,7 @@ Ext.define("Ext.form.Labelable", {
};
},
- /**
+ /**
* @protected
* Gets the markup to be inserted into the outer template's bodyEl. Defaults to empty string, should
* be implemented by classes including this mixin as needed.
@@ -318,7 +335,7 @@ Ext.define("Ext.form.Labelable", {
return '';
},
- /**
+ /**
* Get the input id, if any, for this component. This is used as the "for" attribute on the label element.
* Implementing subclasses may also use this as e.g. the id for their own <tt>input</tt> element.
* @return {String} The input id
@@ -327,7 +344,7 @@ Ext.define("Ext.form.Labelable", {
return '';
},
- /**
+ /**
* Gets the active error message for this component, if any. This does not trigger
* validation on its own, it merely returns any message that the component may already hold.
* @return {String} The active error message on the component; if there is no error, an empty string is returned.
@@ -336,7 +353,7 @@ Ext.define("Ext.form.Labelable", {
return this.activeError || '';
},
- /**
+ /**
* Tells whether the field currently has an active error message. This does not trigger
* validation on its own, it merely looks for any message that the component may already hold.
* @return {Boolean}
@@ -345,10 +362,15 @@ Ext.define("Ext.form.Labelable", {
return !!this.getActiveError();
},
- /**
+ /**
* Sets the active error message to the given string. This replaces the entire error message
* contents with the given string. Also see {@link #setActiveErrors} which accepts an Array of
* messages and formats them according to the {@link #activeErrorsTpl}.
+ *
+ * Note that this only updates the error message element's text and attributes, you'll have
+ * to call doComponentLayout to actually update the field's layout to match. If the field extends
+ * {@link Ext.form.field.Base} you should call {@link Ext.form.field.Base#markInvalid markInvalid} instead.
+ *
* @param {String} msg The error message
*/
setActiveError: function(msg) {
@@ -357,7 +379,7 @@ Ext.define("Ext.form.Labelable", {
this.renderActiveError();
},
- /**
+ /**
* Gets an Array of any active error messages currently applied to the field. This does not trigger
* validation on its own, it merely returns any messages that the component may already hold.
* @return {Array} The active error messages on the component; if there are no errors, an empty Array is returned.
@@ -366,10 +388,15 @@ Ext.define("Ext.form.Labelable", {
return this.activeErrors || [];
},
- /**
+ /**
* Set the active error message to an Array of error messages. The messages are formatted into
* a single message string using the {@link #activeErrorsTpl}. Also see {@link #setActiveError}
* which allows setting the entire error contents with a single string.
+ *
+ * Note that this only updates the error message element's text and attributes, you'll have
+ * to call doComponentLayout to actually update the field's layout to match. If the field extends
+ * {@link Ext.form.field.Base} you should call {@link Ext.form.field.Base#markInvalid markInvalid} instead.
+ *
* @param {Array} errors The error messages
*/
setActiveErrors: function(errors) {
@@ -378,8 +405,12 @@ Ext.define("Ext.form.Labelable", {
this.renderActiveError();
},
- /**
- * Clears the active error.
+ /**
+ * Clears the active error message(s).
+ *
+ * Note that this only clears the error message element's text and attributes, you'll have
+ * to call doComponentLayout to actually update the field's layout to match. If the field extends
+ * {@link Ext.form.field.Base} you should call {@link Ext.form.field.Base#clearInvalid clearInvalid} instead.
*/
unsetActiveError: function() {
delete this.activeError;
@@ -387,7 +418,7 @@ Ext.define("Ext.form.Labelable", {
this.renderActiveError();
},
- /**
+ /**
* @private
* Updates the rendered DOM to match the current activeError. This only updates the content and
* attributes, you'll have to call doComponentLayout to actually update the display.
@@ -414,7 +445,7 @@ Ext.define("Ext.form.Labelable", {
}
},
- /**
+ /**
* Applies a set of default configuration values to this Labelable instance. For each of the
* properties in the given object, check if this component hasOwnProperty that config; if not
* then it's inheriting a default value from its prototype and we should apply the default value.
@@ -429,7 +460,7 @@ Ext.define("Ext.form.Labelable", {
});
},
- /**
+ /**
* @protected Calculate and return the natural width of the bodyEl. Override to provide custom logic.
* Note for implementors: if at all possible this method should be overridden with a custom implementation
* that can avoid anything that would cause the browser to reflow, e.g. querying offsetWidth.
@@ -439,4 +470,6 @@ Ext.define("Ext.form.Labelable", {
}
});
-