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:

• register a function in the container to mark touched and dirty the form
• pass the function via an @Output from the presenter and call it before executing the submit logic
• use markAllControlsDirtyAndTouched helper is available in @o3r/forms to mark interactions on given form

See FORM_SUBMIT&INTERCOMMUNICATION

Details

Find more information in the documentation.