Forms Controls

A guide to creating forms using screen controls in Form Pages

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

Buttons are interactive components which are allow users to submit forms, they are also to implement Consent. The Button screen control widget is used to build buttons.

Button - Screen Control
Button - Screen Structure

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.

  • Button Type

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

    Action – Not used will default to the form type

    Form – Standard form button

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

    State – Not used will default to the form type

  • 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.

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

    /Fault({{faultId}})

    And a “URL Template” value of

    /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. 

    . => 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 or 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

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

Properties of Nav Button

  • Title:

    Sets the button label.

  • URL:

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

  • Icon:

    This property is no longer supported.

  • 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:

    This property is no longer supported.

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.

Reference Input - Screen Control
Reference Input - Screen Structure

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:

    This property is no longer supported.

  • Image URL Template:

    This property is no longer supported.

  • 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. Specify the Target URL or the Entity name of the active form page and save your changes.

  2. Add a Auto Inputs screen control widget to the active form page and configure its properties or else,

  3. Add a Input screen control widget to the active form page and configure its properties or else

  4. Add a 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.

PreviousFormNextLists in Form Pages