@digigov/form 0.8.3 → 0.8.5-alpha

package/es/create-simple-form.mdx

@@ -0,0 +1,515 @@
+---
+id: create-simple-form
+title: Create a simple Digigov Form
+sidebar_label: Creating simple forms
+---
+
+import LeadText from "@site/src/components/LeadText";
+
+<LeadText>This guide walks through building a simple form page, complete with
+validation and data serialisation.</LeadText>
+
+## What we are building
+
+Before we start diving into more advanced usecases, let's first create a form
+asking users for their personal information.
+
+* First name
+* Last name
+* AFM (Greek tax number)
+* Telephone number
+* Marital status
+
+As you can see, this form is pretty basic. But even for a basic form like this
+we want to implement features that will help our users submit their data. We
+should add basic input validations and get any data from those inputs, assuming
+that these validation checks passed. These features are not rocket science, but
+even though they are used all the time, there is a lot of boilerplate code that
+can be abstracted away.
+
+Let's see how Digigov Form helps us build forms in no time.
+
+## Create your first form component
+
+Let's start by creating a form in plain HTML. In this example, the first element
+we use is a `<form>` followed by `<label>` and `<input>` elements. These are
+primitive elements.
+
+```jsx
+import React from 'react';
+
+export default function SimpleForm() {
+  return <form>
+    <label>
+      Name:
+      <input type="text" name="name" />
+    </label>
+    <input type="submit" value="Submit" />
+  </form>
+}
+```
+
+In Digigov Form, we use the same primitive elements under the hood but we add a
+lot of built-in functionality. Let's take a quick look on how we can transform
+the same form using Digigov Form.
+
+The default export of `@digigov/form` package is a React component that can be
+used for wrapping Field components. The component is the same as
+`@digigov/form/FormBuilder` and it can be used in two distinct ways. We will
+talk about that in a more advanced guide.
+
+```jsx
+import React from 'react';
+// highlight-next-line
+import Form from '@digigov/form';
+
+export default function SimpleForm() {
+  // highlight-start
+  return <Form>
+    {/* this is where the fields are going to be placed */}
+  </Form>
+  // highlight-end
+}
+```
+
+## Adding the first field
+
+In this state, the form is just an empty shell waiting for us to define its
+fields. According to our initial requirements set in the beginning of this
+guide, we should create a new field with label ‘First name‘.
+
+Let's go ahead and import the `Field` component and use it to render an input
+field and a label. This component creates and manages any necessary React
+components transparently. All you need to do is describe a few React props.
+
+* `key`
+* `name`
+* `type`
+* `label`
+* `required`
+
+These props can be then passed down the `Field` component which will be rendered
+by `FormBuilder`.
+
+Take a look at this live example. You can also use the live editor to play
+around with the example code.
+
+```jsx
+import React from 'react';
+// highlight-next-line
+import Form, { Field } from '@digigov/form';
+
+export default function SimpleForm() {
+  return <Form>
+    // highlight-start
+    <Field
+      key="firstName"
+      name="firstName"
+      label={{ primary: "First name" }}
+      type="string"
+      required
+    />
+    // highlight-end
+  </Form>
+}
+```
+
+Hooray! 🎉 
+
+It looks like the first two fields of our awesome form are working as
+expected. They are pretty basic, string inputs, accepting data input but they
+don't seem to submit data or do any validation in their current state.
+
+```jsx live
+import React from 'react';
+import Form, { Field } from '@digigov/form';
+
+export default function SimpleForm() {
+  return <Form>
+    <Field
+      key="firstName"
+      name="firstName"
+      label={{ primary: "First name" }}
+      type="string"
+      required
+    />
+    <Field
+      key="lastName"
+      name="lastName"
+      label={{ primary: "Last name" }}
+      type="string"
+      required
+    />
+  </Form>
+}
+```
+
+## Adding a submit button
+
+Before we proceed with adding the rest of the fields, we should first make sure
+that the form is working, validating and submitting data.
+
+Let's modify the previous example and use a `@digigov/ui/form/Button` to submit
+data. First we should import the button component  and use it right at the
+bottom of our form.
+
+It is important to note that you should make sure the Button has a
+`type="submit"` prop. In any other case, the button will not exhibit the correct
+behaviour when users try to submit data using their keyboard (eg. hitting the
+enter key) or using any other tools eg. screen readers.
+
+```jsx
+import React from 'react';
+import Form, { Field } from '@digigov/form';
+// highlight-next-line
+import Button from '@digigov/ui/core/Button';
+
+export default function SimpleForm() {
+  return <Form>
+    {/* this is where the fields are going to be placed */}
+    <Field
+      key="firstName"
+      name="firstName"
+      label={{ primary: "First name" }}
+      type="string"
+      required
+    />
+    <Field
+      key="lastName"
+      name="lastName"
+      label={{ primary: "Last name" }}
+      type="string"
+      required
+    />
+    // highlight-next-line
+    <Button type="submit">Continue</Button>
+  </Form>
+}
+```
+
+The code now looks fine. You can go ahead and test that the fields are
+validating as we have instructed them. The form should display red errors when
+you try to submit it with empty values.
+
+Go ahead and try it in the live example below. You can also remove the
+`required` prop from one of the fields in the live editor, and see how that
+affects the submit behaviour.
+
+```jsx live
+import React from 'react';
+import Form, { Field } from '@digigov/form';
+import Button from '@digigov/ui/core/Button';
+
+export default function SimpleForm() {
+  return <Form>
+    {/* this is where the fields are going to be placed */}
+    <Field
+      key="firstName"
+      name="firstName"
+      label={{ primary: "First name" }}
+      type="string"
+      required
+    />
+    <Field
+      key="lastName"
+      name="lastName"
+      label={{ primary: "Last name" }}
+      type="string"
+      required
+    />
+    <Button type="submit">Continue</Button>
+  </Form>
+}
+```
+
+Straightaway, the form is actually doing something and it is validating our
+inputs with almost zero coding needed.
+ 
+That's good. But we have yet to gather data in our code when users submit the form.
+
+## Handling onSubmit events
+
+Naturally, when we get data from HTML forms, we make use of the `submit` events
+that are bubbling up. In React, we follow the convention of naming event
+handlers like `onChange` and `onSubmit`.
+
+We use the same familiar pattern as many other libraries. We get data inside an
+event handler function and we can render this information in our application or
+choose to send it to a remote server via an API.
+
+In our case, we need a quick and dirty way to display the actual values we have
+just entered to a form right back to us and render them for debugging purposes.
+
+We will use the `useState` hook inside our functional component. This will let
+us react to a `submit` event and locally save the form data as key-value pairs
+in our state. Then we can call `JSON.stringify` and render the raw JSON
+information.
+
+```jsx
+// highlight-next-line
+import React, { useState } from 'react';
+import Form, { Field } from '@digigov/form';
+import Button from '@digigov/ui/core/Button';
+
+export default function SimpleForm() {
+  // highlight-start
+  const [submittedData, setSubmittedData] = useState({})
+  const handleSubmit = (data) => {
+    setSubmittedData(data);
+  }
+  return <>
+    <Form onSubmit={handleSubmit}>
+  // highlight-end
+      {/* this is where the fields are going to be placed */}
+      <Field
+        key="firstName"
+        name="firstName"
+        label={{ primary: "First name" }}
+        type="string"
+        required
+      />
+      <Field
+        key="lastName"
+        name="lastName"
+        label={{ primary: "Last name" }}
+        type="string"
+        required
+      />
+      <Button type="submit">Continue</Button>
+    </Form>
+    // highlight-start
+    {<>
+      You submitted the following values
+      <pre><code>
+        {JSON.stringify(submittedData)}
+      </code></pre>
+    </>}
+    // highlight-end
+  </>
+}
+```
+
+As you can see in the live example when the form first loads, the submitted data
+is an empty object, which is actually the default value we have given the
+`useState` hook when we declare it.
+
+Go ahead and fill the inputs with your first and last name. Then click the
+button or press enter and see what happens.
+
+```jsx live
+import React, { useState } from 'react';
+import Form, { Field } from '@digigov/form';
+import Button from '@digigov/ui/core/Button';
+import Paragraph from '@digigov/ui/typography/Paragraph';
+
+export default function SimpleForm() {
+  const [submittedData, setSubmittedData] = useState({})
+  const handleSubmit = (data) => {
+    setSubmittedData(data);
+  }
+  return <>
+    <Form onSubmit={handleSubmit}>
+      {/* this is where the fields are going to be placed */}
+      <Field
+        key="firstName"
+        name="firstName"
+        label={{ primary: "First name" }}
+        type="string"
+        required
+      />
+      <Field
+        key="lastName"
+        name="lastName"
+        label={{ primary: "Last name" }}
+        type="string"
+        required
+      />
+      <Button type="submit">Continue</Button>
+    </Form>
+    {<Paragraph>
+      You have submitted the following values
+      <pre><code>
+        {JSON.stringify(submittedData)}
+      </code></pre>
+    </Paragraph>}
+  </>
+}
+```
+
+That's great, now we have a form that's actually interactive in some way. The
+inputs are validating data entered and it kindly provides us the submitted data.
+
+We're so close to achieve our original goal of a simple working form.
+
+## Adding miscellaneous fields
+
+It is time to expand our little form and make it render a few more advanced
+fields. We want to get the AFM number, which is used by Greek tax authorities
+and a telephone number. Both of these need custom validations that ensure the
+correct format for user input. Also, we want to get the marital status of our
+users.
+
+### AFM & Phone number with validation
+
+For these two fields, we can follow exactly the same pattern we have used for
+`firstName` and `lastName` before.
+
+In the case of the AFM, the `type` prop will have a value of `afm`. This prop
+will apply the appropriate validation in the Field.
+
+Also, please note the use of the `secondary` value in the `label` prop. It is
+used to provide explanation for each field. We can use it to inform users about
+the format of this tax number
+
+```jsx
+<Field
+  key="taxNumber"
+  name="taxNumber"
+  type="afm"
+  label={{
+    primary: "Tax number",
+    secondary: "Tax number is your AFM number, given to you by AADE"
+  }}
+  required
+/>
+```
+
+A similar field can be used for the phone number. You can use the
+`type="phone_number"` to validate this field.
+
+```jsx
+<Field
+  key="phoneNumber"
+  name="phoneNumber"
+  type="phone_number"
+  label={{
+    primary: "Phone number",
+    secondary: "You can enter any landline phone number."
+  }}
+  required
+/>
+```
+
+### Marital status as a radio group
+
+Last but not least, we should create a single choice field, which will be
+rendered as a radio group of answers.
+
+
+```jsx
+<Field
+  key="maritalStatus"
+  name="maritalStatus"
+  type="choice:single"
+  label={{primary: "Marital status"}}
+  required
+  extra={{
+    options: [
+      {
+        label: {primary: "Married"},
+        value: 'married',
+      },
+      {
+        label: {primary: "Cohabitation agreement"},
+        value: 'cohabitation',
+      },
+      {
+        label: {primary: "Prefer not to answer"},
+        value: 'wontanswer',
+      }
+    ]
+  }}
+/>
+```
+
+## Final form
+
+Finally, we have the code almost ready. Let's put it all together by adding the
+few last fields right above the submit button.
+
+Feel free to fill the form in the example and submit it.
+
+```jsx live
+import React, { useState } from 'react';
+import Form, { Field } from '@digigov/form';
+import Button from '@digigov/ui/core/Button';
+import Paragraph from '@digigov/ui/typography/Paragraph';
+
+export default function SimpleForm() {
+  const [submittedData, setSubmittedData] = useState({})
+  const handleSubmit = (data) => {
+    setSubmittedData(data);
+  }
+  return <>
+    <Form onSubmit={handleSubmit}>
+      {/* this is where the fields are going to be placed */}
+      <Field
+        key="firstName"
+        name="firstName"
+        label={{ primary: "First name" }}
+        type="string"
+        required
+      />
+      <Field
+        key="lastName"
+        name="lastName"
+        label={{ primary: "Last name" }}
+        type="string"
+        required
+      />
+      <Field
+        key="taxNumber"
+        name="taxNumber"
+        type="afm"
+        label={{
+          primary: "Tax number",
+          secondary: "Tax number is your AFM number, given to you by AADE"
+        }}
+        required
+      />
+      <Field
+        key="phoneNumber"
+        name="phoneNumber"
+        type="phone_number"
+        label={{
+          primary: "Phone number",
+          secondary: "You can enter any landline phone number."
+        }}
+        required
+      />
+      <Field
+        key="maritalStatus"
+        name="maritalStatus"
+        type="choice:single"
+        label={{primary: "Marital status"}}
+        required
+        extra={{
+          options: [
+            {
+              label: {primary: "Married"},
+              value: 'married',
+            },
+            {
+              label: {primary: "Cohabitation agreement"},
+              value: 'cohabitation',
+            },
+            {
+              label: {primary: "Prefer not to answer"},
+              value: 'wontanswer',
+            }
+          ]
+        }}
+      />
+      <Button type="submit">Continue</Button>
+    </Form>
+    {<Paragraph>
+      You have submitted the following values
+      <pre><code>
+        {JSON.stringify(submittedData)}
+      </code></pre>
+    </Paragraph>}
+  </>
+}
+```
+
+Perfect! We now have a finished form, complete with field validation.