Wrpeck/formbuilder update (#5473)

* small adjustment to language

* adding storagemanager documentation

* Adding relationships documentation

* final edits to v1 relationships and storage

* Update data-binding.mdx

Adjusting header for clarity

* Update data-binding.mdx

Removed unnecessary hint

* Update special-inputs.mdx

Additional configuration changes

* Update data-binding.mdx

minor change to heading

---------

Co-authored-by: wpeck-amplify <107895670+wpeck-amplify@users.noreply.github.com>

cspell.json

@@ -439,6 +439,7 @@
     "confirmSignUp",
     "ConfirmSignUp",
     "confirmSignUpConfig",
+    "connectedform",
     "connectionWithKeyExamples.md",
     "constraintlayout",
     "contactapi",
@@ -484,6 +485,7 @@
     "deeplink",
     "Deeplink",
     "deepskyblue",
+    "defaultform",
     "defaultName",
     "defaultPriority",
     "defaultTTL",
@@ -722,6 +724,7 @@
     "Info.plist",
     "initapi",
     "inout",
+    "inputs.mdx",
     "installable",
     "Intelli",
     "interceptApplication",
@@ -963,6 +966,7 @@
     "parameters.json",
     "parcelable",
     "passwordless",
+    "pausable",
     "PAY_PER_REQUEST",
     "Permission.Read",
     "phone_number",
@@ -1194,6 +1198,7 @@
     "Storage.put",
     "storagebucketname",
     "storagedemo",
+    "storagemanager",
     "storageOptions",
     "StorageType",
     "streamName",

src/directory/directory.mjs

@@ -2390,6 +2390,14 @@ export const directory = {
             title: 'Customize form inputs',
             route: '/console/formbuilder/customize'
           },
+          {
+            title: 'Data binding',
+            route: '/console/formbuilder/data-binding'
+          },
+          {
+            title: 'Configure special inputs',
+            route: '/console/formbuilder/special-inputs'
+          },
           {
             title: 'Validate form data',
             route: '/console/formbuilder/validations'

src/pages/console/formbuilder/customize.mdx

@@ -27,12 +27,18 @@ Add form inputs to personalize the form to your use case. To add a form element:
 1. Move your mouse onto the center form canvas.
 2. Hover in between, before, or after a form input until a blue bar with a (+) sign appears.
 3. Click the blue bar with the (+) sign.
-4. Select the form input you want to add. If your form is connected to a data model, you can also select a field of the data model and let Amplify Studio infer the input.
+4. Select the form input you want to add.
 
 <video autoPlay={true} muted={true} loop={true} width="100%">
   <source src="/images/console/formbuilder/customize-add.mp4" />
 </video>
 
+
+Every input element in your form can be customized. Select a field in the form to open the configuration menu, where you can customize parts of the input, like its display label and placeholder. 
+
+Some form inputs have unique configurations, like **Storage Manager**. [Learn more about configuring special fields in the documentation](/console/formbuilder/special-inputs). 
+
+
 ## Reorder form inputs with drag and drop
 
 Rearrange form inputs vertically or horizontally.
@@ -69,11 +75,11 @@ Spacing values can either be a CSS length value (`px`, `rem`, `em`, `%`) or a re
   <source src="/images/console/formbuilder/customize-spacing.mp4" />
 </video>
 
-## Configure options for Select Field or Radio Group Field
+## Configure options for Select, Radio Group, or Autocomplete Field
 
-[Select Field](https://ui.docs.amplify.aws/react/components/selectfield) and [Radio Group Field](https://ui.docs.amplify.aws/react/components/radiogroupfield) require a set of options for your users to choose from. For example, a "Status" input can only have the options "Not started", "In progress", and "Done".
+[Select Fields](https://ui.docs.amplify.aws/react/components/selectfield), [Radio Group Fields](https://ui.docs.amplify.aws/react/components/radiogroupfield), and [Autocomplete Fields](https://ui.docs.amplify.aws/react/components/autocomplete) require a set of options for your users to choose from. For example, a "Status" input can only have the options "Not started", "In progress", and "Done".
 
-1. Select a **Select Field** or **Radio Group Field** input
+1. Pick a **Select Field**, **Radio Group Field**, or **Autocomplete Field** input
 2. Go to **Data > Options**
 3. Enter available options line-by-line or paste in a JSON array, such as `["Not started", "In progress", "Done"]`
 

src/pages/console/formbuilder/data-binding.mdx

@@ -0,0 +1,78 @@
+export const meta = {
+  title: 'Data binding',
+  description:
+    'Cloud connected forms can be bound to data models with relationships, allowing multiple data models to be updated upon submission.'
+};
+
+## Connected forms
+Connected Forms are bound to a model in your data schema. Whenever a connected form is submitted, a record is created or updated in the bound data model automatically, with some or all of the form's input fields mapping to fields in the data model. Connected forms work automatically - no `onSubmit` handling is required.
+
+## Unconnected forms
+Unconnected Forms are standalone React components that can be used in any React or Nextjs project, even without an AWS account. Upon submission, the input values for the form are [accessible via the `onSubmit` hook for handling](/console/formbuilder/lifecycle/#handle-form-data-submissions---onsubmit). 
+
+You can build unconnected forms without ever logging into AWS [using the Amplify Sandbox](https://sandbox.amplifyapp.com/ui-library). 
+
+## Types of forms
+
+All connected and unconnected forms are either a **Create** form or an **Update** form. 
+
+### Create forms
+
+Create forms render a form with empty inputs. If a create form is connected to a data model, will always generate a new record upon submission.
+
+### Update forms
+Update forms expect an input value in order to pre-populate the form. 
+
+For update forms that are connected to a data model, you can use the `id` prop, or the model prop:
+* `id` prop: id string of the record you want to update. For example:
+
+```jsx
+<AuthorUpdateForm id='ac74af5c-3aab-4274-8f41-23e1e6576af5' />
+```
+
+* Model prop: if your form is bound to a data model named `Author`, your form will have a prop named `author` as well, which can receive a record. For example:
+
+```jsx
+
+<AuthorUpdateForm author={authorRecord}>
+
+```
+It is generally recommended to use the model prop instead of the `id` prop. 
+
+For unconnected update forms, you can pass an object to the `initialData` prop to pre-populate the form. However, as with all unconnected forms, you must handle the form submission in code. 
+
+## Customizing data binding
+
+### Bind an unconnected form to a data model
+
+If you want to convert an unconnected form to a connected form, you can do so from within the form configuration menu. To configure your form's data model mapping:
+1. [Log into Amplify Studio](/console/adminui/start/) and select the **UI Library** from the left-hand navigation bar
+1. Select your unconnected form and select **Configure** in the upper right-hand corner
+1. In the upper right-hand corner, use the **Data model mapping** dropdown menu to update your form
+
+![Data model mapping drop down with options for an unconnected form](/images/console/formbuilder/data-model-mapping.png)
+
+From this dropdown menu, you have several options:
+
+**Create new data model**: Studio will use your form to [generate a brand-new data model in your schema](/data/data-model/)
+
+**Select from an existing model**: 
+  * If your form matches the data model, Studio will bind them together, converting your unconnected form to a connected form
+  * If your form doesn't match the data model, Studio will add fields to match to your form (or schema) to ensure a match
+
+**Map data in code**: Use this option to ignore data mapping, and keep this form unconnected
+
+### Extend a connected form
+
+If your form is already connected to a data model, Studio will help you manage your connection as you extend your form. To extend a connected form:
+1. [Log into Amplify Studio](/console/adminui/start/) and select the **UI Library** from the left-hand navigation bar
+1. Select your connected form and select **Configure** in the upper right-hand corner
+1. Add a new field of any kind
+
+Studio will list any fields that aren't mapped to your data model on the right-hand side. 
+
+![Unmapped field appears in the right hand bar for the user to handle](/images/console/formbuilder/data-model-field-mapping.png)
+
+If you select **Update data model**, Studio will automatically add a field to your data model schema. 
+
+If you select **I'll handle in code**, Studio will ignore the data mapping for this field, and you can handle this field using the `onSubmit` hook. 

src/pages/console/formbuilder/overview.mdx

@@ -3,70 +3,93 @@ export const meta = {
   description: `Amplify Studio's Form Builder automatically generates cloud-connected forms as React code, either from your data model, any JSON object, or from scratch. You can configure validation logic, adjust theming, and customize presentation all within the console.`,
 };
 
-Amplify Studio's Form Builder automatically generates cloud-connected forms as React code, either from your data model, any JSON object, or from scratch. You can configure validation logic, adjust theming, and customize presentation all within the console. 
+Amplify Studio's **Form Builder** is a visual interface for creating React forms. You can configure validation logic, adjust theming, and customize presentation all within the console. 
 
-Forms are also extensible, allowing full form lifecycle management, and supporting custom validation logic in code, including calling an external API or validating against another database.
+Forms are fully extensible, allowing lifecycle management, and supporting custom validation logic in code, including calling an external API or validating against another database. 
 
-## Option 1: Use auto-generated forms
+<Callout warning>
 
-The fastest and easiest way to use the Form Builder is to use forms generated from your data model. To auto-generate forms:
+Form builder now supports **relationship fields** in your data models! Relationships will be created as [autocomplete fields](https://ui.docs.amplify.aws/react/components/autocomplete). 
 
-1. In [Amplify Studio](/console/adminui/start/#logging-in-and-creating-an-app) deploy a [Data model](/console/data/data-model/) 
+</Callout>
+
+## Getting started
+
+When you build a form with Form Builder, Amplify Studio generates a reusable React component based on your design. This component code can then be pulled into your project directory, imported, and rendered in your app with only a few lines of code.
+
+To start with Form Builder in a Studio app...
+1. [Log into your Studio application](/console/adminui/start/#logging-in-and-creating-an-app)
+1. Select **UI Library** on the left-hand navigation bar
+1. Take one of the following paths:
+
+<BlockSwitcher>
+
+<Block name="Default form">
+
+If you have a data model deployed in your Amplify app, Studio will automatically generate default [connected forms](/console/formbuilder/data-binding/#connected-forms) for you.
+
+To use default forms:
+1. Log into [Amplify Studio](/console/adminui/start/#logging-in-and-creating-an-app) and deploy a [Data model](/console/data/data-model/) 
 2. Navigate to the **Studio Console > UI Library**
 
 Your forms will be listed on the left-hand navigation bar under the **Forms** header
 
 ![Studio console showing auto-generated forms on the left-hand navigation bar](/images/console/formbuilder/overview1.png)
 
+Default forms can be identified by the Amplify icon next to the form name
+
+![Form name showing the Amplify icon, indicating it is a default form](/images/console/formbuilder/defaultform.png)
+
 <Callout info>
 
 **Missing a form?** If you have a deployed data model but have no forms, automatic form generation may be disabled. In the upper right-hand corner of the UI Library, select **UI Library settings**, and enable **Automatic form creation**.
 
 </Callout>
 
-For each data model, Amplify Studio will generate two forms: a **Create** form, and an **Update** form. 
+Default forms can be used as-is, or they can be customized. To customize a default form, select the form in the left-hand navigation bar, and click **Configure** in the upper right-hand corner. If you change your mind, you can delete your form, and a new default form will be generated. 
 
-Your forms will contain inputs for each field of your data model. Auto-generated forms are dynamic; as your data model changes, the forms' fields will update accordingly.
+After you are satisfied with your form, you [can render it in your app](#render-react-form-in-your-app).
 
-## Option 2: Build a form from scratch
+</Block>
 
-Alternatively, Amplify Studio allows you to build forms completely from scratch. To generate a basic, brand-new form:
+<Block name="New connected form">
 
-1. In [Amplify Studio Console](/console/adminui/start/#logging-in-and-creating-an-app), navigate to **UI Library**
-2. In the left-hand nav bar, next to the **Forms** header, select **New**
-3. Give your form a name
-4. For this example, leave the other options as default, and click **Create form**
+To use connected forms, you first need a data model. Log into [Amplify Studio](/console/adminui/start/#logging-in-and-creating-an-app) and deploy a [Data model](/console/data/data-model/). 
 
-![New form page, showing the options available when creating a new form](/images/console/formbuilder/overview2.png)
+To build a new connected form...
+1. Select **UI Library**
+1. In the **Forms** section of the left-hand nav bar, select **New**
+![Red box around the "new" section of Form Builder](/images/console/formbuilder/overview7.png)
+1. Name your Form, and select [Create or Update](#create-and-update-forms)
+1. In the **Data model** dropdown, select which model your form should connect to
+1. Select **Create form**
 
-After clicking **Create form**, you will be directed to the Edit Form page. Select the **plus sign**, and select an input element to add to your form. 
+![Create new form screen with the Publisher data model highlighted in the Data model section](/images/console/formbuilder/connectedform.png)
 
-![Image of the Form Creation page with the blue bar and plus sign indicating the ability to add input elements to the form](/images/console/formbuilder/overview3.png)
+Form builder will generate a new form with input fields that match the fields of the connected data model. From here, you can [customize your inputs](./customize), and after you are satisfied with your form, you [can render it in your app](#render-react-form-in-your-app).
 
-Alternatively, you can select different options when generating your form:
-- Forms created as **Update** forms will expect input data
-- Forms that start with a **Data model** will have an input element for every field on the data model, similar to an auto-generated form
-- Learn more [JSON object forms below](#option-3-generate-a-form-from-json)
+</Block>
 
-## Option 3: Generate a form from any JSON object
+<Block name="New JSON form">
 
-Amplify Studio can generate a form based on the JSON object you'd like it to produce. This is particularly useful if you are interfacing with another API - most API endpoints expect input data in JSON format, so you can quickly generate a form by pasting a sample payload. 
+Amplify Studio can generate an unconnected form based on the JSON object you'd like it to output. This is particularly useful if you are interfacing with another API - most API endpoints expect input data in JSON format, so you can quickly generate a form by pasting a sample payload. 
 
 To generate a form from JSON:
 
 1. In [Amplify Studio Console](/console/adminui/start/#logging-in-and-creating-an-app), navigate to **UI Library**
-2. In the left-hand nav bar, next to the **Forms** header, select **New**
-3. In the New Form page, select **JSON object**
-4. Paste your JSON into the code editor
-5. Give your form a name, and click **Create form**
+1. In the left-hand nav bar, next to the **Forms** header, select **New** 
+![Red box around the "new" section of Form Builder](/images/console/formbuilder/overview7.png)
+1. Give your form a name, and select [Create or Update](#create-and-update-forms)
+1. In the New Form page, select **JSON object**
+1. Paste your JSON into the code editor and click **Create form**
 
 Form Builder will infer the input element type based on the value and can handle arrays and nested JSON values. For example, use this JSON sample:
 
 ```json
 {
   "basics": {
     "firstName": "Wesley",
-    "emailAddress": "wpeck@amazon.com"
+    "emailAddress": "wesley@example.com"
   },
   "favoriteThings": {
     "animals": ["Cats", "Snakes", "Quokka"],
@@ -82,10 +105,42 @@ This JSON will render the following form:
 
 ![Form rendered from JSON showing headings and fields with types inferred from key pair values](/images/console/formbuilder/overview6.png)
 
-From the JSON object, Amplify Studio can automatically
-- set the correct types for **Email address** and **Number**
-- set **Animals** to receive multiple values
-- set **Active** and **Enabled** to switches
+From the JSON object, Amplify Studio can automatically...
+- ...set the correct types for **Email address** and **Number**
+- ...set **Animals** to receive multiple values
+- ...set **Active** and **Enabled** to switches
+
+When you are satisfied with this form, you can convert it to a connected form by [binding to a data model](#form-binding), or you [can render it in your app](#render-react-form-in-your-app).
+
+</Block>
+
+<Block name="New blank form">
+
+Amplify Studio allows you to build unconnected forms completely from scratch with a visual interface. To generate a basic, brand-new form:
+
+1. In the [Amplify Studio Console](/console/adminui/start/#logging-in-and-creating-an-app), navigate to **UI Library**
+1. In the left-hand nav bar, next to the **Forms** header, select **New**
+![Red box around the "new" section of Form Builder](/images/console/formbuilder/overview7.png)
+1. Give your form a name, and select [Create or Update](#create-and-update-forms)
+1. Leave **Black form** selected, and click **Create form**
+
+![New form page, showing the options available when creating a new form](/images/console/formbuilder/overview2.png)
+
+After clicking **Create form**, you will be directed to the Edit Form page. Select the **plus sign**, and select an input element to add to your form. 
+
+![Image of the Form Creation page with the blue bar and plus sign indicating the ability to add input elements to the form](/images/console/formbuilder/overview3.png)
+
+You can continue to customize your form inputs, and when you are satisfied, you can convert it to a connected form by [binding to a data model](#form-binding), or you [can render it in your app](#render-react-form-in-your-app).
+
+</Block>
+
+</BlockSwitcher>
+
+<Callout info>
+
+Alternatively, to get started without logging into AWS, [you can build unconnected forms in the Amplify Sandbox](https://sandbox.amplifyapp.com/ui-library). 
+
+</Callout>
 
 ## Render React form in your app
 
@@ -139,4 +194,22 @@ import {
 
 ```
 
-3. Place your form in code. For a form named `ProductCreateForm`, you would use `<ProductCreateForm />` to render the form
+3. Place your form in code. For a form named `ProductCreateForm` in a React project, you could use the following App code:
+
+```jsx
+
+function App() {
+  return (
+    <ProductCreateForm />
+  )
+}
+
+export default App;
+
+```
+
+## Limitations
+
+To build and use [connected forms](/formbuilder/data-binding/#connected-forms), your GraphQL API must be using **DataStore**. To activate DataStore, [select a Conflict Resolution strategy and deploy your API](/data/data-model/#datastore-and-graphql). 
+
+If you are not using DataStore, you can still build [unconnected forms](/console/formbuilder/data-binding/#unconnected-forms) in Studio or in the Amplify Sandbox.