docs/source/Panel.html

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