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-method-constructor'><span id='Ext-form-Panel'>/**
  19 </span></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  * @constructor
 139  * @param {Object} config Configuration options
 140  * @xtype form
 141  *
 142  * @markdown
 143  * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
 144  */
 145 Ext.define('Ext.form.Panel', {
 146     extend:'Ext.panel.Panel',
 147     mixins: {
 148         fieldAncestor: 'Ext.form.FieldAncestor'
 149     },
 150     alias: 'widget.form',
 151     alternateClassName: ['Ext.FormPanel', 'Ext.form.FormPanel'],
 152     requires: ['Ext.form.Basic', 'Ext.util.TaskRunner'],
 153
 154 <span id='Ext-form-Panel-cfg-pollForChanges'>    /**
 155 </span>     * @cfg {Boolean} pollForChanges
 156      * If set to &lt;tt&gt;true&lt;/tt&gt;, sets up an interval task (using the {@link #pollInterval}) in which the
 157      * panel's fields are repeatedly checked for changes in their values. This is in addition to the normal detection
 158      * each field does on its own input element, and is not needed in most cases. It does, however, provide a
 159      * means to absolutely guarantee detection of all changes including some edge cases in some browsers which
 160      * do not fire native events. Defaults to &lt;tt&gt;false&lt;/tt&gt;.
 161      */
 162
 163 <span id='Ext-form-Panel-cfg-pollInterval'>    /**
 164 </span>     * @cfg {Number} pollInterval
 165      * Interval in milliseconds at which the form's fields are checked for value changes. Only used if
 166      * the {@link #pollForChanges} option is set to &lt;tt&gt;true&lt;/tt&gt;. Defaults to 500 milliseconds.
 167      */
 168
 169 <span id='Ext-form-Panel-cfg-layout'>    /**
 170 </span>     * @cfg {String} layout The {@link Ext.container.Container#layout} for the form panel's immediate child items.
 171      * Defaults to &lt;tt&gt;'anchor'&lt;/tt&gt;.
 172      */
 173     layout: 'anchor',
 174
 175     ariaRole: 'form',
 176
 177     initComponent: function() {
 178         var me = this;
 179
 180         if (me.frame) {
 181             me.border = false;
 182         }
 183
 184         me.initFieldAncestor();
 185         me.callParent();
 186
 187         me.relayEvents(me.form, [
 188             'beforeaction',
 189             'actionfailed',
 190             'actioncomplete',
 191             'validitychange',
 192             'dirtychange'
 193         ]);
 194
 195         // Start polling if configured
 196         if (me.pollForChanges) {
 197             me.startPolling(me.pollInterval || 500);
 198         }
 199     },
 200
 201     initItems: function() {
 202         // Create the BasicForm
 203         var me = this;
 204
 205         me.form = me.createForm();
 206         me.callParent();
 207         me.form.initialize();
 208     },
 209
 210 <span id='Ext-form-Panel-method-createForm'>    /**
 211 </span>     * @private
 212      */
 213     createForm: function() {
 214         return Ext.create('Ext.form.Basic', this, Ext.applyIf({listeners: {}}, this.initialConfig));
 215     },
 216
 217 <span id='Ext-form-Panel-method-getForm'>    /**
 218 </span>     * Provides access to the {@link Ext.form.Basic Form} which this Panel contains.
 219      * @return {Ext.form.Basic} The {@link Ext.form.Basic Form} which this Panel contains.
 220      */
 221     getForm: function() {
 222         return this.form;
 223     },
 224
 225 <span id='Ext-form-Panel-method-loadRecord'>    /**
 226 </span>     * Loads an {@link Ext.data.Model} into this form (internally just calls {@link Ext.form.Basic#loadRecord})
 227      * See also {@link #trackResetOnLoad}.
 228      * @param {Ext.data.Model} record The record to load
 229      * @return {Ext.form.Basic} The Ext.form.Basic attached to this FormPanel
 230      */
 231     loadRecord: function(record) {
 232         return this.getForm().loadRecord(record);
 233     },
 234
 235 <span id='Ext-form-Panel-method-getRecord'>    /**
 236 </span>     * Returns the currently loaded Ext.data.Model instance if one was loaded via {@link #loadRecord}.
 237      * @return {Ext.data.Model} The loaded instance
 238      */
 239     getRecord: function() {
 240         return this.getForm().getRecord();
 241     },
 242
 243 <span id='Ext-form-Panel-method-getValues'>    /**
 244 </span>     * Convenience function for fetching the current value of each field in the form. This is the same as calling
 245      * {@link Ext.form.Basic#getValues this.getForm().getValues()}
 246      * @return {Object} The current form field values, keyed by field name
 247      */
 248     getValues: function() {
 249         return this.getForm().getValues();
 250     },
 251
 252     beforeDestroy: function() {
 253         this.stopPolling();
 254         this.form.destroy();
 255         this.callParent();
 256     },
 257
 258 <span id='Ext-form-Panel-method-load'>    /**
 259 </span>     * This is a proxy for the underlying BasicForm's {@link Ext.form.Basic#load} call.
 260      * @param {Object} options The options to pass to the action (see {@link Ext.form.Basic#load} and
 261      * {@link Ext.form.Basic#doAction} for details)
 262      */
 263     load: function(options) {
 264         this.form.load(options);
 265     },
 266
 267 <span id='Ext-form-Panel-method-submit'>    /**
 268 </span>     * This is a proxy for the underlying BasicForm's {@link Ext.form.Basic#submit} call.
 269      * @param {Object} options The options to pass to the action (see {@link Ext.form.Basic#submit} and
 270      * {@link Ext.form.Basic#doAction} for details)
 271      */
 272     submit: function(options) {
 273         this.form.submit(options);
 274     },
 275
 276     /*
 277      * Inherit docs, not using onDisable because it only gets fired
 278      * when the component is rendered.
 279      */
 280     disable: function(silent) {
 281         this.callParent(arguments);
 282         this.form.getFields().each(function(field) {
 283             field.disable();
 284         });
 285     },
 286
 287     /*
 288      * Inherit docs, not using onEnable because it only gets fired
 289      * when the component is rendered.
 290      */
 291     enable: function(silent) {
 292         this.callParent(arguments);
 293         this.form.getFields().each(function(field) {
 294             field.enable();
 295         });
 296     },
 297
 298 <span id='Ext-form-Panel-method-startPolling'>    /**
 299 </span>     * Start an interval task to continuously poll all the fields in the form for changes in their
 300      * values. This is normally started automatically by setting the {@link #pollForChanges} config.
 301      * @param {Number} interval The interval in milliseconds at which the check should run.
 302      */
 303     startPolling: function(interval) {
 304         this.stopPolling();
 305         var task = Ext.create('Ext.util.TaskRunner', interval);
 306         task.start({
 307             interval: 0,
 308             run: this.checkChange,
 309             scope: this
 310         });
 311         this.pollTask = task;
 312     },
 313
 314 <span id='Ext-form-Panel-method-stopPolling'>    /**
 315 </span>     * Stop a running interval task that was started by {@link #startPolling}.
 316      */
 317     stopPolling: function() {
 318         var task = this.pollTask;
 319         if (task) {
 320             task.stopAll();
 321             delete this.pollTask;
 322         }
 323     },
 324
 325 <span id='Ext-form-Panel-method-checkChange'>    /**
 326 </span>     * Forces each field within the form panel to
 327      * {@link Ext.form.field.Field#checkChange check if its value has changed}.
 328      */
 329     checkChange: function() {
 330         this.form.getFields().each(function(field) {
 331             field.checkChange();
 332         });
 333     }
 334 });
 335 </pre>
 336 </body>
 337 </html>