source: Dev/trunk/src/client/dijit/form/Form.js

define([
        "dojo/_base/declare", // declare
        "dojo/dom-attr", // domAttr.set
        "dojo/_base/kernel", // kernel.deprecated
        "dojo/sniff", // has("ie")
        "../_Widget",
        "../_TemplatedMixin",
        "./_FormMixin",
        "../layout/_ContentPaneResizeMixin"
], function(declare, domAttr, kernel, has, _Widget, _TemplatedMixin, _FormMixin, _ContentPaneResizeMixin){

        // module:
        //              dijit/form/Form


        return declare("dijit.form.Form", [_Widget, _TemplatedMixin, _FormMixin, _ContentPaneResizeMixin], {
                // summary:
                //              Widget corresponding to HTML form tag, for validation and serialization
                //
                // example:
                //      |       <form data-dojo-type="dijit/form/Form" id="myForm">
                //      |               Name: <input type="text" name="name" />
                //      |       </form>
                //      |       myObj = {name: "John Doe"};
                //      |       dijit.byId('myForm').set('value', myObj);
                //      |
                //      |       myObj=dijit.byId('myForm').get('value');

                // HTML <FORM> attributes

                // name: String?
                //              Name of form for scripting.
                name: "",

                // action: String?
                //              Server-side form handler.
                action: "",

                // method: String?
                //              HTTP method used to submit the form, either "GET" or "POST".
                method: "",

                // encType: String?
                //              Encoding type for the form, ex: application/x-www-form-urlencoded.
                encType: "",

                // accept-charset: String?
                //              List of supported charsets.
                "accept-charset": "",

                // accept: String?
                //              List of MIME types for file upload.
                accept: "",

                // target: String?
                //              Target frame for the document to be opened in.
                target: "",

                templateString: "<form data-dojo-attach-point='containerNode' data-dojo-attach-event='onreset:_onReset,onsubmit:_onSubmit' ${!nameAttrSetting}></form>",

                postMixInProperties: function(){
                        // Setup name=foo string to be referenced from the template (but only if a name has been specified)
                        // Unfortunately we can't use _setNameAttr to set the name due to IE limitations, see #8660
                        this.nameAttrSetting = this.name ? ("name='" + this.name + "'") : "";
                        this.inherited(arguments);
                },

                execute: function(/*Object*/ /*===== formContents =====*/){
                        // summary:
                        //              Deprecated: use submit()
                        // tags:
                        //              deprecated
                },

                onExecute: function(){
                        // summary:
                        //              Deprecated: use onSubmit()
                        // tags:
                        //              deprecated
                },

                _setEncTypeAttr: function(/*String*/ value){
                        domAttr.set(this.domNode, "encType", value);
                        if(has("ie")){
                                this.domNode.encoding = value;
                        }
                        this._set("encType", value);
                },

                reset: function(/*Event?*/ e){
                        // summary:
                        //              restores all widget values back to their init values,
                        //              calls onReset() which can cancel the reset by returning false

                        // create fake event so we can know if preventDefault() is called
                        var faux = {
                                returnValue: true, // the IE way
                                preventDefault: function(){ // not IE
                                        this.returnValue = false;
                                },
                                stopPropagation: function(){
                                },
                                currentTarget: e ? e.target : this.domNode,
                                target: e ? e.target : this.domNode
                        };
                        // if return value is not exactly false, and haven't called preventDefault(), then reset
                        if(!(this.onReset(faux) === false) && faux.returnValue){
                                this.inherited(arguments, []);
                        }
                },

                onReset: function(/*Event?*/ /*===== e =====*/){
                        // summary:
                        //              Callback when user resets the form. This method is intended
                        //              to be over-ridden. When the `reset` method is called
                        //              programmatically, the return value from `onReset` is used
                        //              to compute whether or not resetting should proceed
                        // tags:
                        //              callback
                        return true; // Boolean
                },

                _onReset: function(e){
                        this.reset(e);
                        e.stopPropagation();
                        e.preventDefault();
                        return false;
                },

                _onSubmit: function(e){
                        var fp = this.constructor.prototype;
                        // TODO: remove this if statement beginning with 2.0
                        if(this.execute != fp.execute || this.onExecute != fp.onExecute){
                                kernel.deprecated("dijit.form.Form:execute()/onExecute() are deprecated. Use onSubmit() instead.", "", "2.0");
                                this.onExecute();
                                this.execute(this.getValues());
                        }
                        if(this.onSubmit(e) === false){ // only exactly false stops submit
                                e.stopPropagation();
                                e.preventDefault();
                        }
                },

                onSubmit: function(/*Event?*/ /*===== e =====*/){
                        // summary:
                        //              Callback when user submits the form.
                        // description:
                        //              This method is intended to be over-ridden, but by default it checks and
                        //              returns the validity of form elements. When the `submit`
                        //              method is called programmatically, the return value from
                        //              `onSubmit` is used to compute whether or not submission
                        //              should proceed
                        // tags:
                        //              extension

                        return this.isValid(); // Boolean
                },

                submit: function(){
                        // summary:
                        //              programmatically submit form if and only if the `onSubmit` returns true
                        if(!(this.onSubmit() === false)){
                                this.containerNode.submit();
                        }
                }
        });
});