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