docs/source/CheckboxGroup.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-form-CheckboxGroup'>/**
  19 </span> * A {@link Ext.form.FieldContainer field container} which has a specialized layout for arranging
  20  * {@link Ext.form.field.Checkbox} controls into columns, and provides convenience {@link Ext.form.field.Field} methods
  21  * for {@link #getValue getting}, {@link #setValue setting}, and {@link #validate validating} the group
  22  * of checkboxes as a whole.
  23  *
  24  * # Validation
  25  *
  26  * Individual checkbox fields themselves have no default validation behavior, but
  27  * sometimes you want to require a user to select at least one of a group of checkboxes. CheckboxGroup
  28  * allows this by setting the config `{@link #allowBlank}:false`; when the user does not check at
  29  * least one of the checkboxes, the entire group will be highlighted as invalid and the
  30  * {@link #blankText error message} will be displayed according to the {@link #msgTarget} config.
  31  *
  32  * # Layout
  33  *
  34  * The default layout for CheckboxGroup makes it easy to arrange the checkboxes into
  35  * columns; see the {@link #columns} and {@link #vertical} config documentation for details. You may also
  36  * use a completely different layout by setting the {@link #layout} to one of the other supported layout
  37  * types; for instance you may wish to use a custom arrangement of hbox and vbox containers. In that case
  38  * the checkbox components at any depth will still be managed by the CheckboxGroup's validation.
  39  *
  40  * {@img Ext.form.CheckboxGroup/Ext.form.CheckboxGroup.png Ext.form.CheckboxGroup component}
  41  *
  42  * # Example usage
  43  *
  44  *     Ext.create('Ext.form.Panel', {
  45  *         title: 'Checkbox Group',
  46  *         width: 300,
  47  *         height: 125,
  48  *         bodyPadding: 10,
  49  *         renderTo: Ext.getBody(),
  50  *         items:[{
  51  *             xtype: 'checkboxgroup',
  52  *             fieldLabel: 'Two Columns',
  53  *             // Arrange radio buttons into two columns, distributed vertically
  54  *             columns: 2,
  55  *             vertical: true,
  56  *             items: [
  57  *                 {boxLabel: 'Item 1', name: 'rb', inputValue: '1'},
  58  *                 {boxLabel: 'Item 2', name: 'rb', inputValue: '2', checked: true},
  59  *                 {boxLabel: 'Item 3', name: 'rb', inputValue: '3'},
  60  *                 {boxLabel: 'Item 4', name: 'rb', inputValue: '4'},
  61  *                 {boxLabel: 'Item 5', name: 'rb', inputValue: '5'},
  62  *                 {boxLabel: 'Item 6', name: 'rb', inputValue: '6'}
  63  *             ]
  64  *         }]
  65  *     });
  66  *
  67  */
  68 Ext.define('Ext.form.CheckboxGroup', {
  69     extend:'Ext.form.FieldContainer',
  70     mixins: {
  71         field: 'Ext.form.field.Field'
  72     },
  73     alias: 'widget.checkboxgroup',
  74     requires: ['Ext.layout.container.CheckboxGroup', 'Ext.form.field.Base'],
  75
  76 <span id='Ext-form-CheckboxGroup-cfg-name'>    /**
  77 </span>     * @cfg {String} name
  78      * @hide
  79      */
  80
  81 <span id='Ext-form-CheckboxGroup-cfg-items'>    /**
  82 </span>     * @cfg {Array} items An Array of {@link Ext.form.field.Checkbox Checkbox}es or Checkbox config objects
  83      * to arrange in the group.
  84      */
  85
  86 <span id='Ext-form-CheckboxGroup-cfg-columns'>    /**
  87 </span>     * @cfg {String/Number/Array} columns Specifies the number of columns to use when displaying grouped
  88      * checkbox/radio controls using automatic layout.  This config can take several types of values:
  89      * &lt;ul&gt;&lt;li&gt;&lt;b&gt;'auto'&lt;/b&gt; : &lt;p class=&quot;sub-desc&quot;&gt;The controls will be rendered one per column on one row and the width
  90      * of each column will be evenly distributed based on the width of the overall field container. This is the default.&lt;/p&gt;&lt;/li&gt;
  91      * &lt;li&gt;&lt;b&gt;Number&lt;/b&gt; : &lt;p class=&quot;sub-desc&quot;&gt;If you specific a number (e.g., 3) that number of columns will be
  92      * created and the contained controls will be automatically distributed based on the value of {@link #vertical}.&lt;/p&gt;&lt;/li&gt;
  93      * &lt;li&gt;&lt;b&gt;Array&lt;/b&gt; : &lt;p class=&quot;sub-desc&quot;&gt;You can also specify an array of column widths, mixing integer
  94      * (fixed width) and float (percentage width) values as needed (e.g., [100, .25, .75]). Any integer values will
  95      * be rendered first, then any float values will be calculated as a percentage of the remaining space. Float
  96      * values do not have to add up to 1 (100%) although if you want the controls to take up the entire field
  97      * container you should do so.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;
  98      */
  99     columns : 'auto',
 100
 101 <span id='Ext-form-CheckboxGroup-cfg-vertical'>    /**
 102 </span>     * @cfg {Boolean} vertical True to distribute contained controls across columns, completely filling each column
 103      * top to bottom before starting on the next column.  The number of controls in each column will be automatically
 104      * calculated to keep columns as even as possible.  The default value is false, so that controls will be added
 105      * to columns one at a time, completely filling each row left to right before starting on the next row.
 106      */
 107     vertical : false,
 108
 109 <span id='Ext-form-CheckboxGroup-cfg-allowBlank'>    /**
 110 </span>     * @cfg {Boolean} allowBlank False to validate that at least one item in the group is checked (defaults to true).
 111      * If no items are selected at validation time, {@link #blankText} will be used as the error text.
 112      */
 113     allowBlank : true,
 114
 115 <span id='Ext-form-CheckboxGroup-cfg-blankText'>    /**
 116 </span>     * @cfg {String} blankText Error text to display if the {@link #allowBlank} validation fails (defaults to &quot;You must
 117      * select at least one item in this group&quot;)
 118      */
 119     blankText : &quot;You must select at least one item in this group&quot;,
 120
 121     // private
 122     defaultType : 'checkboxfield',
 123
 124     // private
 125     groupCls : Ext.baseCSSPrefix + 'form-check-group',
 126
 127 <span id='Ext-form-CheckboxGroup-cfg-fieldBodyCls'>    /**
 128 </span>     * @cfg {String} fieldBodyCls
 129      * An extra CSS class to be applied to the body content element in addition to {@link #baseBodyCls}.
 130      * Defaults to 'x-form-checkboxgroup-body'.
 131      */
 132     fieldBodyCls: Ext.baseCSSPrefix + 'form-checkboxgroup-body',
 133
 134     // private
 135     layout: 'checkboxgroup',
 136
 137     initComponent: function() {
 138         var me = this;
 139         me.callParent();
 140         me.initField();
 141     },
 142
 143 <span id='Ext-form-CheckboxGroup-method-initValue'>    /**
 144 </span>     * @protected
 145      * Initializes the field's value based on the initial config. If the {@link #value} config is specified
 146      * then we use that to set the value; otherwise we initialize the originalValue by querying the values of
 147      * all sub-checkboxes after they have been initialized.
 148      */
 149     initValue: function() {
 150         var me = this,
 151             valueCfg = me.value;
 152         me.originalValue = me.lastValue = valueCfg || me.getValue();
 153         if (valueCfg) {
 154             me.setValue(valueCfg);
 155         }
 156     },
 157
 158 <span id='Ext-form-CheckboxGroup-method-onFieldAdded'>    /**
 159 </span>     * @protected
 160      * When a checkbox is added to the group, monitor it for changes
 161      */
 162     onFieldAdded: function(field) {
 163         var me = this;
 164         if (field.isCheckbox) {
 165             me.mon(field, 'change', me.checkChange, me);
 166         }
 167         me.callParent(arguments);
 168     },
 169
 170     onFieldRemoved: function(field) {
 171         var me = this;
 172         if (field.isCheckbox) {
 173             me.mun(field, 'change', me.checkChange, me);
 174         }
 175         me.callParent(arguments);
 176     },
 177
 178     // private override - the group value is a complex object, compare using object serialization
 179     isEqual: function(value1, value2) {
 180         var toQueryString = Ext.Object.toQueryString;
 181         return toQueryString(value1) === toQueryString(value2);
 182     },
 183
 184 <span id='Ext-form-CheckboxGroup-method-getErrors'>    /**
 185 </span>     * Runs CheckboxGroup's validations and returns an array of any errors. The only error by default
 186      * is if allowBlank is set to true and no items are checked.
 187      * @return {Array} Array of all validation errors
 188      */
 189     getErrors: function() {
 190         var errors = [];
 191         if (!this.allowBlank &amp;&amp; Ext.isEmpty(this.getChecked())) {
 192             errors.push(this.blankText);
 193         }
 194         return errors;
 195     },
 196
 197 <span id='Ext-form-CheckboxGroup-method-getBoxes'>    /**
 198 </span>     * @private Returns all checkbox components within the container
 199      */
 200     getBoxes: function() {
 201         return this.query('[isCheckbox]');
 202     },
 203
 204 <span id='Ext-form-CheckboxGroup-method-eachBox'>    /**
 205 </span>     * @private Convenience function which calls the given function for every checkbox in the group
 206      * @param {Function} fn The function to call
 207      * @param {Object} scope Optional scope object
 208      */
 209     eachBox: function(fn, scope) {
 210         Ext.Array.forEach(this.getBoxes(), fn, scope || this);
 211     },
 212
 213 <span id='Ext-form-CheckboxGroup-method-getChecked'>    /**
 214 </span>     * Returns an Array of all checkboxes in the container which are currently checked
 215      * @return {Array} Array of Ext.form.field.Checkbox components
 216      */
 217     getChecked: function() {
 218         return Ext.Array.filter(this.getBoxes(), function(cb) {
 219             return cb.getValue();
 220         });
 221     },
 222
 223     // private override
 224     isDirty: function(){
 225         return Ext.Array.some(this.getBoxes(), function(cb) {
 226             return cb.isDirty();
 227         });
 228     },
 229
 230     // private override
 231     setReadOnly: function(readOnly) {
 232         this.eachBox(function(cb) {
 233             cb.setReadOnly(readOnly);
 234         });
 235         this.readOnly = readOnly;
 236     },
 237
 238 <span id='Ext-form-CheckboxGroup-method-reset'>    /**
 239 </span>     * Resets the checked state of all {@link Ext.form.field.Checkbox checkboxes} in the group to their
 240      * originally loaded values and clears any validation messages.
 241      * See {@link Ext.form.Basic}.{@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad}
 242      */
 243     reset: function() {
 244         var me = this,
 245             hadError = me.hasActiveError(),
 246             preventMark = me.preventMark;
 247         me.preventMark = true;
 248         me.batchChanges(function() {
 249             me.eachBox(function(cb) {
 250                 cb.reset();
 251             });
 252         });
 253         me.preventMark = preventMark;
 254         me.unsetActiveError();
 255         if (hadError) {
 256             me.doComponentLayout();
 257         }
 258     },
 259
 260     // private override
 261     resetOriginalValue: function() {
 262         // Defer resetting of originalValue until after all sub-checkboxes have been reset so we get
 263         // the correct data from getValue()
 264         Ext.defer(function() {
 265             this.callParent();
 266         }, 1, this);
 267     },
 268
 269
 270 <span id='Ext-form-CheckboxGroup-method-setValue'>    /**
 271 </span>     * &lt;p&gt;Sets the value(s) of all checkboxes in the group. The expected format is an Object of
 272      * name-value pairs corresponding to the names of the checkboxes in the group. Each pair can
 273      * have either a single or multiple values:&lt;/p&gt;
 274      * &lt;ul&gt;
 275      *   &lt;li&gt;A single Boolean or String value will be passed to the &lt;code&gt;setValue&lt;/code&gt; method of the
 276      *   checkbox with that name. See the rules in {@link Ext.form.field.Checkbox#setValue} for accepted values.&lt;/li&gt;
 277      *   &lt;li&gt;An Array of String values will be matched against the {@link Ext.form.field.Checkbox#inputValue inputValue}
 278      *   of checkboxes in the group with that name; those checkboxes whose inputValue exists in the array will be
 279      *   checked and others will be unchecked.&lt;/li&gt;
 280      * &lt;/ul&gt;
 281      * &lt;p&gt;If a checkbox's name is not in the mapping at all, it will be unchecked.&lt;/p&gt;
 282      * &lt;p&gt;An example:&lt;/p&gt;
 283      * &lt;pre&gt;&lt;code&gt;var myCheckboxGroup = new Ext.form.CheckboxGroup({
 284     columns: 3,
 285     items: [{
 286         name: 'cb1',
 287         boxLabel: 'Single 1'
 288     }, {
 289         name: 'cb2',
 290         boxLabel: 'Single 2'
 291     }, {
 292         name: 'cb3',
 293         boxLabel: 'Single 3'
 294     }, {
 295         name: 'cbGroup',
 296         boxLabel: 'Grouped 1'
 297         inputValue: 'value1'
 298     }, {
 299         name: 'cbGroup',
 300         boxLabel: 'Grouped 2'
 301         inputValue: 'value2'
 302     }, {
 303         name: 'cbGroup',
 304         boxLabel: 'Grouped 3'
 305         inputValue: 'value3'
 306     }]
 307 });
 308
 309 myCheckboxGroup.setValue({
 310     cb1: true,
 311     cb3: false,
 312     cbGroup: ['value1', 'value3']
 313 });&lt;/code&gt;&lt;/pre&gt;
 314      * &lt;p&gt;The above code will cause the checkbox named 'cb1' to be checked, as well as the first and third
 315      * checkboxes named 'cbGroup'. The other three checkboxes will be unchecked.&lt;/p&gt;
 316      * @param {Object} value The mapping of checkbox names to values.
 317      * @return {Ext.form.CheckboxGroup} this
 318      */
 319     setValue: function(value) {
 320         var me = this;
 321         me.batchChanges(function() {
 322             me.eachBox(function(cb) {
 323                 var name = cb.getName(),
 324                     cbValue = false;
 325                 if (value &amp;&amp; name in value) {
 326                     if (Ext.isArray(value[name])) {
 327                         cbValue = Ext.Array.contains(value[name], cb.inputValue);
 328                     } else {
 329                         // single value, let the checkbox's own setValue handle conversion
 330                         cbValue = value[name];
 331                     }
 332                 }
 333                 cb.setValue(cbValue);
 334             });
 335         });
 336         return me;
 337     },
 338
 339
 340 <span id='Ext-form-CheckboxGroup-method-getValue'>    /**
 341 </span>     * &lt;p&gt;Returns an object containing the values of all checked checkboxes within the group. Each key-value pair
 342      * in the object corresponds to a checkbox {@link Ext.form.field.Checkbox#name name}. If there is only one checked
 343      * checkbox with a particular name, the value of that pair will be the String
 344      * {@link Ext.form.field.Checkbox#inputValue inputValue} of that checkbox. If there are multiple checked checkboxes
 345      * with that name, the value of that pair will be an Array of the selected inputValues.&lt;/p&gt;
 346      * &lt;p&gt;The object format returned from this method can also be passed directly to the {@link #setValue} method.&lt;/p&gt;
 347      * &lt;p&gt;NOTE: In Ext 3, this method returned an array of Checkbox components; this was changed to make it more
 348      * consistent with other field components and with the {@link #setValue} argument signature. If you need the old
 349      * behavior in Ext 4+, use the {@link #getChecked} method instead.&lt;/p&gt;
 350      */
 351     getValue: function() {
 352         var values = {};
 353         this.eachBox(function(cb) {
 354             var name = cb.getName(),
 355                 inputValue = cb.inputValue,
 356                 bucket;
 357             if (cb.getValue()) {
 358                 if (name in values) {
 359                     bucket = values[name];
 360                     if (!Ext.isArray(bucket)) {
 361                         bucket = values[name] = [bucket];
 362                     }
 363                     bucket.push(inputValue);
 364                 } else {
 365                     values[name] = inputValue;
 366                 }
 367             }
 368         });
 369         return values;
 370     },
 371
 372     /*
 373      * Don't return any data for submit; the form will get the info from the individual checkboxes themselves.
 374      */
 375     getSubmitData: function() {
 376         return null;
 377     },
 378
 379     /*
 380      * Don't return any data for the model; the form will get the info from the individual checkboxes themselves.
 381      */
 382     getModelData: function() {
 383         return null;
 384     },
 385
 386     validate: function() {
 387         var me = this,
 388             errors = me.getErrors(),
 389             isValid = Ext.isEmpty(errors),
 390             wasValid = !me.hasActiveError();
 391
 392         if (isValid) {
 393             me.unsetActiveError();
 394         } else {
 395             me.setActiveError(errors);
 396         }
 397         if (isValid !== wasValid) {
 398             me.fireEvent('validitychange', me, isValid);
 399             me.doComponentLayout();
 400         }
 401
 402         return isValid;
 403     }
 404
 405 }, function() {
 406
 407     this.borrow(Ext.form.field.Base, ['markInvalid', 'clearInvalid']);
 408
 409 });
 410
 411 </pre>
 412 </body>
 413 </html>