docs/source/CheckboxGroup.html

   1 <html>\r
   2 <head>\r
   3   <title>The source code</title>\r
   4     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
   5     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
   6 </head>\r
   7 <body  onload="prettyPrint();">\r
   8     <pre class="prettyprint lang-js"><div id="cls-Ext.form.CheckboxGroup"></div>/**
   9  * @class Ext.form.CheckboxGroup
  10  * @extends Ext.form.Field
  11  * <p>A grouping container for {@link Ext.form.Checkbox} controls.</p>
  12  * <p>Sample usage:</p>
  13  * <pre><code>
  14 var myCheckboxGroup = new Ext.form.CheckboxGroup({
  15     id:'myGroup',
  16     xtype: 'checkboxgroup',
  17     fieldLabel: 'Single Column',
  18     itemCls: 'x-check-group-alt',
  19     // Put all controls in a single column with width 100%
  20     columns: 1,
  21     items: [
  22         {boxLabel: 'Item 1', name: 'cb-col-1'},
  23         {boxLabel: 'Item 2', name: 'cb-col-2', checked: true},
  24         {boxLabel: 'Item 3', name: 'cb-col-3'}
  25     ]
  26 });
  27  * </code></pre>
  28  * @constructor
  29  * Creates a new CheckboxGroup
  30  * @param {Object} config Configuration options
  31  * @xtype checkboxgroup
  32  */
  33 Ext.form.CheckboxGroup = Ext.extend(Ext.form.Field, {
  34     <div id="cfg-Ext.form.CheckboxGroup-items"></div>/**
  35      * @cfg {Array} items An Array of {@link Ext.form.Checkbox Checkbox}es or Checkbox config objects
  36      * to arrange in the group.
  37      */
  38     <div id="cfg-Ext.form.CheckboxGroup-columns"></div>/**
  39      * @cfg {String/Number/Array} columns Specifies the number of columns to use when displaying grouped
  40      * checkbox/radio controls using automatic layout.  This config can take several types of values:
  41      * <ul><li><b>'auto'</b> : <p class="sub-desc">The controls will be rendered one per column on one row and the width
  42      * of each column will be evenly distributed based on the width of the overall field container. This is the default.</p></li>
  43      * <li><b>Number</b> : <p class="sub-desc">If you specific a number (e.g., 3) that number of columns will be
  44      * created and the contained controls will be automatically distributed based on the value of {@link #vertical}.</p></li>
  45      * <li><b>Array</b> : Object<p class="sub-desc">You can also specify an array of column widths, mixing integer
  46      * (fixed width) and float (percentage width) values as needed (e.g., [100, .25, .75]). Any integer values will
  47      * be rendered first, then any float values will be calculated as a percentage of the remaining space. Float
  48      * values do not have to add up to 1 (100%) although if you want the controls to take up the entire field
  49      * container you should do so.</p></li></ul>
  50      */
  51     columns : 'auto',
  52     <div id="cfg-Ext.form.CheckboxGroup-vertical"></div>/**
  53      * @cfg {Boolean} vertical True to distribute contained controls across columns, completely filling each column
  54      * top to bottom before starting on the next column.  The number of controls in each column will be automatically
  55      * calculated to keep columns as even as possible.  The default value is false, so that controls will be added
  56      * to columns one at a time, completely filling each row left to right before starting on the next row.
  57      */
  58     vertical : false,
  59     <div id="cfg-Ext.form.CheckboxGroup-allowBlank"></div>/**
  60      * @cfg {Boolean} allowBlank False to validate that at least one item in the group is checked (defaults to true).
  61      * If no items are selected at validation time, {@link @blankText} will be used as the error text.
  62      */
  63     allowBlank : true,
  64     <div id="cfg-Ext.form.CheckboxGroup-blankText"></div>/**
  65      * @cfg {String} blankText Error text to display if the {@link #allowBlank} validation fails (defaults to "You must
  66      * select at least one item in this group")
  67      */
  68     blankText : "You must select at least one item in this group",
  69
  70     // private
  71     defaultType : 'checkbox',
  72
  73     // private
  74     groupCls : 'x-form-check-group',
  75
  76     // private
  77     initComponent: function(){
  78         this.addEvents(
  79             <div id="event-Ext.form.CheckboxGroup-change"></div>/**
  80              * @event change
  81              * Fires when the state of a child checkbox changes.
  82              * @param {Ext.form.CheckboxGroup} this
  83              * @param {Array} checked An array containing the checked boxes.
  84              */
  85             'change'
  86         );
  87         Ext.form.CheckboxGroup.superclass.initComponent.call(this);
  88     },
  89
  90     // private
  91     onRender : function(ct, position){
  92         if(!this.el){
  93             var panelCfg = {
  94                 cls: this.groupCls,
  95                 layout: 'column',
  96                 border: false,
  97                 renderTo: ct
  98             };
  99             var colCfg = {
 100                 defaultType: this.defaultType,
 101                 layout: 'form',
 102                 border: false,
 103                 defaults: {
 104                     hideLabel: true,
 105                     anchor: '100%'
 106                 }
 107             };
 108
 109             if(this.items[0].items){
 110
 111                 // The container has standard ColumnLayout configs, so pass them in directly
 112
 113                 Ext.apply(panelCfg, {
 114                     layoutConfig: {columns: this.items.length},
 115                     defaults: this.defaults,
 116                     items: this.items
 117                 });
 118                 for(var i=0, len=this.items.length; i<len; i++){
 119                     Ext.applyIf(this.items[i], colCfg);
 120                 }
 121
 122             }else{
 123
 124                 // The container has field item configs, so we have to generate the column
 125                 // panels first then move the items into the columns as needed.
 126
 127                 var numCols, cols = [];
 128
 129                 if(typeof this.columns == 'string'){ // 'auto' so create a col per item
 130                     this.columns = this.items.length;
 131                 }
 132                 if(!Ext.isArray(this.columns)){
 133                     var cs = [];
 134                     for(var i=0; i<this.columns; i++){
 135                         cs.push((100/this.columns)*.01); // distribute by even %
 136                     }
 137                     this.columns = cs;
 138                 }
 139
 140                 numCols = this.columns.length;
 141
 142                 // Generate the column configs with the correct width setting
 143                 for(var i=0; i<numCols; i++){
 144                     var cc = Ext.apply({items:[]}, colCfg);
 145                     cc[this.columns[i] <= 1 ? 'columnWidth' : 'width'] = this.columns[i];
 146                     if(this.defaults){
 147                         cc.defaults = Ext.apply(cc.defaults || {}, this.defaults)
 148                     }
 149                     cols.push(cc);
 150                 };
 151
 152                 // Distribute the original items into the columns
 153                 if(this.vertical){
 154                     var rows = Math.ceil(this.items.length / numCols), ri = 0;
 155                     for(var i=0, len=this.items.length; i<len; i++){
 156                         if(i>0 && i%rows==0){
 157                             ri++;
 158                         }
 159                         if(this.items[i].fieldLabel){
 160                             this.items[i].hideLabel = false;
 161                         }
 162                         cols[ri].items.push(this.items[i]);
 163                     };
 164                 }else{
 165                     for(var i=0, len=this.items.length; i<len; i++){
 166                         var ci = i % numCols;
 167                         if(this.items[i].fieldLabel){
 168                             this.items[i].hideLabel = false;
 169                         }
 170                         cols[ci].items.push(this.items[i]);
 171                     };
 172                 }
 173
 174                 Ext.apply(panelCfg, {
 175                     layoutConfig: {columns: numCols},
 176                     items: cols
 177                 });
 178             }
 179
 180             this.panel = new Ext.Panel(panelCfg);
 181             this.panel.ownerCt = this;
 182             this.el = this.panel.getEl();
 183
 184             if(this.forId && this.itemCls){
 185                 var l = this.el.up(this.itemCls).child('label', true);
 186                 if(l){
 187                     l.setAttribute('htmlFor', this.forId);
 188                 }
 189             }
 190
 191             var fields = this.panel.findBy(function(c){
 192                 return c.isFormField;
 193             }, this);
 194
 195             this.items = new Ext.util.MixedCollection();
 196             this.items.addAll(fields);
 197         }
 198         Ext.form.CheckboxGroup.superclass.onRender.call(this, ct, position);
 199     },
 200
 201     afterRender : function(){
 202         Ext.form.CheckboxGroup.superclass.afterRender.call(this);
 203         if(this.values){
 204             this.setValue.apply(this, this.values);
 205             delete this.values;
 206         }
 207         this.eachItem(function(item){
 208             item.on('check', this.fireChecked, this);
 209             item.inGroup = true;
 210         });
 211     },
 212
 213     // private
 214     doLayout: function(){
 215         //ugly method required to layout hidden items
 216         if(this.rendered){
 217             this.panel.forceLayout = this.ownerCt.forceLayout;
 218             this.panel.doLayout();
 219         }
 220     },
 221
 222     // private
 223     fireChecked: function(){
 224         var arr = [];
 225         this.eachItem(function(item){
 226             if(item.checked){
 227                 arr.push(item);
 228             }
 229         });
 230         this.fireEvent('change', this, arr);
 231     },
 232
 233     // private
 234     validateValue : function(value){
 235         if(!this.allowBlank){
 236             var blank = true;
 237             this.eachItem(function(f){
 238                 if(f.checked){
 239                     return (blank = false);
 240                 }
 241             });
 242             if(blank){
 243                 this.markInvalid(this.blankText);
 244                 return false;
 245             }
 246         }
 247         return true;
 248     },
 249
 250     // private
 251     onDisable : function(){
 252         this.eachItem(function(item){
 253             item.disable();
 254         });
 255     },
 256
 257     // private
 258     onEnable : function(){
 259         this.eachItem(function(item){
 260             item.enable();
 261         });
 262     },
 263
 264     // private
 265     doLayout: function(){
 266         if(this.rendered){
 267             this.panel.forceLayout = this.ownerCt.forceLayout;
 268             this.panel.doLayout();
 269         }
 270     },
 271
 272     // private
 273     onResize : function(w, h){
 274         this.panel.setSize(w, h);
 275         this.panel.doLayout();
 276     },
 277
 278     // inherit docs from Field
 279     reset : function(){
 280         Ext.form.CheckboxGroup.superclass.reset.call(this);
 281         this.eachItem(function(c){
 282             if(c.reset){
 283                 c.reset();
 284             }
 285         });
 286     },
 287
 288     <div id="method-Ext.form.CheckboxGroup-setValue"></div>/**
 289      * {@link Ext.form.Checkbox#setValue Set the value(s)} of an item or items
 290      * in the group. Examples illustrating how this method may be called:
 291      * <pre><code>
 292 // call with name and value
 293 myCheckboxGroup.setValue('cb-col-1', true);
 294 // call with an array of boolean values
 295 myCheckboxGroup.setValue([true, false, false]);
 296 // call with an object literal specifying item:value pairs
 297 myCheckboxGroup.setValue({
 298     'cb-col-2': false,
 299     'cb-col-3': true
 300 });
 301 // use comma separated string to set items with name to true (checked)
 302 myCheckboxGroup.setValue('cb-col-1,cb-col-3');
 303      * </code></pre>
 304      * See {@link Ext.form.Checkbox#setValue} for additional information.
 305      * @param {Mixed} id The checkbox to check, or as described by example shown.
 306      * @param {Boolean} value (optional) The value to set the item.
 307      * @return {Ext.form.CheckboxGroup} this
 308      */
 309     setValue : function(id, value){
 310         if(this.rendered){
 311             if(arguments.length == 1){
 312                 if(Ext.isArray(id)){
 313                     //an array of boolean values
 314                     Ext.each(id, function(val, idx){
 315                         var item = this.items.itemAt(idx);
 316                         if(item){
 317                             item.setValue(val);
 318                         }
 319                     }, this);
 320                 }else if(Ext.isObject(id)){
 321                     //set of name/value pairs
 322                     for(var i in id){
 323                         var f = this.getBox(i);
 324                         if(f){
 325                             f.setValue(id[i]);
 326                         }
 327                     }
 328                 }else{
 329                     this.setValueForItem(id);
 330                 }
 331             }else{
 332                 var f = this.getBox(id);
 333                 if(f){
 334                     f.setValue(value);
 335                 }
 336             }
 337         }else{
 338             this.values = arguments;
 339         }
 340         return this;
 341     },
 342
 343     // private
 344     onDestroy: function(){
 345         Ext.destroy(this.panel);
 346         Ext.form.CheckboxGroup.superclass.onDestroy.call(this);
 347
 348     },
 349
 350     setValueForItem : function(val){
 351         val = String(val).split(',');
 352         this.eachItem(function(item){
 353             if(val.indexOf(item.inputValue)> -1){
 354                 item.setValue(true);
 355             }
 356         });
 357     },
 358
 359     // private
 360     getBox : function(id){
 361         var box = null;
 362         this.eachItem(function(f){
 363             if(id == f || f.dataIndex == id || f.id == id || f.getName() == id){
 364                 box = f;
 365                 return false;
 366             }
 367         });
 368         return box;
 369     },
 370
 371     /**
 372      * Gets an array of the selected {@link Ext.form.Checkbox} in the group.
 373      * @return {Array} An array of the selected checkboxes.
 374      */
 375     getValue : function(){
 376         var out = [];
 377         this.eachItem(function(item){
 378             if(item.checked){
 379                 out.push(item);
 380             }
 381         });
 382         return out;
 383     },
 384
 385     // private
 386     eachItem: function(fn){
 387         if(this.items && this.items.each){
 388             this.items.each(fn, this);
 389         }
 390     },
 391
 392     <div id="cfg-Ext.form.CheckboxGroup-name"></div>/**
 393      * @cfg {String} name
 394      * @hide
 395      */
 396     <div id="method-Ext.form.CheckboxGroup-initValue"></div>/**
 397      * @method initValue
 398      * @hide
 399      */
 400     initValue : Ext.emptyFn,
 401     <div id="method-Ext.form.CheckboxGroup-getValue"></div>/**
 402      * @method getValue
 403      * @hide
 404      */
 405     getValue : Ext.emptyFn,
 406     <div id="method-Ext.form.CheckboxGroup-getRawValue"></div>/**
 407      * @method getRawValue
 408      * @hide
 409      */
 410     getRawValue : Ext.emptyFn,
 411
 412     <div id="method-Ext.form.CheckboxGroup-setRawValue"></div>/**
 413      * @method setRawValue
 414      * @hide
 415      */
 416     setRawValue : Ext.emptyFn
 417
 418 });
 419
 420 Ext.reg('checkboxgroup', Ext.form.CheckboxGroup);
 421 </pre>    \r
 422 </body>\r
 423 </html>