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