A grouping container for {@link Ext.form.Checkbox} controls.
- *
Sample usage:
- *
-var myCheckboxGroup = new Ext.form.CheckboxGroup({
- id:'myGroup',
- xtype: 'checkboxgroup',
- fieldLabel: 'Single Column',
- itemCls: 'x-check-group-alt',
- // Put all controls in a single column with width 100%
- columns: 1,
- items: [
- {boxLabel: 'Item 1', name: 'cb-col-1'},
- {boxLabel: 'Item 2', name: 'cb-col-2', checked: true},
- {boxLabel: 'Item 3', name: 'cb-col-3'}
- ]
+Sencha Documentation Project
/**
+ * @class Ext.form.CheckboxGroup
+ * @extends Ext.form.FieldContainer
+ * <p>A {@link Ext.form.FieldContainer field container} which has a specialized layout for arranging
+ * {@link Ext.form.field.Checkbox} controls into columns, and provides convenience {@link Ext.form.field.Field} methods
+ * for {@link #getValue getting}, {@link #setValue setting}, and {@link #validate validating} the group
+ * of checkboxes as a whole.</p>
+ * <p><b>Validation:</b> 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 <tt>{@link #allowBlank}:false</tt>; when the user does not check at
+ * least one of the checkboxes, the entire group will be highlighted as invalid and the
+ * {@link #blankText error message} will be displayed according to the {@link #msgTarget} config.</p>
+ * <p><b>Layout:</b> The default layout for CheckboxGroup makes it easy to arrange the checkboxes into
+ * columns; see the {@link #columns} and {@link #vertical} config documentation for details. You may also
+ * use a completely different layout by setting the {@link #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.</p>
+ * {@img Ext.form.RadioGroup/Ext.form.RadioGroup.png Ext.form.RadioGroup component}
+ * <p>Example usage:</p>
+ * <pre><code>
+Ext.create('Ext.form.Panel', {
+ title: 'RadioGroup Example',
+ width: 300,
+ height: 125,
+ bodyPadding: 10,
+ renderTo: Ext.getBody(),
+ items:[{
+ xtype: 'radiogroup',
+ fieldLabel: 'Two Columns',
+ // Arrange radio buttons 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'}
+ ]
+ }]
});
- *
+ * </code></pre>
* @constructor
* Creates a new CheckboxGroup
* @param {Object} config Configuration options
* @xtype checkboxgroup
*/
-Ext.form.CheckboxGroup = Ext.extend(Ext.form.Field, {
- /**
- * @cfg {Array} items An Array of {@link Ext.form.Checkbox Checkbox}es or Checkbox config objects
+Ext.define('Ext.form.CheckboxGroup', {
+ extend:'Ext.form.FieldContainer',
+ mixins: {
+ field: 'Ext.form.field.Field'
+ },
+ alias: 'widget.checkboxgroup',
+ requires: ['Ext.layout.container.CheckboxGroup', 'Ext.form.field.Base'],
+
+ /**
+ * @cfg {String} name
+ * @hide
+ */
+
+ /**
+ * @cfg {Array} items An Array of {@link Ext.form.field.Checkbox Checkbox}es or Checkbox config objects
* to arrange in the group.
*/
- /**
- * @cfg {String/Number/Array} columns Specifies the number of columns to use when displaying grouped
+
+ /**
+ * @cfg {String/Number/Array} 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 {@link #vertical}.
- *
Array : Object
You can also specify an array of column widths, mixing integer
+ * <ul><li><b>'auto'</b> : <p class="sub-desc">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.</p></li>
+ * <li><b>Number</b> : <p class="sub-desc">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 {@link #vertical}.</p></li>
+ * <li><b>Array</b> : <p class="sub-desc">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.
+ * container you should do so.</p></li></ul>
*/
columns : 'auto',
- /**
- * @cfg {Boolean} vertical True to distribute contained controls across columns, completely filling each column
+
+ /**
+ * @cfg {Boolean} 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.
*/
vertical : false,
- /**
- * @cfg {Boolean} allowBlank False to validate that at least one item in the group is checked (defaults to true).
- * If no items are selected at validation time, {@link @blankText} will be used as the error text.
+
+ /**
+ * @cfg {Boolean} allowBlank False to validate that at least one item in the group is checked (defaults to true).
+ * If no items are selected at validation time, {@link #blankText} will be used as the error text.
*/
allowBlank : true,
- /**
- * @cfg {String} blankText Error text to display if the {@link #allowBlank} validation fails (defaults to "You must
- * select at least one item in this group")
+
+ /**
+ * @cfg {String} blankText Error text to display if the {@link #allowBlank} validation fails (defaults to "You must
+ * select at least one item in this group")
*/
- blankText : "You must select at least one item in this group",
+ blankText : "You must select at least one item in this group",
// private
- defaultType : 'checkbox',
+ defaultType : 'checkboxfield',
// private
- groupCls : 'x-form-check-group',
+ groupCls : Ext.baseCSSPrefix + 'form-check-group',
- // private
- initComponent: function(){
- this.addEvents(
- /**
- * @event change
- * Fires when the state of a child checkbox changes.
- * @param {Ext.form.CheckboxGroup} this
- * @param {Array} checked An array containing the checked boxes.
- */
- 'change'
- );
- this.on('change', this.validate, this);
- Ext.form.CheckboxGroup.superclass.initComponent.call(this);
- },
+ /**
+ * @cfg {String} fieldBodyCls
+ * An extra CSS class to be applied to the body content element in addition to {@link #baseBodyCls}.
+ * Defaults to 'x-form-checkboxgroup-body'.
+ */
+ fieldBodyCls: Ext.baseCSSPrefix + 'form-checkboxgroup-body',
// private
- onRender : function(ct, position){
- if(!this.el){
- var panelCfg = {
- autoEl: {
- id: this.id
- },
- cls: this.groupCls,
- layout: 'column',
- renderTo: ct,
- bufferResize: false // Default this to false, since it doesn't really have a proper ownerCt.
- };
- var colCfg = {
- xtype: 'container',
- defaultType: this.defaultType,
- layout: 'form',
- defaults: {
- hideLabel: true,
- anchor: '100%'
- }
- };
-
- if(this.items[0].items){
+ layout: 'checkboxgroup',
- // The container has standard ColumnLayout configs, so pass them in directly
-
- Ext.apply(panelCfg, {
- layoutConfig: {columns: this.items.length},
- defaults: this.defaults,
- items: this.items
- });
- for(var i=0, len=this.items.length; i0 && i%rows==0){
- ri++;
- }
- if(this.items[i].fieldLabel){
- this.items[i].hideLabel = false;
- }
- cols[ri].items.push(this.items[i]);
- };
- }else{
- for(var i=0, len=this.items.length; i /**
+ * @protected
+ * Initializes the field's value based on the initial config. If the {@link #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.
+ */
+ initValue: function() {
+ var me = this,
+ valueCfg = me.value;
+ me.originalValue = me.lastValue = valueCfg || me.getValue();
+ if (valueCfg) {
+ me.setValue(valueCfg);
}
},
- afterRender : function(){
- Ext.form.CheckboxGroup.superclass.afterRender.call(this);
- this.eachItem(function(item){
- item.on('check', this.fireChecked, this);
- item.inGroup = true;
- });
+ /**
+ * @protected
+ * When a checkbox is added to the group, monitor it for changes
+ */
+ onFieldAdded: function(field) {
+ var me = this;
+ if (field.isCheckbox) {
+ me.mon(field, 'change', me.checkChange, me);
+ }
+ me.callParent(arguments);
},
- // private
- doLayout: function(){
- //ugly method required to layout hidden items
- if(this.rendered){
- this.panel.forceLayout = this.ownerCt.forceLayout;
- this.panel.doLayout();
+ onFieldRemoved: function(field) {
+ var me = this;
+ if (field.isCheckbox) {
+ me.mun(field, 'change', me.checkChange, me);
}
+ me.callParent(arguments);
},
- // private
- fireChecked: function(){
- var arr = [];
- this.eachItem(function(item){
- if(item.checked){
- arr.push(item);
- }
- });
- this.fireEvent('change', this, arr);
+ // private override - the group value is a complex object, compare using object serialization
+ isEqual: function(value1, value2) {
+ var toQueryString = Ext.Object.toQueryString;
+ return toQueryString(value1) === toQueryString(value2);
},
-
- /**
- * Runs CheckboxGroup's validations and returns an array of any errors. The only error by default
+
+ /**
+ * 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.
* @return {Array} Array of all validation errors
*/
getErrors: function() {
- var errors = Ext.form.CheckboxGroup.superclass.getErrors.apply(this, arguments);
-
- if (!this.allowBlank) {
- var blank = true;
-
- this.eachItem(function(f){
- if (f.checked) {
- return (blank = false);
- }
- });
-
- if (blank) errors.push(this.blankText);
+ var errors = [];
+ if (!this.allowBlank && Ext.isEmpty(this.getChecked())) {
+ errors.push(this.blankText);
}
-
return errors;
},
- // private
- isDirty: function(){
- //override the behaviour to check sub items.
- if (this.disabled || !this.rendered) {
- return false;
- }
-
- var dirty = false;
-
- this.eachItem(function(item){
- if(item.isDirty()){
- dirty = true;
- return false;
- }
- });
-
- return dirty;
+ /**
+ * @private Returns all checkbox components within the container
+ */
+ getBoxes: function() {
+ return this.query('[isCheckbox]');
},
- // private
- setReadOnly : function(readOnly){
- if(this.rendered){
- this.eachItem(function(item){
- item.setReadOnly(readOnly);
- });
- }
- this.readOnly = readOnly;
+ /**
+ * @private Convenience function which calls the given function for every checkbox in the group
+ * @param {Function} fn The function to call
+ * @param {Object} scope Optional scope object
+ */
+ eachBox: function(fn, scope) {
+ Ext.Array.forEach(this.getBoxes(), fn, scope || this);
},
- // private
- onDisable : function(){
- this.eachItem(function(item){
- item.disable();
+ /**
+ * Returns an Array of all checkboxes in the container which are currently checked
+ * @return {Array} Array of Ext.form.field.Checkbox components
+ */
+ getChecked: function() {
+ return Ext.Array.filter(this.getBoxes(), function(cb) {
+ return cb.getValue();
});
},
- // private
- onEnable : function(){
- this.eachItem(function(item){
- item.enable();
+ // private override
+ isDirty: function(){
+ return Ext.Array.some(this.getBoxes(), function(cb) {
+ return cb.isDirty();
});
},
- // private
- onResize : function(w, h){
- this.panel.setSize(w, h);
- this.panel.doLayout();
+ // private override
+ setReadOnly: function(readOnly) {
+ this.eachBox(function(cb) {
+ cb.setReadOnly(readOnly);
+ });
+ this.readOnly = readOnly;
},
- // inherit docs from Field
- reset : function(){
- if (this.originalValue) {
- // Clear all items
- this.eachItem(function(c){
- if(c.setValue){
- c.setValue(false);
- c.originalValue = c.getValue();
- }
- });
- // Set items stored in originalValue, ugly - set a flag to reset the originalValue
- // during the horrible onSetValue. This will allow trackResetOnLoad to function.
- this.resetOriginal = true;
- this.setValue(this.originalValue);
- delete this.resetOriginal;
- } else {
- this.eachItem(function(c){
- if(c.reset){
- c.reset();
- }
+ /**
+ * Resets the checked state of all {@link Ext.form.field.Checkbox checkboxes} in the group to their
+ * originally loaded values and clears any validation messages.
+ * See {@link Ext.form.Basic}.{@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad}
+ */
+ reset: function() {
+ var me = this,
+ hadError = me.hasActiveError(),
+ preventMark = me.preventMark;
+ me.preventMark = true;
+ me.batchChanges(function() {
+ me.eachBox(function(cb) {
+ cb.reset();
});
+ });
+ me.preventMark = preventMark;
+ me.unsetActiveError();
+ if (hadError) {
+ me.doComponentLayout();
}
- // Defer the clearInvalid so if BaseForm's collection is being iterated it will be called AFTER it is complete.
- // Important because reset is being called on both the group and the individual items.
- (function() {
- this.clearInvalid();
- }).defer(50, this);
},
- /**
- * {@link Ext.form.Checkbox#setValue Set the value(s)} of an item or items
- * in the group. Examples illustrating how this method may be called:
- *
-// call with name and value
-myCheckboxGroup.setValue('cb-col-1', true);
-// call with an array of boolean values
-myCheckboxGroup.setValue([true, false, false]);
-// call with an object literal specifying item:value pairs
-myCheckboxGroup.setValue({
- 'cb-col-2': false,
- 'cb-col-3': true
-});
-// use comma separated string to set items with name to true (checked)
-myCheckboxGroup.setValue('cb-col-1,cb-col-3');
- *
- * See {@link Ext.form.Checkbox#setValue} for additional information.
- * @param {Mixed} id The checkbox to check, or as described by example shown.
- * @param {Boolean} value (optional) The value to set the item.
- * @return {Ext.form.CheckboxGroup} this
- */
- setValue: function(){
- if(this.rendered){
- this.onSetValue.apply(this, arguments);
- }else{
- this.buffered = true;
- this.value = arguments;
- }
- return this;
+ // private override
+ resetOriginalValue: function() {
+ // Defer resetting of originalValue until after all sub-checkboxes have been reset so we get
+ // the correct data from getValue()
+ Ext.defer(function() {
+ this.callParent();
+ }, 1, this);
},
- /**
- * @private
- * Sets the values of one or more of the items within the CheckboxGroup
- * @param {String|Array|Object} id Can take multiple forms. Can be optionally:
- *
- *
An ID string to be used with a second argument
- *
An array of the form ['some', 'list', 'of', 'ids', 'to', 'mark', 'checked']
- *
An array in the form [true, true, false, true, false] etc, where each item relates to the check status of
- * the checkbox at the same index
- *
An object containing ids of the checkboxes as keys and check values as properties
- *
- * @param {String} value The value to set the field to if the first argument was a string
+
+ /**
+ * <p>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:</p>
+ * <ul>
+ * <li>A single Boolean or String value will be passed to the <code>setValue</code> method of the
+ * checkbox with that name. See the rules in {@link Ext.form.field.Checkbox#setValue} for accepted values.</li>
+ * <li>An Array of String values will be matched against the {@link Ext.form.field.Checkbox#inputValue 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.</li>
+ * </ul>
+ * <p>If a checkbox's name is not in the mapping at all, it will be unchecked.</p>
+ * <p>An example:</p>
+ * <pre><code>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']
+});</code></pre>
+ * <p>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.</p>
+ * @param {Object} value The mapping of checkbox names to values.
+ * @return {Ext.form.CheckboxGroup} this
*/
- onSetValue: function(id, value){
- if(arguments.length == 1){
- if(Ext.isArray(id)){
- Ext.each(id, function(val, idx){
- if (Ext.isObject(val) && val.setValue){ // array of checkbox components to be checked
- val.setValue(true);
- if (this.resetOriginal === true) {
- val.originalValue = val.getValue();
- }
- } else { // an array of boolean values
- var item = this.items.itemAt(idx);
- if(item){
- item.setValue(val);
- }
- }
- }, this);
- }else if(Ext.isObject(id)){
- // set of name/value pairs
- for(var i in id){
- var f = this.getBox(i);
- if(f){
- f.setValue(id[i]);
+ setValue: function(value) {
+ var me = this;
+ me.batchChanges(function() {
+ me.eachBox(function(cb) {
+ var name = cb.getName(),
+ cbValue = false;
+ if (value && name in value) {
+ if (Ext.isArray(value[name])) {
+ cbValue = Ext.Array.contains(value[name], cb.inputValue);
+ } else {
+ // single value, let the checkbox's own setValue handle conversion
+ cbValue = value[name];
}
}
- }else{
- this.setValueForItem(id);
- }
- }else{
- var f = this.getBox(id);
- if(f){
- f.setValue(value);
- }
- }
+ cb.setValue(cbValue);
+ });
+ });
+ return me;
},
- // private
- beforeDestroy: function(){
- Ext.destroy(this.panel);
- if (!this.rendered) {
- Ext.destroy(this.items);
- }
- Ext.form.CheckboxGroup.superclass.beforeDestroy.call(this);
-
- },
- setValueForItem : function(val){
- val = String(val).split(',');
- this.eachItem(function(item){
- if(val.indexOf(item.inputValue)> -1){
- item.setValue(true);
+ /**
+ * <p>Returns an object containing the values of all checked checkboxes within the group. Each key-value pair
+ * in the object corresponds to a checkbox {@link Ext.form.field.Checkbox#name name}. If there is only one checked
+ * checkbox with a particular name, the value of that pair will be the String
+ * {@link Ext.form.field.Checkbox#inputValue 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.</p>
+ * <p>The object format returned from this method can also be passed directly to the {@link #setValue} method.</p>
+ * <p>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 {@link #setValue} argument signature. If you need the old
+ * behavior in Ext 4+, use the {@link #getChecked} method instead.</p>
+ */
+ getValue: function() {
+ var values = {};
+ this.eachBox(function(cb) {
+ var name = cb.getName(),
+ inputValue = cb.inputValue,
+ bucket;
+ if (cb.getValue()) {
+ if (name in values) {
+ bucket = values[name];
+ if (!Ext.isArray(bucket)) {
+ bucket = values[name] = [bucket];
+ }
+ bucket.push(inputValue);
+ } else {
+ values[name] = inputValue;
+ }
}
});
+ return values;
},
- // private
- getBox : function(id){
- var box = null;
- this.eachItem(function(f){
- if(id == f || f.dataIndex == id || f.id == id || f.getName() == id){
- box = f;
- return false;
- }
- });
- return box;
+ /*
+ * Don't return any data for submit; the form will get the info from the individual checkboxes themselves.
+ */
+ getSubmitData: function() {
+ return null;
},
- /**
- * Gets an array of the selected {@link Ext.form.Checkbox} in the group.
- * @return {Array} An array of the selected checkboxes.
+ /*
+ * Don't return any data for the model; the form will get the info from the individual checkboxes themselves.
*/
- getValue : function(){
- var out = [];
- this.eachItem(function(item){
- if(item.checked){
- out.push(item);
- }
- });
- return out;
+ getModelData: function() {
+ return null;
},
- /**
- * @private
- * Convenience function which passes the given function to every item in the composite
- * @param {Function} fn The function to call
- * @param {Object} scope Optional scope object
- */
- eachItem: function(fn, scope) {
- if(this.items && this.items.each){
- this.items.each(fn, scope || this);
+ validate: function() {
+ var me = this,
+ errors = me.getErrors(),
+ isValid = Ext.isEmpty(errors),
+ wasValid = !me.hasActiveError();
+
+ if (isValid) {
+ me.unsetActiveError();
+ } else {
+ me.setActiveError(errors);
+ }
+ if (isValid !== wasValid) {
+ me.fireEvent('validitychange', me, isValid);
+ me.doComponentLayout();
}
- },
- /**
- * @cfg {String} name
- * @hide
- */
+ return isValid;
+ }
- /**
- * @method getRawValue
- * @hide
- */
- getRawValue : Ext.emptyFn,
+}, function() {
- /**
- * @method setRawValue
- * @hide
- */
- setRawValue : Ext.emptyFn
+ this.borrow(Ext.form.field.Base, ['markInvalid', 'clearInvalid']);
});
-Ext.reg('checkboxgroup', Ext.form.CheckboxGroup);
-
-
-
\ No newline at end of file
+
\ No newline at end of file