The Form component
Instead of the standard JSX <form> element, use the Form component, imported from Tenon.UI.
This component employs a children render prop to render the form view:
Every Form requires a render function supplied as children of the component. An onSubmit handler is also required.
The Form component automatically manages all the child form element components (see below) and will pass all the required data into the render function.
Form props
children
This prop is required.
A render function accepting three paramaters:
formControls
A full summary object of all form controls on the page. This object is always up to date with the latest values from the form controls.
The structure of this object is:
validity
A boolean value indicating the combined validity values for each form control. For Forms where all the controls pass validation the value will be true, if at least one control fails validation the value will be false.
This flag can be used to trigger global error blocks, for example.
hasSubmitted
A boolean value indicating if the user has triggered an onSubmit event at least once.
This can also be used to display information, such as error blocks, only after the user has attempted to submit the Form.
onSubmit
This prop is required.
An event handler function that is called if a submit event occurs and all form controls passes validation.
NOTE: This event is NOT called on a submit event if any of the form controls fails validation. Please see onRawSubmit below if you need this functionality.
If the Form is valid, the event handler is called with a submitData object containing the current, valid values for each control on the Form, by control name:
onRawSubmit
An optional event handler that gets triggered by every submit action on the Form, regardless of the validity state of the Form.
This event handler gets called with a formControls and validity parameter that has the same shape and function of those injected into the view by the Form's children render prop.
This function can, for example, be used to set focus on a summary error block.
formData
An object used to pass data into the smart form, for instance when loading already saved data from the server.
This object shape mirrors that of the submitData object passed into the onSubmit handler.
Note: This object does NOT get mutated by the form. It is simply there to pass data into the form. Every time this object is changed it will overwrite the form data. If the form data is changed via user interaction, these changes will NOT be reflected in this prop.
alwaysShowErrors
By default, the smart form control are built to only display validation error conditions once a submit has been attempted. As this is the user experience we recommend.
Should the need arise to immediately show errors real-time, this boolean flag can be set to true.
className
Allows setting a className on the actual rendered <form> element.