add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / form / Panel.js

/**\r
 * FormPanel provides a standard container for forms. It is essentially a standard {@link Ext.panel.Panel} which\r
 * automatically creates a {@link Ext.form.Basic BasicForm} for managing any {@link Ext.form.field.Field}\r
 * objects that are added as descendants of the panel. It also includes conveniences for configuring and\r
 * working with the BasicForm and the collection of Fields.\r
 * \r
 * # Layout\r
 * \r
 * By default, FormPanel is configured with `{@link Ext.layout.container.Anchor layout:'anchor'}` for\r
 * the layout of its immediate child items. This can be changed to any of the supported container layouts.\r
 * The layout of sub-containers is configured in {@link Ext.container.Container#layout the standard way}.\r
 * \r
 * # BasicForm\r
 * \r
 * FormPanel class accepts all\r
 * of the config options supported by the {@link Ext.form.Basic} class, and will pass them along to\r
 * the internal BasicForm when it is created.\r
 * \r
 * The following events fired by the BasicForm will be re-fired by the FormPanel and can therefore be\r
 * listened for on the FormPanel itself:\r
 * \r
 * - {@link Ext.form.Basic#beforeaction beforeaction}\r
 * - {@link Ext.form.Basic#actionfailed actionfailed}\r
 * - {@link Ext.form.Basic#actioncomplete actioncomplete}\r
 * - {@link Ext.form.Basic#validitychange validitychange}\r
 * - {@link Ext.form.Basic#dirtychange dirtychange}\r
 * \r
 * # Field Defaults\r
 * \r
 * The {@link #fieldDefaults} config option conveniently allows centralized configuration of default values\r
 * for all fields added as descendants of the FormPanel. Any config option recognized by implementations\r
 * of {@link Ext.form.Labelable} may be included in this object. See the {@link #fieldDefaults} documentation\r
 * for details of how the defaults are applied.\r
 * \r
 * # Form Validation\r
 * \r
 * With the default configuration, form fields are validated on-the-fly while the user edits their values.\r
 * This can be controlled on a per-field basis (or via the {@link #fieldDefaults} config) with the field\r
 * config properties {@link Ext.form.field.Field#validateOnChange} and {@link Ext.form.field.Base#checkChangeEvents},\r
 * and the FormPanel's config properties {@link #pollForChanges} and {@link #pollInterval}.\r
 * \r
 * Any component within the FormPanel can be configured with `formBind: true`. This will cause that\r
 * component to be automatically disabled when the form is invalid, and enabled when it is valid. This is most\r
 * commonly used for Button components to prevent submitting the form in an invalid state, but can be used on\r
 * any component type.\r
 * \r
 * For more information on form validation see the following:\r
 * \r
 * - {@link Ext.form.field.Field#validateOnChange}\r
 * - {@link #pollForChanges} and {@link #pollInterval}\r
 * - {@link Ext.form.field.VTypes}\r
 * - {@link Ext.form.Basic#doAction BasicForm.doAction clientValidation notes}\r
 * \r
 * # Form Submission\r
 * \r
 * By default, Ext Forms are submitted through Ajax, using {@link Ext.form.action.Action}. See the documentation for\r
 * {@link Ext.form.Basic} for details.\r
 *\r
 * # Example usage\r
 * \r
 *     @example\r
 *     Ext.create('Ext.form.Panel', {\r
 *         title: 'Simple Form',\r
 *         bodyPadding: 5,\r
 *         width: 350,\r
 * \r
 *         // The form will submit an AJAX request to this URL when submitted\r
 *         url: 'save-form.php',\r
 * \r
 *         // Fields will be arranged vertically, stretched to full width\r
 *         layout: 'anchor',\r
 *         defaults: {\r
 *             anchor: '100%'\r
 *         },\r
 * \r
 *         // The fields\r
 *         defaultType: 'textfield',\r
 *         items: [{\r
 *             fieldLabel: 'First Name',\r
 *             name: 'first',\r
 *             allowBlank: false\r
 *         },{\r
 *             fieldLabel: 'Last Name',\r
 *             name: 'last',\r
 *             allowBlank: false\r
 *         }],\r
 * \r
 *         // Reset and Submit buttons\r
 *         buttons: [{\r
 *             text: 'Reset',\r
 *             handler: function() {\r
 *                 this.up('form').getForm().reset();\r
 *             }\r
 *         }, {\r
 *             text: 'Submit',\r
 *             formBind: true, //only enabled once the form is valid\r
 *             disabled: true,\r
 *             handler: function() {\r
 *                 var form = this.up('form').getForm();\r
 *                 if (form.isValid()) {\r
 *                     form.submit({\r
 *                         success: function(form, action) {\r
 *                            Ext.Msg.alert('Success', action.result.msg);\r
 *                         },\r
 *                         failure: function(form, action) {\r
 *                             Ext.Msg.alert('Failed', action.result.msg);\r
 *                         }\r
 *                     });\r
 *                 }\r
 *             }\r
 *         }],\r
 *         renderTo: Ext.getBody()\r
 *     });\r
 *\r
 */\r
Ext.define('Ext.form.Panel', {\r
    extend:'Ext.panel.Panel',\r
    mixins: {\r
        fieldAncestor: 'Ext.form.FieldAncestor'\r
    },\r
    alias: 'widget.form',\r
    alternateClassName: ['Ext.FormPanel', 'Ext.form.FormPanel'],\r
    requires: ['Ext.form.Basic', 'Ext.util.TaskRunner'],\r
\r
    /**\r
     * @cfg {Boolean} pollForChanges\r
     * If set to `true`, sets up an interval task (using the {@link #pollInterval}) in which the\r
     * panel's fields are repeatedly checked for changes in their values. This is in addition to the normal detection\r
     * each field does on its own input element, and is not needed in most cases. It does, however, provide a\r
     * means to absolutely guarantee detection of all changes including some edge cases in some browsers which\r
     * do not fire native events. Defaults to `false`.\r
     */\r
\r
    /**\r
     * @cfg {Number} pollInterval\r
     * Interval in milliseconds at which the form's fields are checked for value changes. Only used if\r
     * the {@link #pollForChanges} option is set to `true`. Defaults to 500 milliseconds.\r
     */\r
\r
    /**\r
     * @cfg {Ext.enums.Layout/Object} layout\r
     * The {@link Ext.container.Container#layout} for the form panel's immediate child items.\r
     */\r
    layout: 'anchor',\r
\r
    bodyAriaRole: 'form',\r
    \r
    basicFormConfigs: [\r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#api\r
         */\r
        'api', \r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#baseParams\r
         */\r
        'baseParams', \r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#errorReader\r
         */\r
        'errorReader', \r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#jsonSubmit\r
         */\r
        'jsonSubmit',\r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#method\r
         */\r
        'method', \r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#paramOrder\r
         */\r
        'paramOrder',\r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#paramsAsHash\r
         */\r
        'paramsAsHash',\r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#reader\r
         */\r
        'reader',\r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#standardSubmit\r
         */\r
        'standardSubmit',\r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#timeout\r
         */\r
        'timeout',\r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#trackResetOnLoad\r
         */\r
        'trackResetOnLoad',\r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#url\r
         */\r
        'url',\r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#waitMsgTarget\r
         */\r
        'waitMsgTarget',\r
        /**\r
         * @cfg\r
         * @inheritdoc Ext.form.Basic#waitTitle\r
         */\r
        'waitTitle'\r
    ],\r
\r
    initComponent: function() {\r
        var me = this;\r
\r
        if (me.frame) {\r
            me.border = false;\r
        }\r
\r
        me.initFieldAncestor();\r
        me.callParent();\r
\r
        me.relayEvents(me.form, [\r
            /**\r
             * @event beforeaction\r
             * @inheritdoc Ext.form.Basic#beforeaction\r
             */\r
            'beforeaction',\r
            /**\r
             * @event actionfailed\r
             * @inheritdoc Ext.form.Basic#actionfailed\r
             */\r
            'actionfailed',\r
            /**\r
             * @event actioncomplete\r
             * @inheritdoc Ext.form.Basic#actioncomplete\r
             */\r
            'actioncomplete',\r
            /**\r
             * @event validitychange\r
             * @inheritdoc Ext.form.Basic#validitychange\r
             */\r
            'validitychange',\r
            /**\r
             * @event dirtychange\r
             * @inheritdoc Ext.form.Basic#dirtychange\r
             */\r
            'dirtychange'\r
        ]);\r
\r
        // Start polling if configured\r
        if (me.pollForChanges) {\r
            me.startPolling(me.pollInterval || 500);\r
        }\r
    },\r
\r
    initItems: function() {\r
        // Create the BasicForm\r
        this.callParent();\r
        this.initMonitor();\r
        this.form = this.createForm();\r
    },\r
\r
    // Initialize the BasicForm after all layouts have been completed.\r
    afterFirstLayout: function() {\r
        this.callParent(arguments);\r
        this.form.initialize();\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    createForm: function() {\r
        var cfg = {},\r
            props = this.basicFormConfigs,\r
            len = props.length,\r
            i = 0,\r
            prop;\r
            \r
        for (; i < len; ++i) {\r
            prop = props[i];\r
            cfg[prop] = this[prop];\r
        }\r
        return new Ext.form.Basic(this, cfg);\r
    },\r
\r
    /**\r
     * Provides access to the {@link Ext.form.Basic Form} which this Panel contains.\r
     * @return {Ext.form.Basic} The {@link Ext.form.Basic Form} which this Panel contains.\r
     */\r
    getForm: function() {\r
        return this.form;\r
    },\r
\r
    /**\r
     * Loads an {@link Ext.data.Model} into this form (internally just calls {@link Ext.form.Basic#loadRecord})\r
     * See also {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad}. The fields in the model are mapped to \r
     * fields in the form by matching either the {@link Ext.form.field.Base#name} or {@link Ext.Component#itemId}.  \r
     * @param {Ext.data.Model} record The record to load\r
     * @return {Ext.form.Basic} The Ext.form.Basic attached to this FormPanel\r
     */\r
    loadRecord: function(record) {\r
        return this.getForm().loadRecord(record);\r
    },\r
\r
    /**\r
     * Returns the currently loaded Ext.data.Model instance if one was loaded via {@link #loadRecord}.\r
     * @return {Ext.data.Model} The loaded instance\r
     */\r
    getRecord: function() {\r
        return this.getForm().getRecord();\r
    },\r
    \r
    /**\r
     * Persists the values in this form into the passed {@link Ext.data.Model} object in a beginEdit/endEdit block.\r
     * If the record is not specified, it will attempt to update (if it exists) the record provided to {@link #loadRecord}.\r
     * @param {Ext.data.Model} [record] The record to edit\r
     * @return {Ext.form.Basic} The Ext.form.Basic attached to this FormPanel\r
     */\r
    updateRecord: function(record) {\r
        return this.getForm().updateRecord(record);\r
    },\r
\r
    /**\r
     * Convenience function for fetching the current value of each field in the form. This is the same as calling\r
     * {@link Ext.form.Basic#getValues this.getForm().getValues()}.\r
     *\r
     * @inheritdoc Ext.form.Basic#getValues\r
     */\r
    getValues: function(asString, dirtyOnly, includeEmptyText, useDataValues) {\r
        return this.getForm().getValues(asString, dirtyOnly, includeEmptyText, useDataValues);\r
    },\r
    \r
    /**\r
     * Convenience function to check if the form has any dirty fields. This is the same as calling\r
     * {@link Ext.form.Basic#isDirty this.getForm().isDirty()}.\r
     *\r
     * @inheritdoc Ext.form.Basic#isDirty\r
     */\r
    isDirty: function () {\r
        return this.form.isDirty();\r
    },\r
    \r
    /**\r
     * Convenience function to check if the form has all valid fields. This is the same as calling\r
     * {@link Ext.form.Basic#isValid this.getForm().isValid()}.\r
     *\r
     * @inheritdoc Ext.form.Basic#isValid\r
     */\r
    isValid: function () {\r
       return this.form.isValid();\r
    },\r
\r
    /**\r
     * Convenience function reset the form. This is the same as calling\r
     * {@link Ext.form.Basic#reset this.getForm().reset()}.\r
     *\r
     * @inheritdoc Ext.form.Basic#reset\r
     */\r
    reset: function() {\r
        this.form.reset();\r
    },\r
    \r
    /**\r
     * Convenience function to check if the form has any invalid fields. This is the same as calling\r
     * {@link Ext.form.Basic#hasInvalidField this.getForm().hasInvalidField()}.\r
     *\r
     * @inheritdoc Ext.form.Basic#hasInvalidField\r
     */\r
    hasInvalidField: function () {\r
        return this.form.hasInvalidField();\r
    },\r
\r
    beforeDestroy: function() {\r
        this.stopPolling();\r
        this.form.destroy();\r
        this.callParent();\r
    },\r
\r
    /**\r
     * This is a proxy for the underlying BasicForm's {@link Ext.form.Basic#load} call.\r
     * @param {Object} options The options to pass to the action (see {@link Ext.form.Basic#load} and\r
     * {@link Ext.form.Basic#doAction} for details)\r
     */\r
    load: function(options) {\r
        this.form.load(options);\r
    },\r
\r
    /**\r
     * This is a proxy for the underlying BasicForm's {@link Ext.form.Basic#submit} call.\r
     * @param {Object} options The options to pass to the action (see {@link Ext.form.Basic#submit} and\r
     * {@link Ext.form.Basic#doAction} for details)\r
     */\r
    submit: function(options) {\r
        this.form.submit(options);\r
    },\r
\r
    /**\r
     * Start an interval task to continuously poll all the fields in the form for changes in their\r
     * values. This is normally started automatically by setting the {@link #pollForChanges} config.\r
     * @param {Number} interval The interval in milliseconds at which the check should run.\r
     */\r
    startPolling: function(interval) {\r
        this.stopPolling();\r
        var task = new Ext.util.TaskRunner(interval);\r
        task.start({\r
            interval: 0,\r
            run: this.checkChange,\r
            scope: this\r
        });\r
        this.pollTask = task;\r
    },\r
\r
    /**\r
     * Stop a running interval task that was started by {@link #startPolling}.\r
     */\r
    stopPolling: function() {\r
        var task = this.pollTask;\r
        if (task) {\r
            task.stopAll();\r
            delete this.pollTask;\r
        }\r
    },\r
\r
    /**\r
     * Forces each field within the form panel to\r
     * {@link Ext.form.field.Field#checkChange check if its value has changed}.\r
     */\r
    checkChange: function() {\r
        var fields = this.form.getFields().items,\r
            f,\r
            fLen   = fields.length;\r
\r
        for (f = 0; f < fLen; f++) {\r
            fields[f].checkChange();\r
        }\r
    }\r
});\r