# Forms Controls

Form controls are fundamental elements within the ComUnity Development Toolkit that empower developers to create interactive and user-friendly forms for data collection and input. These controls serve as building blocks for designing effective user interfaces and streamlining data submission processes. Form controls encompass a diverse range of components, each designed to cater to specific input needs.

From input fields and auto-inputs to reference inputs and an extensive array of buttons, these form controls serve as screen controls specifically designed to build forms. They provide a versatile set of tools that seamlessly facilitate data interaction. By incorporating these controls into your application, you can elevate user experience, ensure precise data input, and optimise the overall functionality of your application.

In the following sections, we will delve into the various types of form controls available, explore their unique properties, and discuss best practices for integrating them into your application's design. Whether you're creating simple data entry forms or complex multi-step processes, form controls provide you with the means to build efficient and intuitive user interfaces that cater to your application's requirements.

### Button&#x20;

Buttons are interactive components which are allow users to submit forms, they are also to implement [Consent](https://comunity.gitbook.io/learning.comunityplatform/v4/toolkit-guides/screens/building-screens/form/broken-reference). The Button screen control widget is used to build buttons.

<div align="center"><figure><img src="https://content.gitbook.com/content/h2CgaYxTJg9abC9usaCb/blobs/rBQtNulrHlAysUIOVBT2/image.png" alt="" width="164"><figcaption><p>Button - Screen Control</p></figcaption></figure> <figure><img src="https://content.gitbook.com/content/h2CgaYxTJg9abC9usaCb/blobs/VirzgcIoLOrgUvMBsGdu/image.png" alt="" width="296"><figcaption><p>Button - Screen Structure</p></figcaption></figure></div>

#### Properties of a Button

* **Button Text**\
  This property allows you to specify the default text to display on your form button. A valid Button Text must be of type string with a maximum length of 12. The Button Text property is required.
* #### Button Text(Long)

  This is an optional property that is used to specify a long Button Text. This **Button Text(Long)** is not displayed in devices which enforce a text limit constraint, e.g. Java phones.
* **Verb Name**\
  This property allows you to specify an HTTP verb for the form action.
* **Consent Name**\
  This property allows you to select a consent by name from a list of consents which exist in the system. The selected consent is applied when the form is submitted. To learn more view [Consent](https://comunity.gitbook.io/learning.comunityplatform/v4/toolkit-guides/screens/building-screens/form/broken-reference).
* #### Button Type

  This specifies the type of button to use in a form and defaults to a Form button type if not specified

  Action – *<mark style="color:red;">Not used will default to the form type</mark>*

  Form – Standard form button

  Link – A button that renders as clickable text in the form

  State – *<mark style="color:red;">Not used will default to the form type</mark>*
* #### URL Template

  The button operation (i.e POST, PATCH, etc.) is performed on the form data path which is derived from the **Target URL** or **Entity Name**.  This value allows appending to the data path so that the operation will be performed on a different entity.&#x20;

  For example, a form with a **Target URL** as below:

  `/Fault({{faultId}})`

  And a “URL Template” value of&#x20;

  `/FaultType`

  The OData path for the operation will be as below

  `/Fault({{faultId}})/FaultType`
* #### Document Template

  This allows customisation of the JSON body that will be sent when the button is pressed. The JSON body is automatically derived from the form inputs that have been added to the form, however if additional values are required in the body or it needs to be customised then this field will modify the default behaviour.
* #### Confirm Content

  This property allows you to specify a message that will be displayed to the user before the action continues with submitting the request. Setting this value will result in a dialog being displayed when pressing the button.
* **Navigate URL**

  This property allows you to specify the path to a page a user is redirected to after form submission. The accepted values are:
* #### Yes Button Text

  This property allows you to customise the text that is displayed on the button in the confirm action dialog. By default the Yes Button displays `Yes`.&#x20;

  ```
  . => remain on current form
  .. => return to parent

  LINK:<nav_link_id> => redirect to specified navigation link

  ```
* #### No Button Text

  This property allows you to customise the text that is displayed on the button in the confirm action dialog.. By default the No Button displays `No`.
* #### Success Content

  This property allows you to specify a message to display to a user after successful form submission. Setting this value results in a dialog being displayed to the user that must be dismissed by the user.
* #### Success Bubble Text

  This property allows you to specify a message to display to a user after successful form submission. Setting this value results in a popup message being displayed to the user that will be dismissed automatically after a short time delay.

### Auto Inputs

All inputs screen control widget creates form fields for all the properties of the entity specified in the [Target URL](https://comunity.gitbook.io/learning.comunityplatform/v4/toolkit-guides/screens/building-screens/form/..#target-url) or [Entity name](https://comunity.gitbook.io/learning.comunityplatform/v4/toolkit-guides/screens/building-screens/form/..#entity-name) of the parent form page.

#### Properties of **Auto Inputs**

* **Include:**

  This property allows you to order your form fields by entity property. It accepts a comma delimited list of entity properties.
* **Exclude:**

  The property allows you to filter All Inputs by to specifying entity properties to exclude from All Inputs. It accepts a comma delimited list of entity properties.
* **Readonly:**

  This property allows you to specify read only form fields by entity property. It accepts a comma delimited list of entity properties.

### Block Template

#### Properties of Block Template

* **Block URL:**

  This property allows you to set the Data Path for the items in the list. The value is appended to the Target URL for the page.
* **Block Title:**

  Sets the title for the list item
* **Block Content:**

  Sets the title for the list item
* **Block Items:**

  Sets the maximum number of items to be fetched for the list.
* **Query Filter:**

  Sets the query that will be applied when fetching the records for the list.
* **Search Fields:**

  Sets the fields that will be used when filtering with the text search bar.

### Form Buttons

#### Properties of Form Buttons

* **Entity Fullname:**

  Defines the entity that will be used for the update and delete actions. If a value is not set then the system will attempt to derive this automatically.
* **Edit Text:**

  Sets the label of the form edit button, button will only be added if there is a value set.
* **Update Text:**

  Sets the label of the form update button, button will only be added if there is a value set.
* **Delete Text:**

  Sets the label of the form delete button, button will only be added if there is a value set.

### Input&#x20;

#### Properties of Input

* **Property Name:**

  Sets the property (field) to be used for the input control.
* **Property Navigation:**

  If the property is on a different entity then this value can be used to specify the navigation path to the property. The value is appended to the form’s data path.

### Nav Button&#x20;

#### Properties of Nav Button

* **Title:**

  Sets the button label.
* **URL:**

  An external URL that should be opened when the button is pressed
* **Icon:**

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>This property is no longer supported.</p></div>
* **Detail:**

  If the value starts with “SHARE:” then it can be used to share the application via various channels else the value is not used. For sharing the following syntax must be used:

  ```
  SHARE:{“Message”:”<share message>”}
  ```
* **Navigate URL:**

  The internal that should be navigated to after pressing the button
* **Button Type:**

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>This property is no longer supported.</p></div>

### Reference Input

The **Reference Input** controls are used to generate dropdown lists. These lists can either be based on the entity associations of a designated page or any entity within the Data Model, even if it's unrelated to the entity specified by the **Target URL** of that page. For a basic configuration, simply set the **Data Path** to point to the desired options.

<div align="center"><figure><img src="https://content.gitbook.com/content/h2CgaYxTJg9abC9usaCb/blobs/AdxPsxbZCMHJ5AlXyYZh/image.png" alt="" width="164"><figcaption><p>Reference Input - Screen Control</p></figcaption></figure> <figure><img src="https://content.gitbook.com/content/h2CgaYxTJg9abC9usaCb/blobs/DIpmPRCebVQ72KqRYymy/image.png" alt="" width="299"><figcaption><p>Reference Input - Screen Structure</p></figcaption></figure></div>

#### Properties of Reference Input

* **Property Name:**

  Sets the property (field) to be used for the input control.
* **Property Navigation:**

  If the property is on a different entity then this value can be used to specify the navigation path to the property. The value is appended to the form’s data path.
* **Data Path Template:**

  The value will be appended to the page data path to determine the reference entity that will be used as the source for the dropdown values. The specified value can contain templates and '..' to define the required Data Path.
* **Query:**

  The query that must be applied to the reference entity when fetching the values.
* **Search Fields:**

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>This property is no longer supported.</p></div>
* **Image URL Template:**

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>This property is no longer supported.</p></div>
* **List Title Template:**

  The template definition for displaying the value in the dropdown selector.

## Building Forms

In the ComUnity Toolkit, you have the flexibility to construct forms utilising either the **Input** controls, the **Auto Inputs** controls, or a combination of both. With the **Input** controls, you're required to manually define each input field, giving you more control as you manage all your form fields directly. In contrast, the **Auto Inputs** feature automatically generates all input fields based on the entity defined in the **TargetURL** of the designated page. The primary advantage of **Auto Inputs** controls is their adaptability: when you modify your entity definition, your form fields adjust automatically. However, there's a drawback. If you don't want fields for all entity properties, you may have to adjust **Auto Inputs** settings. Thus, while **Auto Inputs** offers convenience, **Input** controls provide a granular level of management.

To create a form in a form page, follow these steps:

1. &#x20;Specify the [Target URL](https://comunity.gitbook.io/learning.comunityplatform/v4/toolkit-guides/screens/building-screens/form/..#target-url) or the [Entity name](https://comunity.gitbook.io/learning.comunityplatform/v4/toolkit-guides/screens/building-screens/form/..#entity-name) of the active form page and save your changes.
2. Add a [Auto Inputs](#auto-inputs) screen control widget to the active form page and configure its properties or else,
3. Add a [Input](#input) screen control widget to the active form page and configure its properties or else
4. Add a [Button ](#button)control widget to an active form page and configure its properties.

You have successfully created a dynamic form. The ComUnity Development Toolkit will parse your form definition and render forms in the client with an intelligent auto fill feature.
