Adding event as second argument to Form onSubmit + documentation and unit tests. Fixes #664

Author: davidkpiano

docs/api/Form.md

@@ -95,9 +95,11 @@ _(Function)_: The handler function called when the form is submitted. This works
 
 - The submit event's default action is prevented by default, using `event.preventDefault()`.
 - The `onSubmit` handler _will not execute_ if the form is invalid.
-- The `onSubmit` handler receives the form model data, not the event.
+- The `onSubmit` handler receives the form model data as the first argument, and the event as the second argument.
 
-The function passed into `onSubmit={...}` will be called with one argument: the form's model value.
+The function passed into `onSubmit={...}` will be called with two arguments:
+1. the form's model value
+2. the native submit event (if applicable).
 
 ### Example
 ```jsx

docs/guides/faqs.md

@@ -118,5 +118,41 @@ For single or multiple checkboxes that represent boolean keyed values in a model
 <Control.checkbox model="user.pets.goat" />
 ```
 
+### How do I create a file upload form?
+The second argument of the `<Form onSubmit={(values, event) => ...}>` prop provides the event emitted when the form was submitted. Adapted from the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/FormData/Using_FormData_Objects):
+
+```jsx
+class UploadForm extends Component {
+  onSubmit = (values, event) => {
+    const formData = new FormData(event.target);
+
+    const request = new XMLHttpRequest();
+    request.open('POST', '/upload', true);
+    request.onload = function(oEvent) {
+      if (request.status == 200) {
+        console.log('Uploaded!');
+      } else {
+        console.log('Error uploading.');
+      }
+    };
+
+    request.send(formData);
+    event.preventDefault();
+  }
+  render() {
+    return (
+      <Form
+        model="user"
+        encType="multipart/form-data"
+        onSubmit={this.onSubmit}
+      >
+        <Control.file model=".avatar" />
+        <button>Upload!</button>
+      </Form>
+    );
+  };
+}
+```
+
 ### Other Questions and Answers
 - https://github.com/davidkpiano/react-redux-form/issues/675#issuecomment-281164930

src/components/form-component.js

@@ -71,6 +71,10 @@ function createFormClass(s = defaultStrategy) {
       this.handleValidSubmit = this.handleValidSubmit.bind(this);
       this.handleInvalidSubmit = this.handleInvalidSubmit.bind(this);
       this.attachNode = this.attachNode.bind(this);
+
+      this.state = {
+        lastSubmitEvent: null,
+      };
     }
 
     getChildContext() {
@@ -279,7 +283,7 @@ function createFormClass(s = defaultStrategy) {
 
       dispatch(s.actions.setPending(model, true, options));
 
-      if (onSubmit) onSubmit(modelValue);
+      if (onSubmit) onSubmit(modelValue, this.state.lastSubmitEvent);
     }
 
     handleInvalidSubmit(options) {
@@ -323,6 +327,7 @@ function createFormClass(s = defaultStrategy) {
 
     handleSubmit(e) {
       if (e && !this.props.action) e.preventDefault();
+      if (e && e.persist) e.persist();
 
       const {
         modelValue,
@@ -339,11 +344,13 @@ function createFormClass(s = defaultStrategy) {
         : true;
 
       if (!validators && onSubmit && formValid) {
-        onSubmit(modelValue);
+        onSubmit(modelValue, e);
 
         return modelValue;
       }
 
+      this.setState({ lastSubmitEvent: e });
+
       this.validate(this.props, false, true);
 
       return modelValue;

test/form-component-spec.js

@@ -782,6 +782,7 @@ Object.keys(testContexts).forEach((testKey) => {
       });
 
       let submitValue = null;
+      let submitEventValue = null;
 
       const form = TestUtils.renderIntoDocument(
         <Provider store={store}>
@@ -796,8 +797,9 @@ Object.keys(testContexts).forEach((testKey) => {
             errors={{
               bar: (val) => val !== 'bar' && 'bar invalid',
             }}
-            onSubmit={(val) => {
+            onSubmit={(val, event) => {
               submitValue = val;
+              submitEventValue = event;
               return true;
             }}
           >
@@ -834,6 +836,7 @@ Object.keys(testContexts).forEach((testKey) => {
           store.getState().testForm.foo.valid);
 
         assert.isNull(submitValue);
+        assert.isNull(submitEventValue);
       });
 
       it('should set submitFailed to true if form is invalid and submitted', () => {
@@ -842,7 +845,7 @@ Object.keys(testContexts).forEach((testKey) => {
         assert.isTrue(store.getState().testForm.$form.submitFailed);
       });
 
-      it('should call onSubmit with model value if form is valid', () => {
+      it('should call onSubmit with model value and event if form is valid', () => {
         barControl.value = 'bar';
 
         TestUtils.Simulate.change(barControl);
@@ -873,6 +876,9 @@ Object.keys(testContexts).forEach((testKey) => {
             baz: 'valid',
             foo: 'valid',
           });
+
+        assert.instanceOf(submitEventValue.target, window.HTMLElement,
+          'second argument should be event with a target');
       });
     });