You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/docs/getting-started/getting-started.md
+45-14
Original file line number
Diff line number
Diff line change
@@ -9,10 +9,12 @@ import CodeBlock from '@theme/CodeBlock'
9
9
import HandlingChangesSource from '!!raw-loader!./SignUpForm_HandlingChanges.res'
10
10
import MarkupSource from '!!raw-loader!./SignUpForm_Markup.res'
11
11
import FormHookSource from '!!raw-loader!./SignUpForm_FormHook.res'
12
+
import SubmitSource from '!!raw-loader!./SignUpForm_Submit.res'
12
13
// Preview
13
14
import { make as HandlingChangesPreview } from './SignUpForm_HandlingChanges.bs.js'
14
15
import { make as MarkupPreview } from './SignUpForm_Markup.bs.js'
15
16
import { make as FormHookPreview } from './SignUpForm_FormHook.bs.js'
17
+
import { make as SubmitPreview } from './SignUpForm_Submit.bs.js'
16
18
import { Preview } from '../__components'
17
19
18
20
After setting up `reform`, `reschema`, and `lenses-ppx` in the [previous section](/docs/installation), you're ready to create your first form. You can understand every
@@ -37,13 +39,13 @@ module FormFields = %lenses(
37
39
The name of the record passed to `lenses-ppx` must be named as `state`.
38
40
:::
39
41
40
-
You might be asking yourself: _"what this lenses-ppx is doing?"_ and it's kinda of magic, but it's a way to create "getters" and "setters" for the `state` record.
42
+
You might be asking yourself: _"what this lenses-ppx is doing?"_ and it's kind of magic, but it's a way to create "getters" and "setters" for the `state` record.
41
43
42
44
After that, we have to create a new form using the `ReForm.Make` module functor.
43
45
The module functor expects a lenses module which was created by
44
46
`lenses-ppx` and returns a new form module. You can see the API reference of this module [here](/docs/reform-make).
45
47
46
-
```reason title="SignUpForm.res"
48
+
```reason{9} title="SignUpForm.res"
47
49
module FormFields = %lenses(
48
50
type state = {
49
51
name: string,
@@ -61,41 +63,70 @@ You can read more about module functors [here](https://rescript-lang.org/docs/ma
61
63
### The `Form.use` hook
62
64
ReForm provides a form hook and we're going to use it by passing some parameters like `schema`, an `onSubmit` function, `initialState`, etc.
-1. The `Form.use` hook calling: This is the hook provided by reform. It returns a `form` object that's typed as `Form.api` and you can read more about its api _here_.
69
+
-1. The `Form.use` hook calling: This is the hook provided by reform. It returns a `form` object that is typed as `Form.api` and you can read more about its api _here_.
68
70
-2. The `onSubmit` parameter: Just a function that will be called when you trigger the `form.submit` function.
69
71
-3. The `validationStrategy`: We're telling to reform which strategy of validation we want to use, in this case, we're using `OnDemand` which means that we'll trigger the validation **manually** using the `form` object.
70
-
-4. The `schema` parameter: It's a schema created using [ReSchema](https://github.com/rescriptbr/reschema). You can read more about the usage of _reschema with reform_ and its _official documentation_.
72
+
-4. The `schema` parameter: It's a schema created using [ReSchema](https://github.com/rescriptbr/reschema). You can read more about the usage of _reschema with reform_ and in its _official documentation_.
71
73
72
74
### Creating our form component
73
75
We need a form to make everything works, so we're going to use a combination of inputs and button to create a simple sign up form:
74
76
:::important
75
-
For this tutorial, we created some local components (like `Input`, `Button`, `Input.Error`) just to make the markup more readable, but with the same API of native input and button (`onChange`, `value`, `onClick`, etc). Another components like `Box` or `Typography` are from [Ancestor](https://github.com/rescriptbr/reform) which is
77
+
For this tutorial, we created some local components (like `Input`, `Button`, `Input.Error`) just to make the markup more readable, but with the same API of native (`onChange`, `value`, `onClick`, etc). Another components like `Box` or `Typography` are from [Ancestor](https://github.com/rescriptbr/reform) which is
76
78
an UI library and is totally optional for this tutorial. Feel free to use pure html with or without css to create your own form.
We created the `Form` module by combining `lenses-ppx`, `reform` and `reschema` and we also have a simple form component. Now, it's time to put everything to
86
-
work together.
87
88
88
-
Different from libraries like [react-hook-form](https://react-hook-form.com/), ReForm doesn't use any kinda of magic with refs.
89
+
We created the `Form` module by combining `lenses-ppx`, `reform` and `reschema` and we also have a simple form component. Now, it's time to make everything working together.
90
+
91
+
Different from libraries like [react-hook-form](https://react-hook-form.com/), ReForm doesn't use any kind of magic with refs.
89
92
ReForm was created to be both deadly simple and to make forms sound good, leveraging ReScript's powerful typesytem.
90
93
Even the schemas we use are nothing more than constructors built-in in the language itself.
91
94
92
95
We encourage you to handle every change in your inputs manually. Not just the changes, but also the conversion of values, like string to int or string to float.
93
-
Could be more verbosive to do everything manually, but it's intentional and keep you in control of everything that happens with your forms.
96
+
Might be more verbosive to do everything manually, but it's intentional and keep you in control of everything that happens with your forms.
94
97
95
-
The `form` record returned by reform has some fields like `handleChange` and `values` that we're going to use to make everything work.
96
-
We're going to start by handling tha changes on the inputs:
98
+
The `form` record returned by reform has some fields like `handleChange` and `values` that we're going to use to integrate the form module with our form component.
99
+
We're going to start by handling the changes on the inputs:
Also, we've added a simple block to display the form values. If you type something in any input, you can see the values changing:
99
104
<Preview>
100
105
<HandlingChangesPreview />
101
106
</Preview>
107
+
108
+
But, we can just type and see the values, if you click on the submit button, nothing happens, no error messages, no console.log, etc.
109
+
To make everything works, we still have to do two things: trigger the `form.submit` function and render the validation errors (when we got an error) using then`form.getFieldError` function:
Now, when we click on the submit button without fill the form (or filling with invalid values), we can see the error message for each field.
114
+
Also, if we open the browser console and fill all fields correctly, we can see the result of the form submission on the console.
115
+
116
+
<Preview>
117
+
<SubmitPreview />
118
+
</Preview>
119
+
120
+
<br/>
121
+
122
+
123
+
### Disclaimers
124
+
125
+
There are some disclaimers about this part of the tutorial:
126
+
127
+
- The first one, is about the handling of our `handleSubmit` function. If you click on the submit button without filling the fields, the function
128
+
will not be triggered. That's the expected behavior. The `onSubmit` function will be triggered when the form is valid. If you need to handle
129
+
a function on the submit and there are invalid fields, you can use the `onSubmitFail` parameter. You can read more about this **here**.
130
+
- Because we're passing `OnDemand` to the `validationStrategy` parameter, we have to call the form validation **manually** using a function like `form.validateForm` or just call
131
+
call the `form.submit` function (like we did) that triggers the form validation automatically. If you need to trigger the validation on every change, you can use `OnChange` as a validation strategy.
132
+
You can read more about validation strategies **here**.
0 commit comments