docs/source/FieldContainer.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="../prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../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-FieldContainer'>/**
  19 </span> * @class Ext.form.FieldContainer
  20  * @extends Ext.container.Container
  21
  22 FieldContainer is a derivation of {@link Ext.container.Container Container} that implements the
  23 {@link Ext.form.Labelable Labelable} mixin. This allows it to be configured so that it is rendered with
  24 a {@link #fieldLabel field label} and optional {@link #msgTarget error message} around its sub-items.
  25 This is useful for arranging a group of fields or other components within a single item in a form, so
  26 that it lines up nicely with other fields. A common use is for grouping a set of related fields under
  27 a single label in a form.
  28
  29 The container's configured {@link #items} will be layed out within the field body area according to the
  30 configured {@link #layout} type. The default layout is `'autocontainer'`.
  31
  32 Like regular fields, FieldContainer can inherit its decoration configuration from the
  33 {@link Ext.form.Panel#fieldDefaults fieldDefaults} of an enclosing FormPanel. In addition,
  34 FieldContainer itself can pass {@link #fieldDefaults} to any {@link Ext.form.Labelable fields}
  35 it may itself contain.
  36
  37 If you are grouping a set of {@link Ext.form.field.Checkbox Checkbox} or {@link Ext.form.field.Radio Radio}
  38 fields in a single labeled container, consider using a {@link Ext.form.CheckboxGroup}
  39 or {@link Ext.form.RadioGroup} instead as they are specialized for handling those types.
  40 {@img Ext.form.FieldContainer/Ext.form.FieldContainer1.png Ext.form.FieldContainer component}
  41 __Example usage:__
  42
  43     Ext.create('Ext.form.Panel', {
  44         title: 'FieldContainer Example',
  45         width: 550,
  46         bodyPadding: 10,
  47
  48         items: [{
  49             xtype: 'fieldcontainer',
  50             fieldLabel: 'Last Three Jobs',
  51             labelWidth: 100,
  52
  53             // The body area will contain three text fields, arranged
  54             // horizontally, separated by draggable splitters.
  55             layout: 'hbox',
  56             items: [{
  57                 xtype: 'textfield',
  58                 flex: 1
  59             }, {
  60                 xtype: 'splitter'
  61             }, {
  62                 xtype: 'textfield',
  63                 flex: 1
  64             }, {
  65                 xtype: 'splitter'
  66             }, {
  67                 xtype: 'textfield',
  68                 flex: 1
  69             }]
  70         }],
  71         renderTo: Ext.getBody()
  72     });
  73
  74 __Usage of {@link #fieldDefaults}:__
  75 {@img Ext.form.FieldContainer/Ext.form.FieldContainer2.png Ext.form.FieldContainer component}
  76
  77     Ext.create('Ext.form.Panel', {
  78         title: 'FieldContainer Example',
  79         width: 350,
  80         bodyPadding: 10,
  81
  82         items: [{
  83             xtype: 'fieldcontainer',
  84             fieldLabel: 'Your Name',
  85             labelWidth: 75,
  86             defaultType: 'textfield',
  87
  88             // Arrange fields vertically, stretched to full width
  89             layout: 'anchor',
  90             defaults: {
  91                 layout: '100%'
  92             },
  93
  94             // These config values will be applied to both sub-fields, except
  95             // for Last Name which will use its own msgTarget.
  96             fieldDefaults: {
  97                 msgTarget: 'under',
  98                 labelAlign: 'top'
  99             },
 100
 101             items: [{
 102                 fieldLabel: 'First Name',
 103                 name: 'firstName'
 104             }, {
 105                 fieldLabel: 'Last Name',
 106                 name: 'lastName',
 107                 msgTarget: 'under'
 108             }]
 109         }],
 110         renderTo: Ext.getBody()
 111     });
 112
 113
 114  * @markdown
 115  * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
 116  */
 117 Ext.define('Ext.form.FieldContainer', {
 118     extend: 'Ext.container.Container',
 119     mixins: {
 120         labelable: 'Ext.form.Labelable',
 121         fieldAncestor: 'Ext.form.FieldAncestor'
 122     },
 123     alias: 'widget.fieldcontainer',
 124
 125     componentLayout: 'field',
 126
 127 <span id='Ext-form-FieldContainer-cfg-combineLabels'>    /**
 128 </span>     * @cfg {Boolean} combineLabels
 129      * If set to true, and there is no defined {@link #fieldLabel}, the field container will automatically
 130      * generate its label by combining the labels of all the fields it contains. Defaults to false.
 131      */
 132     combineLabels: false,
 133
 134 <span id='Ext-form-FieldContainer-cfg-labelConnector'>    /**
 135 </span>     * @cfg {String} labelConnector
 136      * The string to use when joining the labels of individual sub-fields, when {@link #combineLabels} is
 137      * set to true. Defaults to ', '.
 138      */
 139     labelConnector: ', ',
 140
 141 <span id='Ext-form-FieldContainer-cfg-combineErrors'>    /**
 142 </span>     * @cfg {Boolean} combineErrors
 143      * If set to true, the field container will automatically combine and display the validation errors from
 144      * all the fields it contains as a single error on the container, according to the configured
 145      * {@link #msgTarget}. Defaults to false.
 146      */
 147     combineErrors: false,
 148
 149     maskOnDisable: false,
 150
 151     initComponent: function() {
 152         var me = this,
 153             onSubCmpAddOrRemove = me.onSubCmpAddOrRemove;
 154
 155         // Init mixins
 156         me.initLabelable();
 157         me.initFieldAncestor();
 158
 159         me.callParent();
 160     },
 161
 162 <span id='Ext-form-FieldContainer-method-onLabelableAdded'>    /**
 163 </span>     * @protected Called when a {@link Ext.form.Labelable} instance is added to the container's subtree.
 164      * @param {Ext.form.Labelable} labelable The instance that was added
 165      */
 166     onLabelableAdded: function(labelable) {
 167         var me = this;
 168         me.mixins.fieldAncestor.onLabelableAdded.call(this, labelable);
 169         me.updateLabel();
 170     },
 171
 172 <span id='Ext-form-FieldContainer-method-onLabelableRemoved'>    /**
 173 </span>     * @protected Called when a {@link Ext.form.Labelable} instance is removed from the container's subtree.
 174      * @param {Ext.form.Labelable} labelable The instance that was removed
 175      */
 176     onLabelableRemoved: function(labelable) {
 177         var me = this;
 178         me.mixins.fieldAncestor.onLabelableRemoved.call(this, labelable);
 179         me.updateLabel();
 180     },
 181
 182     onRender: function() {
 183         var me = this,
 184             renderSelectors = me.renderSelectors,
 185             applyIf = Ext.applyIf;
 186
 187         applyIf(renderSelectors, me.getLabelableSelectors());
 188
 189         me.callParent(arguments);
 190     },
 191
 192     initRenderTpl: function() {
 193         var me = this;
 194         if (!me.hasOwnProperty('renderTpl')) {
 195             me.renderTpl = me.getTpl('labelableRenderTpl');
 196         }
 197         return me.callParent();
 198     },
 199
 200     initRenderData: function() {
 201         return Ext.applyIf(this.callParent(), this.getLabelableRenderData());
 202     },
 203
 204 <span id='Ext-form-FieldContainer-method-getFieldLabel'>    /**
 205 </span>     * Returns the combined field label if {@link #combineLabels} is set to true and if there is no
 206      * set {@link #fieldLabel}. Otherwise returns the fieldLabel like normal. You can also override
 207      * this method to provide a custom generated label.
 208      */
 209     getFieldLabel: function() {
 210         var label = this.fieldLabel || '';
 211         if (!label &amp;&amp; this.combineLabels) {
 212             label = Ext.Array.map(this.query('[isFieldLabelable]'), function(field) {
 213                 return field.getFieldLabel();
 214             }).join(this.labelConnector);
 215         }
 216         return label;
 217     },
 218
 219 <span id='Ext-form-FieldContainer-method-updateLabel'>    /**
 220 </span>     * @private Updates the content of the labelEl if it is rendered
 221      */
 222     updateLabel: function() {
 223         var me = this,
 224             label = me.labelEl;
 225         if (label) {
 226             label.update(me.getFieldLabel());
 227         }
 228     },
 229
 230
 231 <span id='Ext-form-FieldContainer-method-onFieldErrorChange'>    /**
 232 </span>     * @private Fired when the error message of any field within the container changes, and updates the
 233      * combined error message to match.
 234      */
 235     onFieldErrorChange: function(field, activeError) {
 236         if (this.combineErrors) {
 237             var me = this,
 238                 oldError = me.getActiveError(),
 239                 invalidFields = Ext.Array.filter(me.query('[isFormField]'), function(field) {
 240                     return field.hasActiveError();
 241                 }),
 242                 newErrors = me.getCombinedErrors(invalidFields);
 243
 244             if (newErrors) {
 245                 me.setActiveErrors(newErrors);
 246             } else {
 247                 me.unsetActiveError();
 248             }
 249
 250             if (oldError !== me.getActiveError()) {
 251                 me.doComponentLayout();
 252             }
 253         }
 254     },
 255
 256 <span id='Ext-form-FieldContainer-method-getCombinedErrors'>    /**
 257 </span>     * Takes an Array of invalid {@link Ext.form.field.Field} objects and builds a combined list of error
 258      * messages from them. Defaults to prepending each message by the field name and a colon. This
 259      * can be overridden to provide custom combined error message handling, for instance changing
 260      * the format of each message or sorting the array (it is sorted in order of appearance by default).
 261      * @param {Array} invalidFields An Array of the sub-fields which are currently invalid.
 262      * @return {Array} The combined list of error messages
 263      */
 264     getCombinedErrors: function(invalidFields) {
 265         var forEach = Ext.Array.forEach,
 266             errors = [];
 267         forEach(invalidFields, function(field) {
 268             forEach(field.getActiveErrors(), function(error) {
 269                 var label = field.getFieldLabel();
 270                 errors.push((label ? label + ': ' : '') + error);
 271             });
 272         });
 273         return errors;
 274     },
 275
 276     getTargetEl: function() {
 277         return this.bodyEl || this.callParent();
 278     }
 279 });
 280 </pre>
 281 </body>
 282 </html>