docs/source/Panel.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-Panel'>/**
  19 </span> * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
  20  *
  21  * FormPanel provides a standard container for forms. It is essentially a standard {@link Ext.panel.Panel} which
  22  * automatically creates a {@link Ext.form.Basic BasicForm} for managing any {@link Ext.form.field.Field}
  23  * objects that are added as descendants of the panel. It also includes conveniences for configuring and
  24  * working with the BasicForm and the collection of Fields.
  25  *
  26  * # Layout
  27  *
  28  * By default, FormPanel is configured with `{@link Ext.layout.container.Anchor layout:'anchor'}` for
  29  * the layout of its immediate child items. This can be changed to any of the supported container layouts.
  30  * The layout of sub-containers is configured in {@link Ext.container.Container#layout the standard way}.
  31  *
  32  * # BasicForm
  33  *
  34  * Although **not listed** as configuration options of FormPanel, the FormPanel class accepts all
  35  * of the config options supported by the {@link Ext.form.Basic} class, and will pass them along to
  36  * the internal BasicForm when it is created.
  37  *
  38  * **Note**: If subclassing FormPanel, any configuration options for the BasicForm must be applied to
  39  * the `initialConfig` property of the FormPanel. Applying {@link Ext.form.Basic BasicForm}
  40  * configuration settings to `this` will *not* affect the BasicForm's configuration.
  41  *
  42  * The following events fired by the BasicForm will be re-fired by the FormPanel and can therefore be
  43  * listened for on the FormPanel itself:
  44  *
  45  * - {@link Ext.form.Basic#beforeaction beforeaction}
  46  * - {@link Ext.form.Basic#actionfailed actionfailed}
  47  * - {@link Ext.form.Basic#actioncomplete actioncomplete}
  48  * - {@link Ext.form.Basic#validitychange validitychange}
  49  * - {@link Ext.form.Basic#dirtychange dirtychange}
  50  *
  51  * # Field Defaults
  52  *
  53  * The {@link #fieldDefaults} config option conveniently allows centralized configuration of default values
  54  * for all fields added as descendants of the FormPanel. Any config option recognized by implementations
  55  * of {@link Ext.form.Labelable} may be included in this object. See the {@link #fieldDefaults} documentation
  56  * for details of how the defaults are applied.
  57  *
  58  * # Form Validation
  59  *
  60  * With the default configuration, form fields are validated on-the-fly while the user edits their values.
  61  * This can be controlled on a per-field basis (or via the {@link #fieldDefaults} config) with the field
  62  * config properties {@link Ext.form.field.Field#validateOnChange} and {@link Ext.form.field.Base#checkChangeEvents},
  63  * and the FormPanel's config properties {@link #pollForChanges} and {@link #pollInterval}.
  64  *
  65  * Any component within the FormPanel can be configured with `formBind: true`. This will cause that
  66  * component to be automatically disabled when the form is invalid, and enabled when it is valid. This is most
  67  * commonly used for Button components to prevent submitting the form in an invalid state, but can be used on
  68  * any component type.
  69  *
  70  * For more information on form validation see the following:
  71  *
  72  * - {@link Ext.form.field.Field#validateOnChange}
  73  * - {@link #pollForChanges} and {@link #pollInterval}
  74  * - {@link Ext.form.field.VTypes}
  75  * - {@link Ext.form.Basic#doAction BasicForm.doAction clientValidation notes}
  76  *
  77  * # Form Submission
  78  *
  79  * By default, Ext Forms are submitted through Ajax, using {@link Ext.form.action.Action}. See the documentation for
  80  * {@link Ext.form.Basic} for details.
  81  *
  82  * # Example usage
  83  *
  84  *     @example
  85  *     Ext.create('Ext.form.Panel', {
  86  *         title: 'Simple Form',
  87  *         bodyPadding: 5,
  88  *         width: 350,
  89  *
  90  *         // The form will submit an AJAX request to this URL when submitted
  91  *         url: 'save-form.php',
  92  *
  93  *         // Fields will be arranged vertically, stretched to full width
  94  *         layout: 'anchor',
  95  *         defaults: {
  96  *             anchor: '100%'
  97  *         },
  98  *
  99  *         // The fields
 100  *         defaultType: 'textfield',
 101  *         items: [{
 102  *             fieldLabel: 'First Name',
 103  *             name: 'first',
 104  *             allowBlank: false
 105  *         },{
 106  *             fieldLabel: 'Last Name',
 107  *             name: 'last',
 108  *             allowBlank: false
 109  *         }],
 110  *
 111  *         // Reset and Submit buttons
 112  *         buttons: [{
 113  *             text: 'Reset',
 114  *             handler: function() {
 115  *                 this.up('form').getForm().reset();
 116  *             }
 117  *         }, {
 118  *             text: 'Submit',
 119  *             formBind: true, //only enabled once the form is valid
 120  *             disabled: true,
 121  *             handler: function() {
 122  *                 var form = this.up('form').getForm();
 123  *                 if (form.isValid()) {
 124  *                     form.submit({
 125  *                         success: function(form, action) {
 126  *                            Ext.Msg.alert('Success', action.result.msg);
 127  *                         },
 128  *                         failure: function(form, action) {
 129  *                             Ext.Msg.alert('Failed', action.result.msg);
 130  *                         }
 131  *                     });
 132  *                 }
 133  *             }
 134  *         }],
 135  *         renderTo: Ext.getBody()
 136  *     });
 137  *
 138  */
 139 Ext.define('Ext.form.Panel', {
 140     extend:'Ext.panel.Panel',
 141     mixins: {
 142         fieldAncestor: 'Ext.form.FieldAncestor'
 143     },
 144     alias: 'widget.form',
 145     alternateClassName: ['Ext.FormPanel', 'Ext.form.FormPanel'],
 146     requires: ['Ext.form.Basic', 'Ext.util.TaskRunner'],
 147
 148 <span id='Ext-form-Panel-cfg-pollForChanges'>    /**
 149 </span>     * @cfg {Boolean} pollForChanges
 150      * If set to `true`, sets up an interval task (using the {@link #pollInterval}) in which the
 151      * panel's fields are repeatedly checked for changes in their values. This is in addition to the normal detection
 152      * each field does on its own input element, and is not needed in most cases. It does, however, provide a
 153      * means to absolutely guarantee detection of all changes including some edge cases in some browsers which
 154      * do not fire native events. Defaults to `false`.
 155      */
 156
 157 <span id='Ext-form-Panel-cfg-pollInterval'>    /**
 158 </span>     * @cfg {Number} pollInterval
 159      * Interval in milliseconds at which the form's fields are checked for value changes. Only used if
 160      * the {@link #pollForChanges} option is set to `true`. Defaults to 500 milliseconds.
 161      */
 162
 163 <span id='Ext-form-Panel-cfg-layout'>    /**
 164 </span>     * @cfg {String} layout
 165      * The {@link Ext.container.Container#layout} for the form panel's immediate child items.
 166      * Defaults to `'anchor'`.
 167      */
 168     layout: 'anchor',
 169
 170     ariaRole: 'form',
 171
 172     initComponent: function() {
 173         var me = this;
 174
 175         if (me.frame) {
 176             me.border = false;
 177         }
 178
 179         me.initFieldAncestor();
 180         me.callParent();
 181
 182         me.relayEvents(me.form, [
 183             'beforeaction',
 184             'actionfailed',
 185             'actioncomplete',
 186             'validitychange',
 187             'dirtychange'
 188         ]);
 189
 190         // Start polling if configured
 191         if (me.pollForChanges) {
 192             me.startPolling(me.pollInterval || 500);
 193         }
 194     },
 195
 196     initItems: function() {
 197         // Create the BasicForm
 198         var me = this;
 199
 200         me.form = me.createForm();
 201         me.callParent();
 202         me.form.initialize();
 203     },
 204
 205 <span id='Ext-form-Panel-method-createForm'>    /**
 206 </span>     * @private
 207      */
 208     createForm: function() {
 209         return Ext.create('Ext.form.Basic', this, Ext.applyIf({listeners: {}}, this.initialConfig));
 210     },
 211
 212 <span id='Ext-form-Panel-method-getForm'>    /**
 213 </span>     * Provides access to the {@link Ext.form.Basic Form} which this Panel contains.
 214      * @return {Ext.form.Basic} The {@link Ext.form.Basic Form} which this Panel contains.
 215      */
 216     getForm: function() {
 217         return this.form;
 218     },
 219
 220 <span id='Ext-form-Panel-method-loadRecord'>    /**
 221 </span>     * Loads an {@link Ext.data.Model} into this form (internally just calls {@link Ext.form.Basic#loadRecord})
 222      * See also {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad}.
 223      * @param {Ext.data.Model} record The record to load
 224      * @return {Ext.form.Basic} The Ext.form.Basic attached to this FormPanel
 225      */
 226     loadRecord: function(record) {
 227         return this.getForm().loadRecord(record);
 228     },
 229
 230 <span id='Ext-form-Panel-method-getRecord'>    /**
 231 </span>     * Returns the currently loaded Ext.data.Model instance if one was loaded via {@link #loadRecord}.
 232      * @return {Ext.data.Model} The loaded instance
 233      */
 234     getRecord: function() {
 235         return this.getForm().getRecord();
 236     },
 237
 238 <span id='Ext-form-Panel-method-getValues'>    /**
 239 </span>     * Convenience function for fetching the current value of each field in the form. This is the same as calling
 240      * {@link Ext.form.Basic#getValues this.getForm().getValues()}
 241      * @return {Object} The current form field values, keyed by field name
 242      */
 243     getValues: function() {
 244         return this.getForm().getValues();
 245     },
 246
 247     beforeDestroy: function() {
 248         this.stopPolling();
 249         this.form.destroy();
 250         this.callParent();
 251     },
 252
 253 <span id='Ext-form-Panel-method-load'>    /**
 254 </span>     * This is a proxy for the underlying BasicForm's {@link Ext.form.Basic#load} call.
 255      * @param {Object} options The options to pass to the action (see {@link Ext.form.Basic#load} and
 256      * {@link Ext.form.Basic#doAction} for details)
 257      */
 258     load: function(options) {
 259         this.form.load(options);
 260     },
 261
 262 <span id='Ext-form-Panel-method-submit'>    /**
 263 </span>     * This is a proxy for the underlying BasicForm's {@link Ext.form.Basic#submit} call.
 264      * @param {Object} options The options to pass to the action (see {@link Ext.form.Basic#submit} and
 265      * {@link Ext.form.Basic#doAction} for details)
 266      */
 267     submit: function(options) {
 268         this.form.submit(options);
 269     },
 270
 271     /*
 272      * Inherit docs, not using onDisable because it only gets fired
 273      * when the component is rendered.
 274      */
 275     disable: function(silent) {
 276         this.callParent(arguments);
 277         this.form.getFields().each(function(field) {
 278             field.disable();
 279         });
 280     },
 281
 282     /*
 283      * Inherit docs, not using onEnable because it only gets fired
 284      * when the component is rendered.
 285      */
 286     enable: function(silent) {
 287         this.callParent(arguments);
 288         this.form.getFields().each(function(field) {
 289             field.enable();
 290         });
 291     },
 292
 293 <span id='Ext-form-Panel-method-startPolling'>    /**
 294 </span>     * Start an interval task to continuously poll all the fields in the form for changes in their
 295      * values. This is normally started automatically by setting the {@link #pollForChanges} config.
 296      * @param {Number} interval The interval in milliseconds at which the check should run.
 297      */
 298     startPolling: function(interval) {
 299         this.stopPolling();
 300         var task = Ext.create('Ext.util.TaskRunner', interval);
 301         task.start({
 302             interval: 0,
 303             run: this.checkChange,
 304             scope: this
 305         });
 306         this.pollTask = task;
 307     },
 308
 309 <span id='Ext-form-Panel-method-stopPolling'>    /**
 310 </span>     * Stop a running interval task that was started by {@link #startPolling}.
 311      */
 312     stopPolling: function() {
 313         var task = this.pollTask;
 314         if (task) {
 315             task.stopAll();
 316             delete this.pollTask;
 317         }
 318     },
 319
 320 <span id='Ext-form-Panel-method-checkChange'>    /**
 321 </span>     * Forces each field within the form panel to
 322      * {@link Ext.form.field.Field#checkChange check if its value has changed}.
 323      */
 324     checkChange: function() {
 325         this.form.getFields().each(function(field) {
 326             field.checkChange();
 327         });
 328     }
 329 });
 330 </pre>
 331 </body>
 332 </html>