src/form/RadioGroup.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * A {@link Ext.form.FieldContainer field container} which has a specialized layout for arranging
  17  * {@link Ext.form.field.Radio} controls into columns, and provides convenience {@link Ext.form.field.Field}
  18  * methods for {@link #getValue getting}, {@link #setValue setting}, and {@link #validate validating} the
  19  * group of radio buttons as a whole.
  20  *
  21  * # Validation
  22  *
  23  * Individual radio buttons themselves have no default validation behavior, but
  24  * sometimes you want to require a user to select one of a group of radios. RadioGroup
  25  * allows this by setting the config `{@link #allowBlank}:false`; when the user does not check at
  26  * one of the radio buttons, the entire group will be highlighted as invalid and the
  27  * {@link #blankText error message} will be displayed according to the {@link #msgTarget} config.</p>
  28  *
  29  * # Layout
  30  *
  31  * The default layout for RadioGroup makes it easy to arrange the radio buttons into
  32  * columns; see the {@link #columns} and {@link #vertical} config documentation for details. You may also
  33  * use a completely different layout by setting the {@link #layout} to one of the other supported layout
  34  * types; for instance you may wish to use a custom arrangement of hbox and vbox containers. In that case
  35  * the Radio components at any depth will still be managed by the RadioGroup's validation.
  36  *
  37  * # Example usage
  38  *
  39  *     @example
  40  *     Ext.create('Ext.form.Panel', {
  41  *         title: 'RadioGroup Example',
  42  *         width: 300,
  43  *         height: 125,
  44  *         bodyPadding: 10,
  45  *         renderTo: Ext.getBody(),
  46  *         items:[{
  47  *             xtype: 'radiogroup',
  48  *             fieldLabel: 'Two Columns',
  49  *             // Arrange radio buttons into two columns, distributed vertically
  50  *             columns: 2,
  51  *             vertical: true,
  52  *             items: [
  53  *                 { boxLabel: 'Item 1', name: 'rb', inputValue: '1' },
  54  *                 { boxLabel: 'Item 2', name: 'rb', inputValue: '2', checked: true},
  55  *                 { boxLabel: 'Item 3', name: 'rb', inputValue: '3' },
  56  *                 { boxLabel: 'Item 4', name: 'rb', inputValue: '4' },
  57  *                 { boxLabel: 'Item 5', name: 'rb', inputValue: '5' },
  58  *                 { boxLabel: 'Item 6', name: 'rb', inputValue: '6' }
  59  *             ]
  60  *         }]
  61  *     });
  62  *
  63  */
  64 Ext.define('Ext.form.RadioGroup', {
  65     extend: 'Ext.form.CheckboxGroup',
  66     alias: 'widget.radiogroup',
  67
  68     /**
  69      * @cfg {Ext.form.field.Radio[]/Object[]} items
  70      * An Array of {@link Ext.form.field.Radio Radio}s or Radio config objects to arrange in the group.
  71      */
  72     /**
  73      * @cfg {Boolean} allowBlank True to allow every item in the group to be blank.
  74      * If allowBlank = false and no items are selected at validation time, {@link #blankText} will
  75      * be used as the error text.
  76      */
  77     allowBlank : true,
  78     /**
  79      * @cfg {String} blankText Error text to display if the {@link #allowBlank} validation fails
  80      */
  81     blankText : 'You must select one item in this group',
  82
  83     // private
  84     defaultType : 'radiofield',
  85
  86     // private
  87     groupCls : Ext.baseCSSPrefix + 'form-radio-group',
  88
  89     getBoxes: function() {
  90         return this.query('[isRadio]');
  91     },
  92
  93     /**
  94      * Sets the value of the radio group. The radio with corresponding name and value will be set.
  95      * This method is simpler than {@link Ext.form.CheckboxGroup#setValue} because only 1 value is allowed
  96      * for each name.
  97      *
  98      * @param {Object} value The map from names to values to be set.
  99      * @return {Ext.form.CheckboxGroup} this
 100      */
 101     setValue: function(value) {
 102         var me = this;
 103         if (Ext.isObject(value)) {
 104             Ext.Object.each(value, function(name, cbValue) {
 105                 var radios = Ext.form.RadioManager.getWithValue(name, cbValue);
 106                 radios.each(function(cb) {
 107                     cb.setValue(true);
 108                 });
 109             });
 110         }
 111         return me;
 112     }
 113 });
 114