docs/source/FormLayout.html

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