Clear Up
SharpKit Reference

CheckboxGroup Class

A field container which has a specialized layout for arranging Ext.form.field.Checkbox controls into columns, and provides convenience Ext.form.field.Field methods for getting, setting, and validating the group of checkboxes as a whole.

Validation

Individual checkbox fields themselves have no default validation behavior, but sometimes you want to require a user to select at least one of a group of checkboxes. CheckboxGroup allows this by setting the config allowBlank:false; when the user does not check at least one of the checkboxes, the entire group will be highlighted as invalid and the error message will be displayed according to the msgTarget config.

Layout

The default layout for CheckboxGroup makes it easy to arrange the checkboxes into columns; see the columns and vertical config documentation for details. You may also use a completely different layout by setting the layout to one of the other supported layout types; for instance you may wish to use a custom arrangement of hbox and vbox containers. In that case the checkbox components at any depth will still be managed by the CheckboxGroup's validation.

  
    Ext.create('Ext.form.Panel', {
            title: 'Checkbox Group',
            width: 300,
            height: 125,
            bodyPadding: 10,
            renderTo: Ext.getBody(),
            items:[{
            xtype: 'checkboxgroup',
            fieldLabel: 'Two Columns',
            // Arrange checkboxes into two columns, distributed vertically
            columns: 2,
            vertical: true,
            items: [
            { boxLabel: 'Item 1', name: 'rb', inputValue: '1' },
            { boxLabel: 'Item 2', name: 'rb', inputValue: '2', checked: true },
            { boxLabel: 'Item 3', name: 'rb', inputValue: '3' },
            { boxLabel: 'Item 4', name: 'rb', inputValue: '4' },
            { boxLabel: 'Item 5', name: 'rb', inputValue: '5' },
            { boxLabel: 'Item 6', name: 'rb', inputValue: '6' }
            ]
            }]
            });
            

Namespace: Ext.form

Derived Types

Fields

Name Description
allowBlank False to validate that at least one item in the group is checked. If no items are selected at validation time, blankText will be used as the error text. Defaults to: true
blankText Error text to display if the allowBlank validation fails Defaults to: "You must select at least one item in this group"
columns Specifies the number of columns to use when displaying grouped checkbox/radio controls using automatic layout. This config can take several types of values:
  • 'auto' - The controls will be rendered one per column on one row and the width of each column will be evenly distributed based on the width of the overall field container. This is the default.
  • Number - If you specific a number (e.g., 3) that number of columns will be created and the contained controls will be automatically distributed based on the value of vertical.
  • Array - You can also specify an array of column widths, mixing integer (fixed width) and float (percentage width) values as needed (e.g., [100, .25, .75]). Any integer values will be rendered first, then any float values will be calculated as a percentage of the remaining space. Float values do not have to add up to 1 (100%) although if you want the controls to take up the entire field container you should do so.
  • Defaults to: "auto"
    name Overrides: Ext.form.field.Field.name
    submitValue Setting this to false will prevent the field from being submitted even when it is not disabled. Defaults to: true
    validateOnChange Specifies whether this field should be validated immediately whenever a change in its value is detected. If the validation results in a change in the field's validity, a validitychange event will be fired. This allows the field to show feedback about the validity of its contents immediately as the user is typing. When set to false, feedback will not be immediate. However the form will still be validated before submitting if the clientValidation option to Ext.form.Basic.doAction is enabled, or if the field or form are validated manually. See also Ext.form.field.Base.checkChangeEvents for controlling how changes to the field's value are detected. Defaults to: true
    value A value to initialize this field with.
    vertical True to distribute contained controls across columns, completely filling each column top to bottom before starting on the next column. The number of controls in each column will be automatically calculated to keep columns as even as possible. The default value is false, so that controls will be added to columns one at a time, completely filling each row left to right before starting on the next row. Defaults to: false

    Methods

    Name Description
    batchChanges(Delegate) A utility for grouping a set of modifications which may trigger value changes into a single transaction, to prevent excessive firing of change events. This is useful for instance if the field has sub-fields which are being updated as a group; you don't want the container field to check its own changed state for each subfield change.
    beforeReset() Template method before a field is reset.
    checkChange() Checks whether the value of the field has changed since the last time it was checked. If the value has changed, it:
  • Fires the change event,
  • Performs validation if the validateOnChange config is enabled, firing the validitychange event if the validity has changed, and
  • Checks the dirty state of the field and fires the dirtychange event if it has changed.
  • checkDirty() Checks the isDirty state of the field and if it has changed since the last time it was checked, fires the dirtychange event.
    clearInvalid() Clear any invalid styles/messages for this field. Components using this mixin should implement this method to update the components rendering to clear any existing messages. Note: this method does not cause the Field's validate or isValid methods to return true if the value does not pass validation. So simply clearing a field's errors will not necessarily allow submission of forms submitted with the Ext.form.action.Submit.clientValidation option set.
    extractFileInput() Only relevant if the instance's isFileUpload method returns true. Returns a reference to the file input DOM element holding the user's selected file. The input will be appended into the submission form and will not be returned, so this method should also create a replacement.
    getChecked() Returns an Array of all checkboxes in the container which are currently checked
    getErrors() Runs CheckboxGroup's validations and returns an array of any errors. The only error by default is if allowBlank is set to true and no items are checked.
    getErrors(object) Runs this field's validators and returns an array of error messages for any validation failures. This is called internally during validation and would not usually need to be used manually. Each subclass should override or augment the return value to provide their own errors.
    getModelData() Returns the value(s) that should be saved to the Ext.data.Model instance for this field, when Ext.form.Basic.updateRecord is called. Typically this will be an object with a single name-value pair, the name being this field's name and the value being its current data value. More advanced field implementations may return more than one name-value pair. The returned values will be saved to the corresponding field names in the Model. Note that the values returned from this method are not guaranteed to have been successfully validated.
    getName() Returns the name attribute of the field. This is used as the parameter name when including the field value in a form submit().
    getSubmitData() Returns the parameter(s) that would be included in a standard form submit for this field. Typically this will be an object with a single name-value pair, the name being this field's name and the value being its current stringified value. More advanced field implementations may return more than one name-value pair. Note that the values returned from this method are not guaranteed to have been successfully validated.
    getValue() Returns an object containing the values of all checked checkboxes within the group. Each key-value pair in the object corresponds to a checkbox name. If there is only one checked checkbox with a particular name, the value of that pair will be the String inputValue of that checkbox. If there are multiple checked checkboxes with that name, the value of that pair will be an Array of the selected inputValues. The object format returned from this method can also be passed directly to the setValue method. NOTE: In Ext 3, this method returned an array of Checkbox components; this was changed to make it more consistent with other field components and with the setValue argument signature. If you need the old behavior in Ext 4+, use the getChecked method instead. Overrides: Ext.form.field.Field.getValue
    initField() Initializes this Field mixin on the current instance. Components using this mixin should call this method during their own initialization process.
    initValue() Initializes the field's value based on the initial config. If the value config is specified then we use that to set the value; otherwise we initialize the originalValue by querying the values of all sub-checkboxes after they have been initialized. Overrides: Ext.form.field.Field.initValue
    isDirty() Returns true if the value of this Field has been changed from its originalValue. Will always return false if the field is disabled. Note that if the owning form was configured with trackResetOnLoad then the originalValue is updated when the values are loaded by Ext.form.Basic.setValues.
    isEqual(object, object) Returns whether two field values are logically equal. Field implementations may override this to provide custom comparison logic appropriate for the particular field's data type.
    isEqualAsString(object, object) Returns whether two values are logically equal. Similar to isEqual, however null or undefined values will be treated as empty strings.
    isFileUpload() Returns whether this Field is a file upload field; if it returns true, forms will use special techniques for submitting the form via AJAX. See Ext.form.Basic.hasUpload for details. If this returns true, the extractFileInput method must also be implemented to return the corresponding file input element.
    isValid() Returns whether or not the field value is currently valid by validating the field's current value. The validitychange event will not be fired; use validate instead if you want the event to fire. Note: disabled fields are always treated as valid. Implementations are encouraged to ensure that this method does not have side-effects such as triggering error message display.
    markInvalid(object) Associate one or more error messages with this field. Components using this mixin should implement this method to update the component's rendering to display the messages. Note: this method does not cause the Field's validate or isValid methods to return false if the value does pass validation. So simply marking a Field as invalid will not prevent submission of forms submitted with the Ext.form.action.Submit.clientValidation option set.
    onChange(object, object) Called when the field's value changes. Performs validation if the validateOnChange config is enabled, and invokes the dirty check.
    onDirtyChange(bool) Called when the field's dirty state changes.
    reset() Resets the checked state of all checkboxes in the group to their originally loaded values and clears any validation messages. See Ext.form.Basic.trackResetOnLoad Overrides: Ext.form.field.Field.reset
    resetOriginalValue() Resets the field's originalValue property so it matches the current value. This is called by Ext.form.Basic.setValues if the form's trackResetOnLoad property is set to true.
    setValue(object) Sets the value(s) of all checkboxes in the group. The expected format is an Object of name-value pairs corresponding to the names of the checkboxes in the group. Each pair can have either a single or multiple values:
  • A single Boolean or String value will be passed to the setValue method of the checkbox with that name. See the rules in Ext.form.field.Checkbox.setValue for accepted values.
  • An Array of String values will be matched against the inputValue of checkboxes in the group with that name; those checkboxes whose inputValue exists in the array will be checked and others will be unchecked.
  • If a checkbox's name is not in the mapping at all, it will be unchecked. An example:
    var myCheckboxGroup = new Ext.form.CheckboxGroup({
                columns: 3,
                items: [{
                name: 'cb1',
                boxLabel: 'Single 1'
                }, {
                name: 'cb2',
                boxLabel: 'Single 2'
                }, {
                name: 'cb3',
                boxLabel: 'Single 3'
                }, {
                name: 'cbGroup',
                boxLabel: 'Grouped 1'
                inputValue: 'value1'
                }, {
                name: 'cbGroup',
                boxLabel: 'Grouped 2'
                inputValue: 'value2'
                }, {
                name: 'cbGroup',
                boxLabel: 'Grouped 3'
                inputValue: 'value3'
                }]
                });
                myCheckboxGroup.setValue({
                cb1: true,
                cb3: false,
                cbGroup: ['value1', 'value3']
                });
                
    The above code will cause the checkbox named 'cb1' to be checked, as well as the first and third checkboxes named 'cbGroup'. The other three checkboxes will be unchecked.
    transformOriginalValue(object) Allows for any necessary modifications before the original value is set
    validate() Returns whether or not the field value is currently valid by validating the field's current value, and fires the validitychange event if the field's validity has changed since the last validation. Note: disabled fields are always treated as valid. Custom implementations of this method are allowed to have side-effects such as triggering error message display. To validate without side-effects, use isValid.

    Properties

    Name Description
    isFormField Flag denoting that this component is a Field. Always true. Defaults to: true
    originalValue The original value of the field as configured in the value configuration, or as loaded by the last form load operation if the form's trackResetOnLoad setting is true.
    suspendCheckChange Defaults to: 0
    © Copyright 2005-2011 SharpKit. All rights reserved.