Clear Up
SharpKit Reference

FieldContainer Class

FieldContainer is a derivation of Container that implements the Labelable mixin. This allows it to be configured so that it is rendered with a field label and optional error message around its sub-items. This is useful for arranging a group of fields or other components within a single item in a form, so that it lines up nicely with other fields. A common use is for grouping a set of related fields under a single label in a form.

The container's configured items will be layed out within the field body area according to the configured layout type. The default layout is 'autocontainer'.

Like regular fields, FieldContainer can inherit its decoration configuration from the fieldDefaults of an enclosing FormPanel. In addition, FieldContainer itself can pass fieldDefaults to any fields it may itself contain.

If you are grouping a set of Checkbox or Radio fields in a single labeled container, consider using a Ext.form.CheckboxGroup or Ext.form.RadioGroup instead as they are specialized for handling those types.

Example

  
    Ext.create('Ext.form.Panel', {
            title: 'FieldContainer Example',
            width: 550,
            bodyPadding: 10,
            items: [{
            xtype: 'fieldcontainer',
            fieldLabel: 'Last Three Jobs',
            labelWidth: 100,
            // The body area will contain three text fields, arranged
            // horizontally, separated by draggable splitters.
            layout: 'hbox',
            items: [{
            xtype: 'textfield',
            flex: 1
            }, {
            xtype: 'splitter'
            }, {
            xtype: 'textfield',
            flex: 1
            }, {
            xtype: 'splitter'
            }, {
            xtype: 'textfield',
            flex: 1
            }]
            }],
            renderTo: Ext.getBody()
            });
            

Usage of fieldDefaults

  
    Ext.create('Ext.form.Panel', {
            title: 'FieldContainer Example',
            width: 350,
            bodyPadding: 10,
            items: [{
            xtype: 'fieldcontainer',
            fieldLabel: 'Your Name',
            labelWidth: 75,
            defaultType: 'textfield',
            // Arrange fields vertically, stretched to full width
            layout: 'anchor',
            defaults: {
            layout: '100%'
            },
            // These config values will be applied to both sub-fields, except
            // for Last Name which will use its own msgTarget.
            fieldDefaults: {
            msgTarget: 'under',
            labelAlign: 'top'
            },
            items: [{
            fieldLabel: 'First Name',
            name: 'firstName'
            }, {
            fieldLabel: 'Last Name',
            name: 'lastName',
            msgTarget: 'under'
            }]
            }],
            renderTo: Ext.getBody()
            });
            

Namespace: Ext.form

Fields

Name Description
activeError If specified, then the component will be displayed with this value as its active error when first rendered. Use setActiveError or unsetActiveError to change it after component creation.
activeErrorsTpl The template used to format the Array of error messages passed to setActiveErrors into a single HTML string. By default this renders each message as an item in an unordered list. Defaults to: ["<tpl if="errors && errors.length">", "<ul><tpl for="errors"><li>{.}</li></tpl></ul>", "</tpl>"]
afterBodyEl An optional string or XTemplate configuration to insert in the field markup at the end of the input containing element. If an XTemplate is used, the component's render data serves as the context.
afterLabelTextTpl An optional string or XTemplate configuration to insert in the field markup after the label text. If an XTemplate is used, the component's render data serves as the context.
afterLabelTpl An optional string or XTemplate configuration to insert in the field markup after the label element. If an XTemplate is used, the component's render data serves as the context.
afterSubTpl An optional string or XTemplate configuration to insert in the field markup after the subTpl markup. If an XTemplate is used, the component's render data serves as the context.
autoFitErrors Whether to adjust the component's body area to make room for 'side' or 'under' error messages. Defaults to: true
baseBodyCls The CSS class to be applied to the body content element. Defaults to: "x-form-item-body"
beforeBodyEl An optional string or XTemplate configuration to insert in the field markup at the beginning of the input containing element. If an XTemplate is used, the component's render data serves as the context.
beforeLabelTextTpl An optional string or XTemplate configuration to insert in the field markup before the label text. If an XTemplate is used, the component's render data serves as the context.
beforeLabelTpl An optional string or XTemplate configuration to insert in the field markup before the label element. If an XTemplate is used, the component's render data serves as the context.
beforeSubTpl An optional string or XTemplate configuration to insert in the field markup before the subTpl markup. If an XTemplate is used, the component's render data serves as the context.
clearCls The CSS class to be applied to the special clearing div rendered directly after the field contents wrapper to provide field clearing. Defaults to: "x-clear"
combineErrors If set to true, the field container will automatically combine and display the validation errors from all the fields it contains as a single error on the container, according to the configured msgTarget. Defaults to false. Defaults to: false
combineLabels If set to true, and there is no defined fieldLabel, the field container will automatically generate its label by combining the labels of all the fields it contains. Defaults to false. Defaults to: false
errorMsgCls The CSS class to be applied to the error message element. Defaults to: "x-form-error-msg"
fieldBodyCls An extra CSS class to be applied to the body content element in addition to baseBodyCls. Defaults to: ""
fieldDefaults If specified, the properties in this object are used as default config values for each Ext.form.Labelable instance (e.g. Ext.form.field.Base or Ext.form.FieldContainer) that is added as a descendant of this container. Corresponding values specified in an individual field's own configuration, or from the defaults config of its parent container, will take precedence. See the documentation for Ext.form.Labelable to see what config options may be specified in the fieldDefaults. Example:
new Ext.form.Panel({
            fieldDefaults: {
            labelAlign: 'left',
            labelWidth: 100
            },
            items: [{
            xtype: 'fieldset',
            defaults: {
            labelAlign: 'top'
            },
            items: [{
            name: 'field1'
            }, {
            name: 'field2'
            }]
            }, {
            xtype: 'fieldset',
            items: [{
            name: 'field3',
            labelWidth: 150
            }, {
            name: 'field4'
            }]
            }]
            });
            
In this example, field1 and field2 will get labelAlign:'top' (from the fieldset's defaults) and labelWidth:100 (from fieldDefaults), field3 and field4 will both get labelAlign:'left' (from fieldDefaults and field3 will use the labelWidth:150 from its own config.
fieldLabel The label for the field. It gets appended with the labelSeparator, and its position and sizing is determined by the labelAlign, labelWidth, and labelPad configs.
formItemCls 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"
hideEmptyLabel When set to true, the label element (fieldLabel and labelSeparator) will be automatically hidden if the fieldLabel is empty. Setting this to false 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. If you wish to unconditionall hide the label even if a non-empty fieldLabel is configured, then set the hideLabel config to true. Defaults to: true
hideLabel Set to true to completely hide the label element (fieldLabel and labelSeparator). Also see hideEmptyLabel, which controls whether space will be reserved for an empty fieldLabel. Defaults to: false
invalidCls The CSS class to use when marking the component invalid. Defaults to: "x-form-invalid"
labelableRenderTpl The rendering template for the field decorations. Component classes using this mixin should include logic to use this as their renderTpl, and implement the getSubTplMarkup method to generate the field body content. The structure of a field is a table as follows: If labelAlign: 'left',msgTarget: 'side'`
+----------------------+----------------------+-------------+
           | Label:               | InputField           | sideErrorEl |
           +----------------------+----------------------+-------------+
            
If labelAlign: 'left',msgTarget: 'under'`
+----------------------+------------------------------------+
           | Label:               | InputField      (colspan=2)        |
           |                      | underErrorEl                       |
           +----------------------+------------------------------------+
            
If labelAlign: 'top',msgTarget: 'side'`
+---------------------------------------------+-------------+
           | label                                       |             |
           | InputField                                  | sideErrorEl |
           +---------------------------------------------+-------------+
            
If labelAlign: 'top',msgTarget: 'under'`
+-----------------------------------------------------------+
           | label                                                     |
           | InputField                      (colspan=2)               |
           | underErrorEl                                              |
           +-----------------------------------------------------------+
            
The total columns always the same for fields with each setting of labelAlign because when rendered into a Ext.layout.container.Form layout, just the TR of the table will be placed into the form's main TABLE, and the columns of all the siblings must match so that they all line up. In a Ext.layout.container.Form layout, different settings of labelAlign are not supported because of the incompatible column structure. When the triggerCell or side error cell are hidden or shown, the input cell's colspan is recalculated to maintain the correct 3 visible column count. Defaults to: ["<tr id="{id}-inputRow" <tpl if="inFormLayout">id="{id}"</tpl>>", "<tpl if="labelOnLeft">", "<td id="{id}-labelCell" style="{labelCellStyle}" {labelCellAttrs}>", "{beforeLabelTpl}", "<label id="{id}-labelEl" {labelAttrTpl}<tpl if="inputId"> for="{inputId}"</tpl> class="{labelCls}"", "<tpl if="labelStyle"> style="{labelStyle}"</tpl>>", "{beforeLabelTextTpl}", "<tpl if="fieldLabel">{fieldLabel}{labelSeparator}</tpl>", "{afterLabelTextTpl}", "</label>", "{afterLabelTpl}", "</td>", "</tpl>", "<td class="{baseBodyCls} {fieldBodyCls}" id="{id}-bodyEl" colspan="{bodyColspan}" role="presentation">", "{beforeBodyEl}", "<tpl if="labelAlign==\'top\'">", "{beforeLabelTpl}", "<div id="{id}-labelCell" style="{labelCellStyle}">", "<label id="{id}-labelEl" {labelAttrTpl}<tpl if="inputId"> for="{inputId}"</tpl> class="{labelCls}"", "<tpl if="labelStyle"> style="{labelStyle}"</tpl>>", "{beforeLabelTextTpl}", "<tpl if="fieldLabel">{fieldLabel}{labelSeparator}</tpl>", "{afterLabelTextTpl}", "</label>", "</div>", "{afterLabelTpl}", "</tpl>", "{beforeSubTpl}", "{[values.$comp.getSubTplMarkup()]}", "{afterSubTpl}", "<tpl if="msgTarget===\'side\'">", "{afterBodyEl}", "</td>", "<td id="{id}-sideErrorCell" vAlign="{[values.labelAlign===\'top\' && !values.hideLabel ? \'bottom\' : \'middle\']}" style="{[values.autoFitErrors ? \'display:none\' : \'\']}" width="{errorIconWidth}">", "<div id="{id}-errorEl" class="{errorMsgCls}" style="display:none;width:{errorIconWidth}px"></div>", "</td>", "<tpl elseif="msgTarget==\'under\'">", "<div id="{id}-errorEl" class="{errorMsgClass}" colspan="2" style="display:none"></div>", "{afterBodyEl}", "</td>", "</tpl>", "</tr>", {disableFormats: true}]
labelAlign Controls the position and alignment of the fieldLabel. Valid values are:
  • "left" (the default) - The label is positioned to the left of the field, with its text aligned to the left. Its width is determined by the labelWidth config.
  • "top" - The label is positioned above the field.
  • "right" - The label is positioned to the left of the field, with its text aligned to the right. Its width is determined by the labelWidth config.
  • Defaults to: "left"
    labelAttrTpl An optional string or XTemplate configuration to insert in the field markup inside the label element (as attributes). If an XTemplate is used, the component's render data serves as the context.
    labelCls 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 labelAlign. To add additional classes, use labelClsExtra. Defaults to: "x-form-item-label"
    labelClsExtra An optional string of one or more additional CSS classes to add to the label element. Defaults to empty.
    labelConnector The string to use when joining the labels of individual sub-fields, when combineLabels is set to true. Defaults to ', '. Defaults to: ", "
    labelPad The amount of space in pixels between the fieldLabel and the input field. Defaults to: 5
    labelSeparator Character(s) to be inserted at the end of the label text. Set to empty string to hide the separator completely. Defaults to: ":"
    labelStyle A CSS style specification string to apply directly to this field's label.
    labelWidth The width of the fieldLabel in pixels. Only applicable if the labelAlign is set to "left" or "right". Defaults to: 100
    msgTarget The location where the error message text should display. Must be one of the following values:
  • qtip Display a quick tip containing the message when the user hovers over the field. This is the default.

    Ext.tip.QuickTipManager.init must have been called for this setting to work.

  • title Display the message in a default browser title attribute popup.

  • under Add a block div beneath the field containing the error message.
  • side Add an error icon to the right of the field, displaying the message in a popup on hover.
  • none Don't display any error message. This might be useful if you are implementing custom error display.
  • [element id] Add the error message directly to the innerHTML of the specified element.
  • Defaults to: "qtip"
    preventMark true to disable displaying any error message set on this object. Defaults to: false

    Properties

    Name Description
    bodyEl The div Element wrapping the component's contents. Only available after the component has been rendered.
    errorEl The div Element that will contain the component's error message(s). Note that depending on the configured 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.
    isFieldLabelable Flag denoting that this object is labelable as a field. Always true. Defaults to: true
    labelCell The <TD> Element which contains the label Element for this component. Only available after the component has been rendered.
    labelEl The label Element for this component. Only available after the component has been rendered.
    noWrap Tells the layout system that the height can be measured immediately because the width does not need setting. Defaults to: true

    Methods

    Name Description
    getActiveError() 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.
    getActiveErrors() 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.
    getBodyColspan() Calculates the colspan value for the body cell - the cell which contains the input field. The field table structure contains 4 columns:
    getCombinedErrors(JsArray<T>) Takes an Array of invalid Ext.form.field.Field objects and builds a combined list of error messages from them. Defaults to prepending each message by the field name and a colon. This can be overridden to provide custom combined error message handling, for instance changing the format of each message or sorting the array (it is sorted in order of appearance by default).
    getFieldLabel() Returns the combined field label if combineLabels is set to true and if there is no set fieldLabel. Otherwise returns the fieldLabel like normal. You can also override this method to provide a custom generated label.

    This is a template method. a hook into the functionality of this class. Feel free to override it in child classes.

    getInputId() 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 input element.
    getLabelableRenderData() Generates the arguments for the field decorations rendering template.
    getLabelStyle() Gets any label styling for the labelEl
    getSubTplMarkup() 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.
    handleFieldErrorChange(object, object) Handle errorchange events on sub-fields; invoke the aggregated event and method
    handleFieldValidityChange(object, object) Handle validitychange events on sub-fields; invoke the aggregated event and method
    hasActiveError() 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.
    hasVisibleLabel() Checks if the field has a visible label
    initFieldAncestor() Initializes the FieldAncestor's state; this must be called from the initComponent method of any components importing this mixin.
    initFieldDefaults() Initialize the fieldDefaults object
    initLabelable() Performs initialization of this mixin. Component classes using this mixin should call this method during their own initialization.
    onFieldAdded(Field) Called when a Ext.form.field.Field instance is added to the container's subtree.
    onFieldAncestorSubtreeChange(object, object) Handle the addition and removal of components in the FieldAncestor component's child tree.
    onFieldErrorChange(Labelable, JsString) Fired when the error message of any field within the container changes, and updates the combined error message to match.
    onFieldRemoved(Field) Called when a Ext.form.field.Field instance is removed from the container's subtree.
    onFieldValidityChange(Field, bool) Fired when the validity of any field within the container changes.
    onLabelableAdded(Labelable) Called when a Ext.form.Labelable instance is added to the container's subtree.
    onLabelableRemoved(Labelable) Called when a Ext.form.Labelable instance is removed from the container's subtree.
    renderActiveError() 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.
    setActiveError(JsString) Sets the active error message to the given string. This replaces the entire error message contents with the given string. Also see setActiveErrors which accepts an Array of messages and formats them according to the 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 Ext.form.field.Base you should call markInvalid instead.
    setActiveErrors(JsArray<T>) Set the active error message to an Array of error messages. The messages are formatted into a single message string using the activeErrorsTpl. Also see setActiveError which allows setting the entire error contents with a single string. 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 Ext.form.field.Base you should call markInvalid instead.
    setFieldDefaults(object) 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.
    setFieldLabel(JsString) Set the label of this field.
    trimLabelSeparator() Returns the trimmed label by slicing off the label separator character. Can be overridden.
    unsetActiveError() 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 Ext.form.field.Base you should call clearInvalid instead.
    © Copyright 2005-2011 SharpKit. All rights reserved.