---
tags:
- UI Page widgets
alias: user-guide-uipage-widgets-form
widgetname: Form
description: "The Form widget allows users to collect or display data through configurable fields, with customization options for styling and behavior"
---

# Form

![formIcon](images/uiForm.png)

## Overview

The Form widget displays a set of fields that can be used to collect inputs or display data. An example of a UI Page is shown below, where a Form widget is used to collect a Barcode.

![formExample](images/uiPageExample8.png)

!!! smart-barcode "Smart Barcode Scanning"
    This widget supports [[smart-barcode-scanning|Smart Barcodes]].

## General Steps

{% include-markdown 'includes/pages/ui_widgets_general_steps_with_behavior.md' %}

![formGeneral](images/form_general.png)

## Widget Customization

1. Optionally, in the **Style** tab, you can define a Border Width and Color, Font, Font Size, Font Color, and Horizontal Alignment. These styles will act as defaults for all fields unless further customization is applied to any specific field.

    ![formStyle](images/form_style.png)

2. In the **Fields** tab, configure the properties to be displayed in the widget. After adding a new field, specify:

    * **Name** - This will be the unique identifier of the field and the text displayed in the Form.
    * **Value Units** - Optional units to be displayed alongside the value in the Form (e.g., kg, cm, etc.).
    * **Show Label** - Determines if the Name property will be shown in the widget. This option is set to `true` by default.
    * **Value Type** - Select the type of value from the available options (e.g., entity type, integer, reference type, among others).
    * **Is Visible** - Determines if the field is visible in the Form. This option is set to `true` by default.
    * **Is Read-Only** - Determines if the field is read-only, meaning it cannot be edited. This option is set to `false` by default.
    * **Is Enabled** - Determines if the field is enabled for user interaction. This option is set to `true` by default.
    * **Is Barcode Scanning Enabled** - Determines if the [[smart-barcode-scanning]] feature is enabled for the widget. This option is set to `true` by default.
    * **Barcode Field Name** - This will be the unique identifier of the field when using the [[smart-barcode-scanning]] feature. This field is only shown if you have enabled the option above.
    * **Is Required** - Specifies if the field is mandatory and must be filled out by the user. This option is set to `false` by default.
  
    The Style properties configured in step 1 will be applied to all the fields in the Form by default. However, you can also customize the Style of each label in this wizard by specifying:

    * **Label Font**
    * **Label Font Size**
    * **Label Font Color**
    * **Label Horizontal Alignment**

    If a field has the Is Read Only toggle button set to `true`, there is also the option to configure the Value Font family, Font Size, Font Color, and Horizontal Alignment.

    !!! warning
        The styles configured in the Fields tab will override the ones defined in the **Styles** tab.

    ![formFields](images/form_fields.png)

3. Optionally, define the **Links** between this widget and other elements of the UI Page.

    ![formLinks](images/form_links.png)

4. Select **Save and Close** to complete the widget configuration.

## Real Use Case 1

A Form field can be easily adapted to be used as an Entity lookup to help the you provide the correct entry.

1. Configure the **Fields** tab by selecting the Type as `ReferenceType`, the ReferenceType as `EntityType`, and specify the ReferenceType name field. In this example, Resource was chosen.

2. Optionally, use a Query if further filtering of the possible entities for selection is needed.

    ![Screenshot showing a form with an optional query field for further entity filtering.](images/form_use_case_example.png)

3. On the UI page, the form field will display as shown below:

    ![Screenshot showing a form field labeled "Form" on a UI page.](images/image-20210518141046284.png)

## Real Use Case 2

If a [[user-guide-system-tasks-data-sources#query|Query]] includes parameters, these can be easily provided using, for example, a Form widget. Each parameter can be linked to a separate Form field. Here are some examples of the different possibilities depending on different Query parameter setups.

### Query Parameter: Name

For a Query parameter configured for an entity name, a string value must be passed to the query. This can be done in two ways:

* **String Name** - Use a string field for free text user entry without needing a converter.
* **Selected Entity** - Use a selected entity field as shown in previous example. In this case, use the `Get Entity Name` converter to transform the selected entity and retrieve the entity name, which is then supplied as a string.

Using the Selected Entity method, you should:

1. Add a Query task in the UI Page Settings wizard. In this example, the Query task selected was the `MaintenanceActivitiesForResourceViewQuery`.

    ![Screenshot showing a query parameter named "Name" in the UI Page Settings wizard.](images/form_to_query_parameter.png)

2. Link the entity Form field to the Query task configured in the previous step:

    ![Screenshot showing a form field linking an entity to a query task, with options including "RESOURCE NAME" and "CHANGE MAINTENANCE ACTIVITY OR ORDER".](images/form_to_query_parameter01.png)

3. Configure a converter for the link just created:

    ![Screenshot showing a form with "Name" as a query parameter field.](images/form_to_query_parameter02.png)

### Query Parameter: Entity

If the Query parameter is the entity itself, used the `Any To Any Property` converter. In this case, the Query expects the database entity ID (normally not known to the user) rather than the familiar entity name. The `Any To Any Property` converter retrieves the entity ID from a selected entity object, requiring a converter parameter to specify which property to retrieve. In this example, we want to retrieve the database entity ID and feed it to the Query.

1. Add in the page properties an additional string property with value "Id":

    ![Screenshot showing a form field for querying an entity parameter, labeled as "Entity".](images/form_to_query_entity_parameter.png)

2. Link the entity Form field to the Query task:

    ![Screenshot showing a form field linking an entity to a query task, with options including "RESOURCE NAME" and "CHANGE MAINTENANCE ACTIVITY OR ORDER".](images/form_to_query_parameter01.png)

3. Configure the `Any To Any Property` converter using the Key Property Id for the link just created:

    ![Screenshot showing a form with fields for querying an entity parameter.](images/form_to_query_entity_parameter02.png)

## Barcode Real Use Case

The following scenario demonstrates how to create a Form widget in a UI Page that can be automatically populated using a barcode scanner.

1. In the **Administration** menu, navigate to the **Configuration** entity and configure the value in the `/Cmf/Guis/Configuration/Common/BarcodeInputLabelSpecification/` entry to `GS1`.

    ![Edit Barcode Configuration Entry](../../../../general/images/barcode_input_config_entry.png)

    !!! info
        For more information, see [[smart-barcode-scanning]].

2. Go to the [[labelspecificationfield-gt]] Generic Table and add the fields that should be extracted from the barcode. Each field must reference a label prefix and the corresponding MES Target Field.

    ![Screenshot showing Generic Table with fields for extracting barcode data.](images/add_label_specification_values.png)

3. In this example, the following fields will be used:

    ![Screenshot showing a barcode with various label specification values displayed.](images/label_specification_values.png)

4. In an empty UI Page, add a Form widget and define the required fields. Below are examples of how to configure each form field:

    === "Material Name"

        ![Screenshot showing a Form widget with fields for "Material" and "NIE".](images/barcode_form_field_name.png)

    === "Material Type"

        ![Screenshot showing a Form widget with fields for scanning and displaying barcodes.](images/barcode_form_field_type.png)

    === "Material Product"

        ![Screenshot showing a Form widget with fields for "Product" and "Quantity".](images/barcode_form_field_product.png)

    !!! note
        The Barcode Field Name must match with the Target Field defined in the [[labelspecificationfield-gt]] Generic Table.

5. With everything in place, you can now scan a barcode. The system will automatically parse its contents and populate the Form fields with the corresponding values.

    ![Screenshot showing a barcode being scanned into a form, with system-generated data populating the fields.](images/barcode_form_example.png)