Forms overview

Introduction to forms

Applications use forms to handle user input in data-entry tasks (such as logging in or creating a profile for example).

Angular provides two approaches for writing forms: template-driven forms and model-driven or reactive forms. The utilities that we provide in the @o3r/forms module are based on Angular's reactive forms, which "provide a model-driven approach to handling form inputs whose values change over time". This type of form is applicable in many use cases, but there are a couple of exceptions where additional utilities may be useful.

These use cases include:

• A container/presenter structure for components
• Handling form submission at page level
• Displaying the error message outside the form

To handle these, this module provides utilities to enhance the build of Angular reactive forms, including:

• An asynchronous decorator (@AsyncInput) to ensure subscriptions are handled if the references of the input observables change.
• Basic and custom validators to validate user input for accuracy and completeness.
• A dedicated NgRX store for form errors to have the possibility of displaying error messages outside the form component.
• Helper functions to handle the interactions with the forms.

Form structure

When a parent/input component architecture is put in place, we provide documentation on some best practices (such as form creation) to use when building Angular reactive forms components.

See Form Structure.

Form validation

The forms use validators to verify their accuracy and completeness when validating them. During validation, error messages might be returned by the validators, which can be displayed. The interfaces for these error messages are provided in @o3r/forms.

Depending on the use cases, there are different types of validators to use: primitive validators or custom validators. You may also need an asynchronous validator for your form if it needs validation for an asynchronous source.

See Form Validation.

Form error display

If the form validation returns error objects, there is a possibility of displaying them as inline error messages in the form and also in error panels (anywhere on the page such as at the top of the page, above the submit button, etc.).

This is possible since we have a dedicated NgRX store for the form errors, this way we can listen to the store state and display the errors anywhere in the page. The store is provided in the @o3r/forms package.

See Form Errors.

Form submission

We support two cases for the forms submit actions:

• Submit from the component: The submit button is displayed in the input component.
• Submit from the page (application level): The button is hidden in the input component and the submit action is triggered at application level.

In both cases, the submit logic is handled in the parent component, which is notified when a submit action is fired. The execution of the submit logic begins when the event is captured in the parent component. The parent component will handle the business logic and when it has finished, it will emit an event which can be intercepted at page level.

See Form Submit and Intercommunication.

[!NOTE] We implemented an example of forms components in the showcase application, in which a parent component has two subcomponents each containing a form. The first subcomponent has a form for the user to fill out their personal information and the second subcomponent has a form for the user to fill out information about their emergency contact. In this example, the two subcomponents correspond to input components.

You can find the implementation of this forms example in the source code of the showcase application.

This example will be referenced throughout this documentation.