docs/source/FieldAncestor.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-form-FieldAncestor'>/**
  19 </span> * @class Ext.form.FieldAncestor
  20
  21 A mixin for {@link Ext.container.Container} components that are likely to have form fields in their
  22 items subtree. Adds the following capabilities:
  23
  24 - Methods for handling the addition and removal of {@link Ext.form.Labelable} and {@link Ext.form.field.Field}
  25   instances at any depth within the container.
  26 - Events ({@link #fieldvaliditychange} and {@link #fielderrorchange}) for handling changes to the state
  27   of individual fields at the container level.
  28 - Automatic application of {@link #fieldDefaults} config properties to each field added within the
  29   container, to facilitate uniform configuration of all fields.
  30
  31 This mixin is primarily for internal use by {@link Ext.form.Panel} and {@link Ext.form.FieldContainer},
  32 and should not normally need to be used directly.
  33
  34  * @markdown
  35  * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
  36  */
  37 Ext.define('Ext.form.FieldAncestor', {
  38
  39 <span id='Ext-form-FieldAncestor-cfg-fieldDefaults'>    /**
  40 </span>     * @cfg {Object} fieldDefaults
  41      * &lt;p&gt;If specified, the properties in this object are used as default config values for each
  42      * {@link Ext.form.Labelable} instance (e.g. {@link Ext.form.field.Base} or {@link Ext.form.FieldContainer})
  43      * that is added as a descendant of this container. Corresponding values specified in an individual field's
  44      * own configuration, or from the {@link Ext.container.Container#defaults defaults config} of its parent container,
  45      * will take precedence. See the documentation for {@link Ext.form.Labelable} to see what config
  46      * options may be specified in the &lt;tt&gt;fieldDefaults&lt;/tt&gt;.&lt;/p&gt;
  47      * &lt;p&gt;Example:&lt;/p&gt;
  48      * &lt;pre&gt;&lt;code&gt;new Ext.form.Panel({
  49     fieldDefaults: {
  50         labelAlign: 'left',
  51         labelWidth: 100
  52     },
  53     items: [{
  54         xtype: 'fieldset',
  55         defaults: {
  56             labelAlign: 'top'
  57         },
  58         items: [{
  59             name: 'field1'
  60         }, {
  61             name: 'field2'
  62         }]
  63     }, {
  64         xtype: 'fieldset',
  65         items: [{
  66             name: 'field3',
  67             labelWidth: 150
  68         }, {
  69             name: 'field4'
  70         }]
  71     }]
  72 });&lt;/code&gt;&lt;/pre&gt;
  73      * &lt;p&gt;In this example, field1 and field2 will get labelAlign:'top' (from the fieldset's &lt;tt&gt;defaults&lt;/tt&gt;)
  74      * and labelWidth:100 (from &lt;tt&gt;fieldDefaults&lt;/tt&gt;), field3 and field4 will both get labelAlign:'left' (from
  75      * &lt;tt&gt;fieldDefaults&lt;/tt&gt; and field3 will use the labelWidth:150 from its own config.&lt;/p&gt;
  76      */
  77
  78
  79 <span id='Ext-form-FieldAncestor-method-initFieldAncestor'>    /**
  80 </span>     * @protected Initializes the FieldAncestor's state; this must be called from the initComponent method
  81      * of any components importing this mixin.
  82      */
  83     initFieldAncestor: function() {
  84         var me = this,
  85             onSubtreeChange = me.onFieldAncestorSubtreeChange;
  86
  87         me.addEvents(
  88 <span id='Ext-form-FieldAncestor-event-fieldvaliditychange'>            /**
  89 </span>             * @event fieldvaliditychange
  90              * Fires when the validity state of any one of the {@link Ext.form.field.Field} instances within this
  91              * container changes.
  92              * @param {Ext.form.FieldAncestor} this
  93              * @param {Ext.form.Labelable} The Field instance whose validity changed
  94              * @param {String} isValid The field's new validity state
  95              */
  96             'fieldvaliditychange',
  97
  98 <span id='Ext-form-FieldAncestor-event-fielderrorchange'>            /**
  99 </span>             * @event fielderrorchange
 100              * Fires when the active error message is changed for any one of the {@link Ext.form.Labelable}
 101              * instances within this container.
 102              * @param {Ext.form.FieldAncestor} this
 103              * @param {Ext.form.Labelable} The Labelable instance whose active error was changed
 104              * @param {String} error The active error message
 105              */
 106             'fielderrorchange'
 107         );
 108
 109         // Catch addition and removal of descendant fields
 110         me.on('add', onSubtreeChange, me);
 111         me.on('remove', onSubtreeChange, me);
 112
 113         me.initFieldDefaults();
 114     },
 115
 116 <span id='Ext-form-FieldAncestor-method-initFieldDefaults'>    /**
 117 </span>     * @private Initialize the {@link #fieldDefaults} object
 118      */
 119     initFieldDefaults: function() {
 120         if (!this.fieldDefaults) {
 121             this.fieldDefaults = {};
 122         }
 123     },
 124
 125 <span id='Ext-form-FieldAncestor-method-onFieldAncestorSubtreeChange'>    /**
 126 </span>     * @private
 127      * Handle the addition and removal of components in the FieldAncestor component's child tree.
 128      */
 129     onFieldAncestorSubtreeChange: function(parent, child) {
 130         var me = this,
 131             isAdding = !!child.ownerCt;
 132
 133         function handleCmp(cmp) {
 134             var isLabelable = cmp.isFieldLabelable,
 135                 isField = cmp.isFormField;
 136             if (isLabelable || isField) {
 137                 if (isLabelable) {
 138                     me['onLabelable' + (isAdding ? 'Added' : 'Removed')](cmp);
 139                 }
 140                 if (isField) {
 141                     me['onField' + (isAdding ? 'Added' : 'Removed')](cmp);
 142                 }
 143             }
 144             else if (cmp.isContainer) {
 145                 Ext.Array.forEach(cmp.getRefItems(), handleCmp);
 146             }
 147         }
 148         handleCmp(child);
 149     },
 150
 151 <span id='Ext-form-FieldAncestor-method-onLabelableAdded'>    /**
 152 </span>     * @protected Called when a {@link Ext.form.Labelable} instance is added to the container's subtree.
 153      * @param {Ext.form.Labelable} labelable The instance that was added
 154      */
 155     onLabelableAdded: function(labelable) {
 156         var me = this;
 157
 158         // buffer slightly to avoid excessive firing while sub-fields are changing en masse
 159         me.mon(labelable, 'errorchange', me.handleFieldErrorChange, me, {buffer: 10});
 160
 161         labelable.setFieldDefaults(me.fieldDefaults);
 162     },
 163
 164 <span id='Ext-form-FieldAncestor-method-onFieldAdded'>    /**
 165 </span>     * @protected Called when a {@link Ext.form.field.Field} instance is added to the container's subtree.
 166      * @param {Ext.form.field.Field} field The field which was added
 167      */
 168     onFieldAdded: function(field) {
 169         var me = this;
 170         me.mon(field, 'validitychange', me.handleFieldValidityChange, me);
 171     },
 172
 173 <span id='Ext-form-FieldAncestor-method-onLabelableRemoved'>    /**
 174 </span>     * @protected Called when a {@link Ext.form.Labelable} instance is removed from the container's subtree.
 175      * @param {Ext.form.Labelable} labelable The instance that was removed
 176      */
 177     onLabelableRemoved: function(labelable) {
 178         var me = this;
 179         me.mun(labelable, 'errorchange', me.handleFieldErrorChange, me);
 180     },
 181
 182 <span id='Ext-form-FieldAncestor-method-onFieldRemoved'>    /**
 183 </span>     * @protected Called when a {@link Ext.form.field.Field} instance is removed from the container's subtree.
 184      * @param {Ext.form.field.Field} field The field which was removed
 185      */
 186     onFieldRemoved: function(field) {
 187         var me = this;
 188         me.mun(field, 'validitychange', me.handleFieldValidityChange, me);
 189     },
 190
 191 <span id='Ext-form-FieldAncestor-method-handleFieldValidityChange'>    /**
 192 </span>     * @private Handle validitychange events on sub-fields; invoke the aggregated event and method
 193      */
 194     handleFieldValidityChange: function(field, isValid) {
 195         var me = this;
 196         me.fireEvent('fieldvaliditychange', me, field, isValid);
 197         me.onFieldValidityChange();
 198     },
 199
 200 <span id='Ext-form-FieldAncestor-method-handleFieldErrorChange'>    /**
 201 </span>     * @private Handle errorchange events on sub-fields; invoke the aggregated event and method
 202      */
 203     handleFieldErrorChange: function(labelable, activeError) {
 204         var me = this;
 205         me.fireEvent('fielderrorchange', me, labelable, activeError);
 206         me.onFieldErrorChange();
 207     },
 208
 209 <span id='Ext-form-FieldAncestor-property-onFieldValidityChange'>    /**
 210 </span>     * @protected Fired when the validity of any field within the container changes.
 211      * @param {Ext.form.field.Field} The sub-field whose validity changed
 212      * @param {String} The new validity state
 213      */
 214     onFieldValidityChange: Ext.emptyFn,
 215
 216 <span id='Ext-form-FieldAncestor-property-onFieldErrorChange'>    /**
 217 </span>     * @protected Fired when the error message of any field within the container changes.
 218      * @param {Ext.form.Labelable} The sub-field whose active error changed
 219      * @param {String} The new active error message
 220      */
 221     onFieldErrorChange: Ext.emptyFn
 222
 223 });</pre>
 224 </body>
 225 </html>