X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/7a654f8d43fdb43d78b63d90528bed6e86b608cc..refs/heads/master:/docs/source/Labelable.html diff --git a/docs/source/Labelable.html b/docs/source/Labelable.html index 01efbebe..2f7ba6b8 100644 --- a/docs/source/Labelable.html +++ b/docs/source/Labelable.html @@ -1,45 +1,60 @@ -Sencha Documentation Project
/**
- * @class Ext.form.Labelable
-
-A mixin which allows a component to be configured and decorated with a label and/or error message as is
-common for form fields. This is used by e.g. {@link Ext.form.field.Base} and {@link Ext.form.FieldContainer}
-to let them be managed by the Field layout.
-
-**NOTE**: This mixin is mainly for internal library use and most users should not need to use it directly. It
-is more likely you will want to use one of the component classes that import this mixin, such as
-{@link Ext.form.field.Base} or {@link Ext.form.FieldContainer}.
-
-Use of this mixin does not make a component a field in the logical sense, meaning it does not provide any
-logic or state related to values or validation; that is handled by the related {@link Ext.form.field.Field}
-mixin. These two mixins may be used separately (for example {@link Ext.form.FieldContainer} is Labelable but not a
-Field), or in combination (for example {@link Ext.form.field.Base} implements both and has logic for connecting the
-two.)
-
-Component classes which use this mixin should use the Field layout
-or a derivation thereof to properly size and position the label and message according to the component config.
-They must also call the {@link #initLabelable} method during component initialization to ensure the mixin gets
-set up correctly.
-
- * @markdown
+
+
+
+  
+  The source code
+  
+  
+  
+  
+
+
+  
/**
+ * A mixin which allows a component to be configured and decorated with a label and/or error message as is
+ * common for form fields. This is used by e.g. Ext.form.field.Base and Ext.form.FieldContainer
+ * to let them be managed by the Field layout.
+ *
+ * NOTE: This mixin is mainly for internal library use and most users should not need to use it directly. It
+ * is more likely you will want to use one of the component classes that import this mixin, such as
+ * Ext.form.field.Base or Ext.form.FieldContainer.
+ *
+ * Use of this mixin does not make a component a field in the logical sense, meaning it does not provide any
+ * logic or state related to values or validation; that is handled by the related Ext.form.field.Field
+ * mixin. These two mixins may be used separately (for example Ext.form.FieldContainer is Labelable but not a
+ * Field), or in combination (for example Ext.form.field.Base implements both and has logic for connecting the
+ * two.)
+ *
+ * Component classes which use this mixin should use the Field layout
+ * or a derivation thereof to properly size and position the label and message according to the component config.
+ * They must also call the {@link #initLabelable} method during component initialization to ensure the mixin gets
+ * set up correctly.
+ *
  * @docauthor Jason Johnston <jason@sencha.com>
  */
 Ext.define("Ext.form.Labelable", {
     requires: ['Ext.XTemplate'],
 
-    /**
-     * @cfg {Array/String/Ext.XTemplate} labelableRenderTpl
+    /**
+     * @cfg {String/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
      * {@link #getSubTplMarkup} method to generate the field body content.
      */
     labelableRenderTpl: [
         '<tpl if="!hideLabel && !(!fieldLabel && hideEmptyLabel)">',
-            '<label<tpl if="inputId"> for="{inputId}"</tpl> class="{labelCls}"<tpl if="labelStyle"> style="{labelStyle}"</tpl>>',
+            '<label id="{id}-labelEl"<tpl if="inputId"> for="{inputId}"</tpl> class="{labelCls}"',
+                '<tpl if="labelStyle"> style="{labelStyle}"</tpl>>',
                 '<tpl if="fieldLabel">{fieldLabel}{labelSeparator}</tpl>',
             '</label>',
         '</tpl>',
-        '<div class="{baseBodyCls} {fieldBodyCls}"<tpl if="inputId"> id="{baseBodyCls}-{inputId}"</tpl> role="presentation">{subTplMarkup}</div>',
-        '<div class="{errorMsgCls}" style="display:none"></div>',
+        '<div class="{baseBodyCls} {fieldBodyCls}" id="{id}-bodyEl" role="presentation">{subTplMarkup}</div>',
+        '<div id="{id}-errorEl" class="{errorMsgCls}" style="display:none"></div>',
         '<div class="{clearCls}" role="presentation"><!-- --></div>',
         {
             compiled: true,
@@ -47,7 +62,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,67 +73,75 @@ 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
+    /**
+     * @cfg {String} [formItemCls='x-form-item']
      * 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'.
+     * field layout.
      */
     formItemCls: Ext.baseCSSPrefix + 'form-item',
 
-    /**
-     * @cfg {String} labelCls
-     * The CSS class to be applied to the label element. Defaults to 'x-form-item-label'.
+    /**
+     * @cfg {String} [labelCls='x-form-item-label']
+     * The CSS class to be applied to the label element.
+     * This (single) CSS class is used to formulate the renderSelector and drives the field
+     * layout where it is concatenated with a hyphen ('-') and {@link #labelAlign}. To add
+     * additional classes, use {@link #labelClsExtra}.
      */
     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'.
+    /**
+     * @cfg {String} labelClsExtra
+     * An optional string of one or more additional CSS classes to add to the label element.
+     * Defaults to empty.
+     */
+
+    /**
+     * @cfg {String} [errorMsgCls='x-form-error-msg']
+     * The CSS class to be applied to the error message element.
      */
     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'.
+    /**
+     * @cfg {String} [baseBodyCls='x-form-item-body']
+     * The CSS class to be applied to the body content element.
      */
     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
+    /**
+     * @cfg {String} [clearCls='x-clear']
      * 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>).
+     * contents wrapper to provide field clearing.
      */
     clearCls: Ext.baseCSSPrefix + 'clear',
 
-    /**
-     * @cfg {String} invalidCls
-     * The CSS class to use when marking the component invalid (defaults to 'x-form-invalid')
+    /**
+     * @cfg {String} [invalidCls='x-form-invalid']
+     * The CSS class to use when marking the component 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}
-     * configs. Defaults to undefined.
+     * configs.
      */
     fieldLabel: undefined,
 
-    /**
+    /**
      * @cfg {String} labelAlign
      * <p>Controls the position and alignment of the {@link #fieldLabel}. Valid values are:</p>
      * <ul>
@@ -131,64 +154,62 @@ 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>.
+     * to "left" or "right".
      */
     labelWidth: 100,
 
-    /**
+    /**
      * @cfg {Number} labelPad
-     * The amount of space in pixels between the {@link #fieldLabel} and the input field. Defaults to <tt>5</tt>.
+     * The amount of space in pixels between the {@link #fieldLabel} and the input field.
      */
     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>
+     * A CSS style specification string to apply directly to this field's label.
      */
 
-    /**
+    /**
      * @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>
-     * <p>Also see {@link #hideEmptyLabel}, which controls whether space will be reserved for an empty fieldLabel.</p>
+     * Set to true to completely hide the label element ({@link #fieldLabel} and {@link #labelSeparator}).
+     * Also see {@link #hideEmptyLabel}, which controls whether space will be reserved for an empty fieldLabel.
      */
     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
      * label element to be rendered and space to be reserved for it; this is useful if you want a field without a label
-     * to line up with other labeled fields in the same form. Defaults to <tt>true</tt>.</p>
+     * to line up with other labeled fields in the same form.</p>
      * <p>If you wish to unconditionall hide the label even if a non-empty fieldLabel is configured, then set
      * the {@link #hideLabel} config to <tt>true</tt>.</p>
      */
     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>.
+     * {@link #msgTarget error messages}.
      */
     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,15 +224,15 @@ 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
+     * first rendered. Use {@link #setActiveError} or {@link #unsetActiveError} to
      * change it after component creation.
      */
 
 
-    /**
+    /**
      * Performs initialization of this mixin. Component classes using this mixin should call this method
      * during their own initialization.
      */
@@ -219,7 +240,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 +250,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 +259,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
@@ -246,6 +267,8 @@ Ext.define("Ext.form.Labelable", {
     getLabelableRenderData: function() {
         var me = this,
             labelAlign = me.labelAlign,
+            labelCls = me.labelCls,
+            labelClsExtra = me.labelClsExtra,
             labelPad = me.labelPad,
             labelStyle;
 
@@ -265,50 +288,44 @@ Ext.define("Ext.form.Labelable", {
             {
                 inputId: me.getInputId(),
                 fieldLabel: me.getFieldLabel(),
+                labelCls: labelClsExtra ? labelCls + ' ' + labelClsExtra : labelCls,
                 labelStyle: labelStyle + (me.labelStyle || ''),
                 subTplMarkup: me.getSubTplMarkup()
             },
             me,
-            'hideLabel,hideEmptyLabel,labelCls,fieldBodyCls,baseBodyCls,errorMsgCls,clearCls,labelSeparator',
+            'hideLabel,hideEmptyLabel,fieldBodyCls,baseBodyCls,errorMsgCls,clearCls,labelSeparator',
             true
         );
     },
 
-    /**
-     * @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
-     * be sure and merge this method's result into the component's {@link Ext.AbstractComponent#renderSelectors}
-     * before rendering.
-     */
-    getLabelableSelectors: function() {
-        return {
-            /**
+    onLabelableRender: function () {
+        this.addChildEls(
+            /**
              * @property labelEl
-             * @type Ext.core.Element
+             * @type Ext.Element
              * The label Element for this component. Only available after the component has been rendered.
              */
-            labelEl: 'label.' + this.labelCls,
+            'labelEl',
 
-            /**
+            /**
              * @property bodyEl
-             * @type Ext.core.Element
+             * @type Ext.Element
              * The div Element wrapping the component's contents. Only available after the component has been rendered.
              */
-            bodyEl: '.' + this.baseBodyCls,
+            'bodyEl',
 
-            /**
+            /**
              * @property errorEl
-             * @type Ext.core.Element
+             * @type Ext.Element
              * The div Element that will contain the component's error message(s). Note that depending on the
              * configured {@link #msgTarget}, this element may be hidden in favor of some other form of
              * presentation, but will always be present in the DOM for use by assistive technologies.
              */
-            errorEl: '.' + this.errorMsgCls
-        };
+            'errorEl'
+        );
     },
 
-    /**
+    /**
      * @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,20 +379,25 @@ 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.
+     * @return {String[]} The active error messages on the component; if there are no errors, an empty Array is returned.
      */
     getActiveErrors: function() {
         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.
-     * @param {Array} errors The error messages
+     *
+     * 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[]} errors The error messages
      */
     setActiveErrors: function(errors) {
         this.activeErrors = 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", {
     }
 
 });
-
\ No newline at end of file +
+ +