@o3r/forms NPM

This package is an Otter Framework Module.

Description

This module provides utilities to enhance angular form (asynchronous decorator, additional validator, error store...).

How to install

ng add @o3r/forms

Warning: this module requires @o3r/core to be installed.

Container/presenter and form creation

A Container/presenter architecture was put in place to ensure best reusability/sharing

Where the form object creation should be done?

form created in presenter - it's the presenter that decides how the data is displayed
container only values and errors are propagated from the presenter
container can set the default value

How the container and presenter will communicate in forms context

presenter implements ControlValueAccessor and Validator (or AsyncValidator) interfaces
- propagate the value, the form status and the errors
container applies FormControlDirective on the presenter html tag
- container sets the default value using formControl directive
- listen to the value and status changes using the same directive

See FORM_STRUCTURE

You want to include form validation and display the errors

interfaces for the error messages provided in @o3r/forms

Display inline errors

the error messages returned by validators are used in the inline error display
simple/basic/primitive validators - set as a configuration of the presenter
- localization of the associated error messages from the presenter
- the error object associated is computed here and has to be compliant with the store object model
- getFlatControlErrors function is available in @o3r/forms to help with the creation of the associated error object
custom validators created at container level
- localization of the associated error messages from the container
- custom validators are passed as an input to the presenter
- the error returned by the validator has to be compliant with the form error store model

Display errors on a messages panel

a dedicated FormErrorStore is available on @o3r/forms
- allows the display of errors anywhere on the page
- the error object model contains the translation key and params
  See FORM_VALIDATION and FORM_ERRORS

Form submit

You want to submit the form

The submit is triggered by the submit button in the presenter and an event is emitted
container captures the event and executes the submit form logic

What happens when you have multiple forms and you want to submit?

The answer is that we should avoid as much as possible having multiple form tags in the same page as it adds a lot of complexity. We should try to have only one form tag that encapsulates everything and one submit action.

If multiple forms are really needed, then we found the following solution:

the submit button is hidden on the presenters
the submit is triggered from the page
an observable to trigger the submit is passed as input to the containers;
AsyncInput decorator is provided in @o3r/forms to be applied on the observable input to ensure performance
the submit form logic is executed on the containers
containers emit events when the submit is done
the page (parent) captures the events and continues its logic

This can be applied also, with only one form on the page, when you don't want a submit button in the presenter.

What happens when the submit is triggered by the page with pristine forms

At the first display of the form, the inline errors (if the form is invalid) are not displayed because the form element is not touched and dirty In case you want to show the inline errors after the submit, you have to: