docs/source/Checkbox.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="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/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-field-Checkbox'>/**
  19 </span> * @docauthor Robert Dougan &lt;rob@sencha.com&gt;
  20  *
  21  * Single checkbox field. Can be used as a direct replacement for traditional checkbox fields. Also serves as a
  22  * parent class for {@link Ext.form.field.Radio radio buttons}.
  23  *
  24  * # Labeling
  25  *
  26  * In addition to the {@link Ext.form.Labelable standard field labeling options}, checkboxes
  27  * may be given an optional {@link #boxLabel} which will be displayed immediately after checkbox. Also see
  28  * {@link Ext.form.CheckboxGroup} for a convenient method of grouping related checkboxes.
  29  *
  30  * # Values
  31  *
  32  * The main value of a checkbox is a boolean, indicating whether or not the checkbox is checked.
  33  * The following values will check the checkbox:
  34  *
  35  * - `true`
  36  * - `'true'`
  37  * - `'1'`
  38  * - `'on'`
  39  *
  40  * Any other value will uncheck the checkbox.
  41  *
  42  * In addition to the main boolean value, you may also specify a separate {@link #inputValue}. This will be
  43  * sent as the parameter value when the form is {@link Ext.form.Basic#submit submitted}. You will want to set
  44  * this value if you have multiple checkboxes with the same {@link #name}. If not specified, the value `on`
  45  * will be used.
  46  *
  47  * # Example usage
  48  *
  49  *     @example
  50  *     Ext.create('Ext.form.Panel', {
  51  *         bodyPadding: 10,
  52  *         width: 300,
  53  *         title: 'Pizza Order',
  54  *         items: [
  55  *             {
  56  *                 xtype: 'fieldcontainer',
  57  *                 fieldLabel: 'Toppings',
  58  *                 defaultType: 'checkboxfield',
  59  *                 items: [
  60  *                     {
  61  *                         boxLabel  : 'Anchovies',
  62  *                         name      : 'topping',
  63  *                         inputValue: '1',
  64  *                         id        : 'checkbox1'
  65  *                     }, {
  66  *                         boxLabel  : 'Artichoke Hearts',
  67  *                         name      : 'topping',
  68  *                         inputValue: '2',
  69  *                         checked   : true,
  70  *                         id        : 'checkbox2'
  71  *                     }, {
  72  *                         boxLabel  : 'Bacon',
  73  *                         name      : 'topping',
  74  *                         inputValue: '3',
  75  *                         id        : 'checkbox3'
  76  *                     }
  77  *                 ]
  78  *             }
  79  *         ],
  80  *         bbar: [
  81  *             {
  82  *                 text: 'Select Bacon',
  83  *                 handler: function() {
  84  *                     Ext.getCmp('checkbox3').setValue(true);
  85  *                 }
  86  *             },
  87  *             '-',
  88  *             {
  89  *                 text: 'Select All',
  90  *                 handler: function() {
  91  *                     Ext.getCmp('checkbox1').setValue(true);
  92  *                     Ext.getCmp('checkbox2').setValue(true);
  93  *                     Ext.getCmp('checkbox3').setValue(true);
  94  *                 }
  95  *             },
  96  *             {
  97  *                 text: 'Deselect All',
  98  *                 handler: function() {
  99  *                     Ext.getCmp('checkbox1').setValue(false);
 100  *                     Ext.getCmp('checkbox2').setValue(false);
 101  *                     Ext.getCmp('checkbox3').setValue(false);
 102  *                 }
 103  *             }
 104  *         ],
 105  *         renderTo: Ext.getBody()
 106  *     });
 107  */
 108 Ext.define('Ext.form.field.Checkbox', {
 109     extend: 'Ext.form.field.Base',
 110     alias: ['widget.checkboxfield', 'widget.checkbox'],
 111     alternateClassName: 'Ext.form.Checkbox',
 112     requires: ['Ext.XTemplate', 'Ext.form.CheckboxManager'],
 113
 114     // note: {id} here is really {inputId}, but {cmpId} is available
 115     fieldSubTpl: [
 116         '&lt;tpl if=&quot;boxLabel &amp;&amp; boxLabelAlign == \'before\'&quot;&gt;',
 117             '&lt;label id=&quot;{cmpId}-boxLabelEl&quot; class=&quot;{boxLabelCls} {boxLabelCls}-{boxLabelAlign}&quot; for=&quot;{id}&quot;&gt;{boxLabel}&lt;/label&gt;',
 118         '&lt;/tpl&gt;',
 119         // Creates not an actual checkbox, but a button which is given aria role=&quot;checkbox&quot; and
 120         // styled with a custom checkbox image. This allows greater control and consistency in
 121         // styling, and using a button allows it to gain focus and handle keyboard nav properly.
 122         '&lt;input type=&quot;button&quot; id=&quot;{id}&quot; ',
 123             '&lt;tpl if=&quot;tabIdx&quot;&gt;tabIndex=&quot;{tabIdx}&quot; &lt;/tpl&gt;',
 124             'class=&quot;{fieldCls} {typeCls}&quot; autocomplete=&quot;off&quot; hidefocus=&quot;true&quot; /&gt;',
 125         '&lt;tpl if=&quot;boxLabel &amp;&amp; boxLabelAlign == \'after\'&quot;&gt;',
 126             '&lt;label id=&quot;{cmpId}-boxLabelEl&quot; class=&quot;{boxLabelCls} {boxLabelCls}-{boxLabelAlign}&quot; for=&quot;{id}&quot;&gt;{boxLabel}&lt;/label&gt;',
 127         '&lt;/tpl&gt;',
 128         {
 129             disableFormats: true,
 130             compiled: true
 131         }
 132     ],
 133
 134     isCheckbox: true,
 135
 136 <span id='Ext-form-field-Checkbox-cfg-focusCls'>    /**
 137 </span>     * @cfg {String} [focusCls='x-form-cb-focus']
 138      * The CSS class to use when the checkbox receives focus
 139      */
 140     focusCls: Ext.baseCSSPrefix + 'form-cb-focus',
 141
 142 <span id='Ext-form-field-Checkbox-cfg-fieldCls'>    /**
 143 </span>     * @cfg {String} [fieldCls='x-form-field']
 144      * The default CSS class for the checkbox
 145      */
 146
 147 <span id='Ext-form-field-Checkbox-cfg-fieldBodyCls'>    /**
 148 </span>     * @cfg {String} [fieldBodyCls='x-form-cb-wrap']
 149      * An extra CSS class to be applied to the body content element in addition to {@link #fieldBodyCls}.
 150      * .
 151      */
 152     fieldBodyCls: Ext.baseCSSPrefix + 'form-cb-wrap',
 153
 154 <span id='Ext-form-field-Checkbox-cfg-checked'>    /**
 155 </span>     * @cfg {Boolean} checked
 156      * true if the checkbox should render initially checked
 157      */
 158     checked: false,
 159
 160 <span id='Ext-form-field-Checkbox-cfg-checkedCls'>    /**
 161 </span>     * @cfg {String} [checkedCls='x-form-cb-checked']
 162      * The CSS class added to the component's main element when it is in the checked state.
 163      */
 164     checkedCls: Ext.baseCSSPrefix + 'form-cb-checked',
 165
 166 <span id='Ext-form-field-Checkbox-cfg-boxLabel'>    /**
 167 </span>     * @cfg {String} boxLabel
 168      * An optional text label that will appear next to the checkbox. Whether it appears before or after the checkbox is
 169      * determined by the {@link #boxLabelAlign} config.
 170      */
 171
 172 <span id='Ext-form-field-Checkbox-cfg-boxLabelCls'>    /**
 173 </span>     * @cfg {String} [boxLabelCls='x-form-cb-label']
 174      * The CSS class to be applied to the {@link #boxLabel} element
 175      */
 176     boxLabelCls: Ext.baseCSSPrefix + 'form-cb-label',
 177
 178 <span id='Ext-form-field-Checkbox-cfg-boxLabelAlign'>    /**
 179 </span>     * @cfg {String} boxLabelAlign
 180      * The position relative to the checkbox where the {@link #boxLabel} should appear. Recognized values are 'before'
 181      * and 'after'.
 182      */
 183     boxLabelAlign: 'after',
 184
 185 <span id='Ext-form-field-Checkbox-cfg-inputValue'>    /**
 186 </span>     * @cfg {String} inputValue
 187      * The value that should go into the generated input element's value attribute and should be used as the parameter
 188      * value when submitting as part of a form.
 189      */
 190     inputValue: 'on',
 191
 192 <span id='Ext-form-field-Checkbox-cfg-uncheckedValue'>    /**
 193 </span>     * @cfg {String} uncheckedValue
 194      * If configured, this will be submitted as the checkbox's value during form submit if the checkbox is unchecked. By
 195      * default this is undefined, which results in nothing being submitted for the checkbox field when the form is
 196      * submitted (the default behavior of HTML checkboxes).
 197      */
 198
 199 <span id='Ext-form-field-Checkbox-cfg-handler'>    /**
 200 </span>     * @cfg {Function} handler
 201      * A function called when the {@link #checked} value changes (can be used instead of handling the {@link #change
 202      * change event}).
 203      * @cfg {Ext.form.field.Checkbox} handler.checkbox The Checkbox being toggled.
 204      * @cfg {Boolean} handler.checked The new checked state of the checkbox.
 205      */
 206
 207 <span id='Ext-form-field-Checkbox-cfg-scope'>    /**
 208 </span>     * @cfg {Object} scope
 209      * An object to use as the scope ('this' reference) of the {@link #handler} function (defaults to this Checkbox).
 210      */
 211
 212     // private overrides
 213     checkChangeEvents: [],
 214     inputType: 'checkbox',
 215     ariaRole: 'checkbox',
 216
 217     // private
 218     onRe: /^on$/i,
 219
 220     initComponent: function(){
 221         this.callParent(arguments);
 222         this.getManager().add(this);
 223     },
 224
 225     initValue: function() {
 226         var me = this,
 227             checked = !!me.checked;
 228
 229 <span id='Ext-form-field-Checkbox-property-originalValue'>        /**
 230 </span>         * @property {Object} originalValue
 231          * The original value of the field as configured in the {@link #checked} configuration, or as loaded by the last
 232          * form load operation if the form's {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad} setting is `true`.
 233          */
 234         me.originalValue = me.lastValue = checked;
 235
 236         // Set the initial checked state
 237         me.setValue(checked);
 238     },
 239
 240     // private
 241     onRender : function(ct, position) {
 242         var me = this;
 243
 244 <span id='Ext-form-field-Checkbox-property-boxLabelEl'>        /**
 245 </span>         * @property {Ext.Element} boxLabelEl
 246          * A reference to the label element created for the {@link #boxLabel}. Only present if the component has been
 247          * rendered and has a boxLabel configured.
 248          */
 249         me.addChildEls('boxLabelEl');
 250
 251         Ext.applyIf(me.subTplData, {
 252             boxLabel: me.boxLabel,
 253             boxLabelCls: me.boxLabelCls,
 254             boxLabelAlign: me.boxLabelAlign
 255         });
 256
 257         me.callParent(arguments);
 258     },
 259
 260     initEvents: function() {
 261         var me = this;
 262         me.callParent();
 263         me.mon(me.inputEl, 'click', me.onBoxClick, me);
 264     },
 265
 266 <span id='Ext-form-field-Checkbox-method-onBoxClick'>    /**
 267 </span>     * @private Handle click on the checkbox button
 268      */
 269     onBoxClick: function(e) {
 270         var me = this;
 271         if (!me.disabled &amp;&amp; !me.readOnly) {
 272             this.setValue(!this.checked);
 273         }
 274     },
 275
 276 <span id='Ext-form-field-Checkbox-method-getRawValue'>    /**
 277 </span>     * Returns the checked state of the checkbox.
 278      * @return {Boolean} True if checked, else false
 279      */
 280     getRawValue: function() {
 281         return this.checked;
 282     },
 283
 284 <span id='Ext-form-field-Checkbox-method-getValue'>    /**
 285 </span>     * Returns the checked state of the checkbox.
 286      * @return {Boolean} True if checked, else false
 287      */
 288     getValue: function() {
 289         return this.checked;
 290     },
 291
 292 <span id='Ext-form-field-Checkbox-method-getSubmitValue'>    /**
 293 </span>     * Returns the submit value for the checkbox which can be used when submitting forms.
 294      * @return {Boolean/Object} True if checked; otherwise either the {@link #uncheckedValue} or null.
 295      */
 296     getSubmitValue: function() {
 297         var unchecked = this.uncheckedValue,
 298             uncheckedVal = Ext.isDefined(unchecked) ? unchecked : null;
 299         return this.checked ? this.inputValue : uncheckedVal;
 300     },
 301
 302 <span id='Ext-form-field-Checkbox-method-setRawValue'>    /**
 303 </span>     * Sets the checked state of the checkbox.
 304      *
 305      * @param {Boolean/String/Number} value The following values will check the checkbox:
 306      * `true, 'true', '1', 1, or 'on'`, as well as a String that matches the {@link #inputValue}.
 307      * Any other value will uncheck the checkbox.
 308      * @return {Boolean} the new checked state of the checkbox
 309      */
 310     setRawValue: function(value) {
 311         var me = this,
 312             inputEl = me.inputEl,
 313             inputValue = me.inputValue,
 314             checked = (value === true || value === 'true' || value === '1' || value === 1 ||
 315                 (((Ext.isString(value) || Ext.isNumber(value)) &amp;&amp; inputValue) ? value == inputValue : me.onRe.test(value)));
 316
 317         if (inputEl) {
 318             inputEl.dom.setAttribute('aria-checked', checked);
 319             me[checked ? 'addCls' : 'removeCls'](me.checkedCls);
 320         }
 321
 322         me.checked = me.rawValue = checked;
 323         return checked;
 324     },
 325
 326 <span id='Ext-form-field-Checkbox-method-setValue'>    /**
 327 </span>     * Sets the checked state of the checkbox, and invokes change detection.
 328      * @param {Boolean/String} checked The following values will check the checkbox: `true, 'true', '1', or 'on'`, as
 329      * well as a String that matches the {@link #inputValue}. Any other value will uncheck the checkbox.
 330      * @return {Ext.form.field.Checkbox} this
 331      */
 332     setValue: function(checked) {
 333         var me = this;
 334
 335         // If an array of strings is passed, find all checkboxes in the group with the same name as this
 336         // one and check all those whose inputValue is in the array, unchecking all the others. This is to
 337         // facilitate setting values from Ext.form.Basic#setValues, but is not publicly documented as we
 338         // don't want users depending on this behavior.
 339         if (Ext.isArray(checked)) {
 340             me.getManager().getByName(me.name).each(function(cb) {
 341                 cb.setValue(Ext.Array.contains(checked, cb.inputValue));
 342             });
 343         } else {
 344             me.callParent(arguments);
 345         }
 346
 347         return me;
 348     },
 349
 350     // private
 351     valueToRaw: function(value) {
 352         // No extra conversion for checkboxes
 353         return value;
 354     },
 355
 356 <span id='Ext-form-field-Checkbox-method-onChange'>    /**
 357 </span>     * @private
 358      * Called when the checkbox's checked state changes. Invokes the {@link #handler} callback
 359      * function if specified.
 360      */
 361     onChange: function(newVal, oldVal) {
 362         var me = this,
 363             handler = me.handler;
 364         if (handler) {
 365             handler.call(me.scope || me, me, newVal);
 366         }
 367         me.callParent(arguments);
 368     },
 369
 370     // inherit docs
 371     beforeDestroy: function(){
 372         this.callParent();
 373         this.getManager().removeAtKey(this.id);
 374     },
 375
 376     // inherit docs
 377     getManager: function() {
 378         return Ext.form.CheckboxManager;
 379     },
 380
 381     onEnable: function() {
 382         var me = this,
 383             inputEl = me.inputEl;
 384         me.callParent();
 385         if (inputEl) {
 386             // Can still be disabled if the field is readOnly
 387             inputEl.dom.disabled = me.readOnly;
 388         }
 389     },
 390
 391     setReadOnly: function(readOnly) {
 392         var me = this,
 393             inputEl = me.inputEl;
 394         if (inputEl) {
 395             // Set the button to disabled when readonly
 396             inputEl.dom.disabled = readOnly || me.disabled;
 397         }
 398         me.readOnly = readOnly;
 399     },
 400
 401     // Calculates and returns the natural width of the bodyEl. It's possible that the initial rendering will
 402     // cause the boxLabel to wrap and give us a bad width, so we must prevent wrapping while measuring.
 403     getBodyNaturalWidth: function() {
 404         var me = this,
 405             bodyEl = me.bodyEl,
 406             ws = 'white-space',
 407             width;
 408         bodyEl.setStyle(ws, 'nowrap');
 409         width = bodyEl.getWidth();
 410         bodyEl.setStyle(ws, '');
 411         return width;
 412     }
 413
 414 });
 415 </pre>
 416 </body>
 417 </html>