Forms

Forms on websites are critical and often the main piece of user interactivity, so forms in SocialStack are intended to be as flexible as possible, without reinventing too much.

The <Form> React component is a very thin wrapper over <form> in order to add some common conveniences, such as using the submitForm function instead of the default browser page load form submit.

Form example

import Form from 'UI/Form';
import Input from 'UI/Input';

...

<Form action="user" submitLabel="Create a user" successMessage="User created!" failureMessage="Unable to create a user now">
        <Input type="text" name="email" label="Email Address" validate={["Required"]} />
        <Input type="password" name="password" label="Email Address" />
</Form>

Props

This is the main available props for the <Form> react component.

Name	About	Required?	Default value
onValues	This callback function can be used to manipulate what is actually sent to the server. It is given the complete set of field values, and you must return the values that you would like to submit, or a promise which resolves to that. Typically this is just by returning the object you were given, after adding/ changing fields on it.	No	none
successMessage	A JSX supporting message which will appear in a success alert when a 200 response is received. A common convenience piece.	No	none
failureMessage	A JSX supporting message which will appear in an error alert when a non 2xx response is received. A common convenience piece.	No	none
action	The URL where the form will be submitted. By default this is API relative, meaning action="user" is going to POST to /v1/user	Yes	none
submitLabel	If specified, an <Input type='submit' /> will be added at the end of the form with the given text on it. Also a common convenience.	No	none
onSuccess	A callback which runs with the response, typically from the API.	No	none
onFailed	A callback which runs with a failure message. This is often from the API, but can be client generated when the failure is down to the a timeout.	No	none

Submitting a form

There are two ways of submitting a form. Either:

• Add any <input type='submit' /> button inside your form
• Obtain a reference to the dom <form> element and call .submit(); on it

How form submit works

• Whenever a form is submitted via any method, submitForm is called.
• All the <input> fields inside the form are collected.
• If the input DOM element has an onValidationCheck function on it, it will be called. Note that this is where <Input> checks itself. This function should return true if the validation failed.
• If the input DOM element has an onGetValue function on it, that function will be called and whatever it returns will be used as the value to submit. onGetValue is very useful if you have a custom input type which needs to map its internal state into some value ready to submit in the form.
• If there were any validation errors, the submit halts and onFailed runs.
• Otherwise, onValues is given the complete set of all values collected. If onValues returned a promise, it is awaited before the values are then submitted via a webRequest.