src/form/field/Radio.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  * @docauthor Robert Dougan <rob@sencha.com>
  17  *
  18  * Single radio field. Similar to checkbox, but automatically handles making sure only one radio is checked
  19  * at a time within a group of radios with the same name.
  20  *
  21  * # Labeling
  22  *
  23  * In addition to the {@link Ext.form.Labelable standard field labeling options}, radio buttons
  24  * may be given an optional {@link #boxLabel} which will be displayed immediately to the right of the input. Also
  25  * see {@link Ext.form.RadioGroup} for a convenient method of grouping related radio buttons.
  26  *
  27  * # Values
  28  *
  29  * The main value of a Radio field is a boolean, indicating whether or not the radio is checked.
  30  *
  31  * The following values will check the radio:
  32  *
  33  * - `true`
  34  * - `'true'`
  35  * - `'1'`
  36  * - `'on'`
  37  *
  38  * Any other value will uncheck it.
  39  *
  40  * In addition to the main boolean value, you may also specify a separate {@link #inputValue}. This will be sent
  41  * as the parameter value when the form is {@link Ext.form.Basic#submit submitted}. You will want to set this
  42  * value if you have multiple radio buttons with the same {@link #name}, as is almost always the case.
  43  *
  44  * # Example usage
  45  *
  46  *     @example
  47  *     Ext.create('Ext.form.Panel', {
  48  *         title      : 'Order Form',
  49  *         width      : 300,
  50  *         bodyPadding: 10,
  51  *         renderTo   : Ext.getBody(),
  52  *         items: [
  53  *             {
  54  *                 xtype      : 'fieldcontainer',
  55  *                 fieldLabel : 'Size',
  56  *                 defaultType: 'radiofield',
  57  *                 defaults: {
  58  *                     flex: 1
  59  *                 },
  60  *                 layout: 'hbox',
  61  *                 items: [
  62  *                     {
  63  *                         boxLabel  : 'M',
  64  *                         name      : 'size',
  65  *                         inputValue: 'm',
  66  *                         id        : 'radio1'
  67  *                     }, {
  68  *                         boxLabel  : 'L',
  69  *                         name      : 'size',
  70  *                         inputValue: 'l',
  71  *                         id        : 'radio2'
  72  *                     }, {
  73  *                         boxLabel  : 'XL',
  74  *                         name      : 'size',
  75  *                         inputValue: 'xl',
  76  *                         id        : 'radio3'
  77  *                     }
  78  *                 ]
  79  *             },
  80  *             {
  81  *                 xtype      : 'fieldcontainer',
  82  *                 fieldLabel : 'Color',
  83  *                 defaultType: 'radiofield',
  84  *                 defaults: {
  85  *                     flex: 1
  86  *                 },
  87  *                 layout: 'hbox',
  88  *                 items: [
  89  *                     {
  90  *                         boxLabel  : 'Blue',
  91  *                         name      : 'color',
  92  *                         inputValue: 'blue',
  93  *                         id        : 'radio4'
  94  *                     }, {
  95  *                         boxLabel  : 'Grey',
  96  *                         name      : 'color',
  97  *                         inputValue: 'grey',
  98  *                         id        : 'radio5'
  99  *                     }, {
 100  *                         boxLabel  : 'Black',
 101  *                         name      : 'color',
 102  *                         inputValue: 'black',
 103  *                         id        : 'radio6'
 104  *                     }
 105  *                 ]
 106  *             }
 107  *         ],
 108  *         bbar: [
 109  *             {
 110  *                 text: 'Smaller Size',
 111  *                 handler: function() {
 112  *                     var radio1 = Ext.getCmp('radio1'),
 113  *                         radio2 = Ext.getCmp('radio2'),
 114  *                         radio3 = Ext.getCmp('radio3');
 115  *
 116  *                     //if L is selected, change to M
 117  *                     if (radio2.getValue()) {
 118  *                         radio1.setValue(true);
 119  *                         return;
 120  *                     }
 121  *
 122  *                     //if XL is selected, change to L
 123  *                     if (radio3.getValue()) {
 124  *                         radio2.setValue(true);
 125  *                         return;
 126  *                     }
 127  *
 128  *                     //if nothing is set, set size to S
 129  *                     radio1.setValue(true);
 130  *                 }
 131  *             },
 132  *             {
 133  *                 text: 'Larger Size',
 134  *                 handler: function() {
 135  *                     var radio1 = Ext.getCmp('radio1'),
 136  *                         radio2 = Ext.getCmp('radio2'),
 137  *                         radio3 = Ext.getCmp('radio3');
 138  *
 139  *                     //if M is selected, change to L
 140  *                     if (radio1.getValue()) {
 141  *                         radio2.setValue(true);
 142  *                         return;
 143  *                     }
 144  *
 145  *                     //if L is selected, change to XL
 146  *                     if (radio2.getValue()) {
 147  *                         radio3.setValue(true);
 148  *                         return;
 149  *                     }
 150  *
 151  *                     //if nothing is set, set size to XL
 152  *                     radio3.setValue(true);
 153  *                 }
 154  *             },
 155  *             '-',
 156  *             {
 157  *                 text: 'Select color',
 158  *                 menu: {
 159  *                     indent: false,
 160  *                     items: [
 161  *                         {
 162  *                             text: 'Blue',
 163  *                             handler: function() {
 164  *                                 var radio = Ext.getCmp('radio4');
 165  *                                 radio.setValue(true);
 166  *                             }
 167  *                         },
 168  *                         {
 169  *                             text: 'Grey',
 170  *                             handler: function() {
 171  *                                 var radio = Ext.getCmp('radio5');
 172  *                                 radio.setValue(true);
 173  *                             }
 174  *                         },
 175  *                         {
 176  *                             text: 'Black',
 177  *                             handler: function() {
 178  *                                 var radio = Ext.getCmp('radio6');
 179  *                                 radio.setValue(true);
 180  *                             }
 181  *                         }
 182  *                     ]
 183  *                 }
 184  *             }
 185  *         ]
 186  *     });
 187  */
 188 Ext.define('Ext.form.field.Radio', {
 189     extend:'Ext.form.field.Checkbox',
 190     alias: ['widget.radiofield', 'widget.radio'],
 191     alternateClassName: 'Ext.form.Radio',
 192     requires: ['Ext.form.RadioManager'],
 193
 194     isRadio: true,
 195
 196     /**
 197      * @cfg {String} uncheckedValue @hide
 198      */
 199
 200     // private
 201     inputType: 'radio',
 202     ariaRole: 'radio',
 203
 204     /**
 205      * If this radio is part of a group, it will return the selected value
 206      * @return {String}
 207      */
 208     getGroupValue: function() {
 209         var selected = this.getManager().getChecked(this.name);
 210         return selected ? selected.inputValue : null;
 211     },
 212
 213     /**
 214      * @private Handle click on the radio button
 215      */
 216     onBoxClick: function(e) {
 217         var me = this;
 218         if (!me.disabled && !me.readOnly) {
 219             this.setValue(true);
 220         }
 221     },
 222
 223     /**
 224      * Sets either the checked/unchecked status of this Radio, or, if a string value is passed, checks a sibling Radio
 225      * of the same name whose value is the value specified.
 226      * @param {String/Boolean} value Checked value, or the value of the sibling radio button to check.
 227      * @return {Ext.form.field.Radio} this
 228      */
 229     setValue: function(v) {
 230         var me = this,
 231             active;
 232
 233         if (Ext.isBoolean(v)) {
 234             me.callParent(arguments);
 235         } else {
 236             active = me.getManager().getWithValue(me.name, v).getAt(0);
 237             if (active) {
 238                 active.setValue(true);
 239             }
 240         }
 241         return me;
 242     },
 243
 244     /**
 245      * Returns the submit value for the checkbox which can be used when submitting forms.
 246      * @return {Boolean/Object} True if checked, null if not.
 247      */
 248     getSubmitValue: function() {
 249         return this.checked ? this.inputValue : null;
 250     },
 251
 252     getModelData: function() {
 253         return this.getSubmitData();
 254     },
 255
 256     // inherit docs
 257     onChange: function(newVal, oldVal) {
 258         var me = this;
 259         me.callParent(arguments);
 260
 261         if (newVal) {
 262             this.getManager().getByName(me.name).each(function(item){
 263                 if (item !== me) {
 264                     item.setValue(false);
 265                 }
 266             }, me);
 267         }
 268     },
 269
 270     // inherit docs
 271     getManager: function() {
 272         return Ext.form.RadioManager;
 273     }
 274 });
 275