docs/source/FormLayout.html

   1 <html>\r
   2 <head>\r
   3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
   4   <title>The source code</title>\r
   5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
   6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
   7 </head>\r
   8 <body  onload="prettyPrint();">\r
   9     <pre class="prettyprint lang-js"><div id="cls-Ext.layout.FormLayout"></div>/**
  10  * @class Ext.layout.FormLayout
  11  * @extends Ext.layout.AnchorLayout
  12  * <p>This layout manager is specifically designed for rendering and managing child Components of
  13  * {@link Ext.form.FormPanel forms}. It is responsible for rendering the labels of
  14  * {@link Ext.form.Field Field}s.</p>
  15  *
  16  * <p>This layout manager is used when a Container is configured with the <tt>layout:'form'</tt>
  17  * {@link Ext.Container#layout layout} config option, and should generally not need to be created directly
  18  * via the new keyword. See <tt><b>{@link Ext.Container#layout}</b></tt> for additional details.</p>
  19  *
  20  * <p>In an application, it will usually be preferrable to use a {@link Ext.form.FormPanel FormPanel}
  21  * (which is configured with FormLayout as its layout class by default) since it also provides built-in
  22  * functionality for {@link Ext.form.BasicForm#doAction loading, validating and submitting} the form.</p>
  23  *
  24  * <p>A {@link Ext.Container Container} <i>using</i> the FormLayout layout manager (e.g.
  25  * {@link Ext.form.FormPanel} or specifying <tt>layout:'form'</tt>) can also accept the following
  26  * layout-specific config properties:<div class="mdetail-params"><ul>
  27  * <li><b><tt>{@link Ext.form.FormPanel#hideLabels hideLabels}</tt></b></li>
  28  * <li><b><tt>{@link Ext.form.FormPanel#labelAlign labelAlign}</tt></b></li>
  29  * <li><b><tt>{@link Ext.form.FormPanel#labelPad labelPad}</tt></b></li>
  30  * <li><b><tt>{@link Ext.form.FormPanel#labelSeparator labelSeparator}</tt></b></li>
  31  * <li><b><tt>{@link Ext.form.FormPanel#labelWidth labelWidth}</tt></b></li>
  32  * </ul></div></p>
  33  *
  34  * <p>Any Component (including Fields) managed by FormLayout accepts the following as a config option:
  35  * <div class="mdetail-params"><ul>
  36  * <li><b><tt>{@link Ext.Component#anchor anchor}</tt></b></li>
  37  * </ul></div></p>
  38  *
  39  * <p>Any Component managed by FormLayout may be rendered as a form field (with an associated label) by
  40  * configuring it with a non-null <b><tt>{@link Ext.Component#fieldLabel fieldLabel}</tt></b>. Components configured
  41  * in this way may be configured with the following options which affect the way the FormLayout renders them:
  42  * <div class="mdetail-params"><ul>
  43  * <li><b><tt>{@link Ext.Component#clearCls clearCls}</tt></b></li>
  44  * <li><b><tt>{@link Ext.Component#fieldLabel fieldLabel}</tt></b></li>
  45  * <li><b><tt>{@link Ext.Component#hideLabel hideLabel}</tt></b></li>
  46  * <li><b><tt>{@link Ext.Component#itemCls itemCls}</tt></b></li>
  47  * <li><b><tt>{@link Ext.Component#labelSeparator labelSeparator}</tt></b></li>
  48  * <li><b><tt>{@link Ext.Component#labelStyle labelStyle}</tt></b></li>
  49  * </ul></div></p>
  50  *
  51  * <p>Example usage:</p>
  52  * <pre><code>
  53 // Required if showing validation messages
  54 Ext.QuickTips.init();
  55
  56 // While you can create a basic Panel with layout:'form', practically
  57 // you should usually use a FormPanel to also get its form functionality
  58 // since it already creates a FormLayout internally.
  59 var form = new Ext.form.FormPanel({
  60     title: 'Form Layout',
  61     bodyStyle: 'padding:15px',
  62     width: 350,
  63     defaultType: 'textfield',
  64     defaults: {
  65         // applied to each contained item
  66         width: 230,
  67         msgTarget: 'side'
  68     },
  69     items: [{
  70             fieldLabel: 'First Name',
  71             name: 'first',
  72             allowBlank: false,
  73             {@link Ext.Component#labelSeparator labelSeparator}: ':' // override labelSeparator layout config
  74         },{
  75             fieldLabel: 'Last Name',
  76             name: 'last'
  77         },{
  78             fieldLabel: 'Email',
  79             name: 'email',
  80             vtype:'email'
  81         }, {
  82             xtype: 'textarea',
  83             hideLabel: true,     // override hideLabels layout config
  84             name: 'msg',
  85             anchor: '100% -53'
  86         }
  87     ],
  88     buttons: [
  89         {text: 'Save'},
  90         {text: 'Cancel'}
  91     ],
  92     layoutConfig: {
  93         {@link #labelSeparator}: '~' // superseded by assignment below
  94     },
  95     // config options applicable to container when layout='form':
  96     hideLabels: false,
  97     labelAlign: 'left',   // or 'right' or 'top'
  98     {@link Ext.form.FormPanel#labelSeparator labelSeparator}: '>>', // takes precedence over layoutConfig value
  99     labelWidth: 65,       // defaults to 100
 100     labelPad: 8           // defaults to 5, must specify labelWidth to be honored
 101 });
 102 </code></pre>
 103  */
 104 Ext.layout.FormLayout = Ext.extend(Ext.layout.AnchorLayout, {
 105
 106     <div id="cfg-Ext.layout.FormLayout-labelSeparator"></div>/**
 107      * @cfg {String} labelSeparator
 108      * See {@link Ext.form.FormPanel}.{@link Ext.form.FormPanel#labelSeparator labelSeparator}.  Configuration
 109      * of this property at the <b>container</b> level takes precedence.
 110      */
 111     labelSeparator : ':',
 112
 113     <div id="prop-Ext.layout.FormLayout-labelStyle"></div>/**
 114      * Read only. The CSS style specification string added to field labels in this layout if not
 115      * otherwise {@link Ext.Component#labelStyle specified by each contained field}.
 116      * @type String
 117      * @property labelStyle
 118      */
 119
 120     <div id="cfg-Ext.layout.FormLayout-trackLabels"></div>/**
 121      * @cfg {Boolean} trackLabels
 122      * True to show/hide the field label when the field is hidden. Defaults to <tt>false</tt>.
 123      */
 124     trackLabels: false,
 125
 126
 127     onRemove: function(c){
 128         Ext.layout.FormLayout.superclass.onRemove.call(this, c);
 129         if(this.trackLabels){
 130             c.un('show', this.onFieldShow, this);
 131             c.un('hide', this.onFieldHide, this);
 132         }
 133         // check for itemCt, since we may be removing a fieldset or something similar
 134         var el = c.getPositionEl(),
 135                 ct = c.getItemCt && c.getItemCt();
 136         if(c.rendered && ct){
 137             if (el && el.dom) {
 138                 el.insertAfter(ct);
 139             }
 140             Ext.destroy(ct);
 141             Ext.destroyMembers(c, 'label', 'itemCt');
 142             if(c.customItemCt){
 143                 Ext.destroyMembers(c, 'getItemCt', 'customItemCt');
 144             }
 145         }
 146     },
 147
 148     // private
 149     setContainer : function(ct){
 150         Ext.layout.FormLayout.superclass.setContainer.call(this, ct);
 151         if(ct.labelAlign){
 152             ct.addClass('x-form-label-'+ct.labelAlign);
 153         }
 154
 155         if(ct.hideLabels){
 156             Ext.apply(this, {
 157                 labelStyle: 'display:none',
 158                 elementStyle: 'padding-left:0;',
 159                 labelAdjust: 0
 160             });
 161         }else{
 162             this.labelSeparator = ct.labelSeparator || this.labelSeparator;
 163             ct.labelWidth = ct.labelWidth || 100;
 164             if(Ext.isNumber(ct.labelWidth)){
 165                 var pad = Ext.isNumber(ct.labelPad) ? ct.labelPad : 5;
 166                 Ext.apply(this, {
 167                     labelAdjust: ct.labelWidth + pad,
 168                     labelStyle: 'width:' + ct.labelWidth + 'px;',
 169                     elementStyle: 'padding-left:' + (ct.labelWidth + pad) + 'px'
 170                 });
 171             }
 172             if(ct.labelAlign == 'top'){
 173                 Ext.apply(this, {
 174                     labelStyle: 'width:auto;',
 175                     labelAdjust: 0,
 176                     elementStyle: 'padding-left:0;'
 177                 });
 178             }
 179         }
 180     },
 181
 182     // private
 183     isHide: function(c){
 184         return c.hideLabel || this.container.hideLabels;
 185     },
 186
 187     onFieldShow: function(c){
 188         c.getItemCt().removeClass('x-hide-' + c.hideMode);
 189     },
 190
 191     onFieldHide: function(c){
 192         c.getItemCt().addClass('x-hide-' + c.hideMode);
 193     },
 194
 195     //private
 196     getLabelStyle: function(s){
 197         var ls = '', items = [this.labelStyle, s];
 198         for (var i = 0, len = items.length; i < len; ++i){
 199             if (items[i]){
 200                 ls += items[i];
 201                 if (ls.substr(-1, 1) != ';'){
 202                     ls += ';'
 203                 }
 204             }
 205         }
 206         return ls;
 207     },
 208
 209     <div id="cfg-Ext.layout.FormLayout-fieldTpl"></div>/**
 210      * @cfg {Ext.Template} fieldTpl
 211      * A {@link Ext.Template#compile compile}d {@link Ext.Template} for rendering
 212      * the fully wrapped, labeled and styled form Field. Defaults to:</p><pre><code>
 213 new Ext.Template(
 214     &#39;&lt;div class="x-form-item {itemCls}" tabIndex="-1">&#39;,
 215         &#39;&lt;&#108;abel for="{id}" style="{labelStyle}" class="x-form-item-&#108;abel">{&#108;abel}{labelSeparator}&lt;/&#108;abel>&#39;,
 216         &#39;&lt;div class="x-form-element" id="x-form-el-{id}" style="{elementStyle}">&#39;,
 217         &#39;&lt;/div>&lt;div class="{clearCls}">&lt;/div>&#39;,
 218     '&lt;/div>'
 219 );
 220 </code></pre>
 221      * <p>This may be specified to produce a different DOM structure when rendering form Fields.</p>
 222      * <p>A description of the properties within the template follows:</p><div class="mdetail-params"><ul>
 223      * <li><b><tt>itemCls</tt></b> : String<div class="sub-desc">The CSS class applied to the outermost div wrapper
 224      * that contains this field label and field element (the default class is <tt>'x-form-item'</tt> and <tt>itemCls</tt>
 225      * will be added to that). If supplied, <tt>itemCls</tt> at the field level will override the default <tt>itemCls</tt>
 226      * supplied at the container level.</div></li>
 227      * <li><b><tt>id</tt></b> : String<div class="sub-desc">The id of the Field</div></li>
 228      * <li><b><tt>{@link #labelStyle}</tt></b> : String<div class="sub-desc">
 229      * A CSS style specification string to add to the field label for this field (defaults to <tt>''</tt> or the
 230      * {@link #labelStyle layout's value for <tt>labelStyle</tt>}).</div></li>
 231      * <li><b><tt>label</tt></b> : String<div class="sub-desc">The text to display as the label for this
 232      * field (defaults to <tt>''</tt>)</div></li>
 233      * <li><b><tt>{@link #labelSeparator}</tt></b> : String<div class="sub-desc">The separator to display after
 234      * the text of the label for this field (defaults to a colon <tt>':'</tt> or the
 235      * {@link #labelSeparator layout's value for labelSeparator}). To hide the separator use empty string ''.</div></li>
 236      * <li><b><tt>elementStyle</tt></b> : String<div class="sub-desc">The styles text for the input element's wrapper.</div></li>
 237      * <li><b><tt>clearCls</tt></b> : String<div class="sub-desc">The CSS class to apply to the special clearing div
 238      * rendered directly after each form field wrapper (defaults to <tt>'x-form-clear-left'</tt>)</div></li>
 239      * </ul></div>
 240      * <p>Also see <tt>{@link #getTemplateArgs}</tt></p>
 241      */
 242
 243     // private
 244     renderItem : function(c, position, target){
 245         if(c && (c.isFormField || c.fieldLabel) && c.inputType != 'hidden'){
 246             var args = this.getTemplateArgs(c);
 247             if(Ext.isNumber(position)){
 248                 position = target.dom.childNodes[position] || null;
 249             }
 250             if(position){
 251                 c.itemCt = this.fieldTpl.insertBefore(position, args, true);
 252             }else{
 253                 c.itemCt = this.fieldTpl.append(target, args, true);
 254             }
 255             if(!c.getItemCt){
 256                 // Non form fields don't have getItemCt, apply it here
 257                 // This will get cleaned up in onRemove
 258                 Ext.apply(c, {
 259                     getItemCt: function(){
 260                         return c.itemCt;
 261                     },
 262                     customItemCt: true
 263                 });
 264             }
 265             c.label = c.getItemCt().child('label.x-form-item-label');
 266             if(!c.rendered){
 267                 c.render('x-form-el-' + c.id);
 268             }else if(!this.isValidParent(c, target)){
 269                 Ext.fly('x-form-el-' + c.id).appendChild(c.getPositionEl());
 270             }
 271             if(this.trackLabels){
 272                 if(c.hidden){
 273                     this.onFieldHide(c);
 274                 }
 275                 c.on({
 276                     scope: this,
 277                     show: this.onFieldShow,
 278                     hide: this.onFieldHide
 279                 });
 280             }
 281             this.configureItem(c);
 282         }else {
 283             Ext.layout.FormLayout.superclass.renderItem.apply(this, arguments);
 284         }
 285     },
 286
 287     <div id="method-Ext.layout.FormLayout-getTemplateArgs"></div>/**
 288      * <p>Provides template arguments for rendering the fully wrapped, labeled and styled form Field.</p>
 289      * <p>This method returns an object hash containing properties used by the layout's {@link #fieldTpl}
 290      * to create a correctly wrapped, labeled and styled form Field. This may be overriden to
 291      * create custom layouts. The properties which must be returned are:</p><div class="mdetail-params"><ul>
 292      * <li><b><tt>itemCls</tt></b> : String<div class="sub-desc">The CSS class applied to the outermost div wrapper
 293      * that contains this field label and field element (the default class is <tt>'x-form-item'</tt> and <tt>itemCls</tt>
 294      * will be added to that). If supplied, <tt>itemCls</tt> at the field level will override the default <tt>itemCls</tt>
 295      * supplied at the container level.</div></li>
 296      * <li><b><tt>id</tt></b> : String<div class="sub-desc">The id of the Field</div></li>
 297      * <li><b><tt>{@link #labelStyle}</tt></b> : String<div class="sub-desc">
 298      * A CSS style specification string to add to the field label for this field (defaults to <tt>''</tt> or the
 299      * {@link #labelStyle layout's value for <tt>labelStyle</tt>}).</div></li>
 300      * <li><b><tt>label</tt></b> : String<div class="sub-desc">The text to display as the label for this
 301      * field (defaults to <tt>''</tt>)</div></li>
 302      * <li><b><tt>{@link #labelSeparator}</tt></b> : String<div class="sub-desc">The separator to display after
 303      * the text of the label for this field (defaults to a colon <tt>':'</tt> or the
 304      * {@link #labelSeparator layout's value for labelSeparator}). To hide the separator use empty string ''.</div></li>
 305      * <li><b><tt>elementStyle</tt></b> : String<div class="sub-desc">The styles text for the input element's wrapper.</div></li>
 306      * <li><b><tt>clearCls</tt></b> : String<div class="sub-desc">The CSS class to apply to the special clearing div
 307      * rendered directly after each form field wrapper (defaults to <tt>'x-form-clear-left'</tt>)</div></li>
 308      * </ul></div>
 309      * @param (Ext.form.Field} field The {@link Ext.form.Field Field} being rendered.
 310      * @return An object hash containing the properties required to render the Field.
 311      */
 312     getTemplateArgs: function(field) {
 313         var noLabelSep = !field.fieldLabel || field.hideLabel;
 314         return {
 315             id: field.id,
 316             label: field.fieldLabel,
 317             labelStyle: this.getLabelStyle(field.labelStyle),
 318             elementStyle: this.elementStyle||'',
 319             labelSeparator: noLabelSep ? '' : (Ext.isDefined(field.labelSeparator) ? field.labelSeparator : this.labelSeparator),
 320             itemCls: (field.itemCls||this.container.itemCls||'') + (field.hideLabel ? ' x-hide-label' : ''),
 321             clearCls: field.clearCls || 'x-form-clear-left'
 322         };
 323     },
 324
 325     // private
 326     adjustWidthAnchor: function(value, c){
 327         if(c.label && !this.isHide(c) && (this.container.labelAlign != 'top')){
 328             var adjust = Ext.isIE6 || (Ext.isIE && !Ext.isStrict);
 329             return value - this.labelAdjust + (adjust ? -3 : 0);
 330         }
 331         return value;
 332     },
 333
 334     adjustHeightAnchor : function(value, c){
 335         if(c.label && !this.isHide(c) && (this.container.labelAlign == 'top')){
 336             return value - c.label.getHeight();
 337         }
 338         return value;
 339     },
 340
 341     // private
 342     isValidParent : function(c, target){
 343         return target && this.container.getEl().contains(c.getPositionEl());
 344     }
 345
 346     <div id="prop-Ext.layout.FormLayout-activeItem"></div>/**
 347      * @property activeItem
 348      * @hide
 349      */
 350 });
 351
 352 Ext.Container.LAYOUTS['form'] = Ext.layout.FormLayout;
 353 </pre>    \r
 354 </body>\r
 355 </html>