The Intershop PWA has switched to using formly to define and build forms.
Refer to our Formly Documentation for information.
The overwhelming majority of old components and directives has been deprecated as of release 1.0.
If you are looking for documentation, refer to older documentation.
File and Naming Conventions
Reusable Form Components
- Form components are available as Formly field types that come with wrappers and extensions. You can find them in: app/shared/formly/ or app/shared/formly-address-forms/components. Refer to our Formly Documentation for more information.
- It is possible to define formly field configurations that can be reused anywhere in the PWA. You can find them in: app/shared/formly/field-library. Refer to the Field Library docs for more information.
- These forms can be used as (sub)forms on arbitrary pages, e.g., there are address forms on registration page, checkout and My Account pages.
Page Specific Form Components
- File location: app/pages/<page>/<form-name>
- Name: <form-name>-form.component.ts
- These forms are only valid for a specific page. They are not reusable.
- Example: The credentials form on the registration page.
Data Models
- File location for models and related classes: app/core/models/<object>
- Model name: <object>.model.ts
- Mapper file name: <object>.mapper.ts
- Data (interface) file name: <object>.interface.ts
Services
- File location for global services: core/services/<object>
- File location for module specific services: <module>/services/<object>
- Name: <object>.service.ts
Usually, there should be no form specific data models.
If forms are related to persistent data, use/create generic data models for your forms, e.g., there should be only one data model for addresses.
Each model has its own service class(es).
In this class there are methods concerning the data model, e.g., updateAddress (address: Address)
Extensions
If functionality is implemented as an extension, the form models and services can be found in the extensions folder:
- forms: app/extensions/<module>/pages/<page>/<form-name>
- models: app/extensions/<module>/models/<object>
- services: app/extensions/<module>/services/<object>
Form Behavior
- Labels of required form controls have to be marked with a red asterisk.
- After a form control is validated:
- Its label gets green and a checked icon is displayed at the end of the control in case the input value is valid.
- Its label gets red, an error icon is displayed at the end of the control and an error message is displayed below the control in case the input value is invalid.
- Form validation:
- If a form is shown, there should not be any validation error messages.
- If a user starts to enter data in an input field, this field will be validated immediately.
- If the user presses the submit button, all form controls of the form are validated. In case of validation errors, the focus is set to the first invalid form field. The submit button will be disabled as long as there is any unhandled form error.
General Rules
Usage of Formly, Template Driven and Reactive Forms
In general, you should use Formly for creating your forms.
If a form is very simple (e.g. only one form input field without any special validation rules), it is also possible to use reactive or template driven forms as an exception.
Validators
For the validation of the form input fields you can use Angular's Built-in Validators.
If there is a need for special custom validators, use the class app/shared/forms/validators/special-validators to write your own custom validators.
Keep Templates Simple
Formly allows moving almost all logic from the template to the component file.
Most form behavior like displaying validation messages and status is already defined within the FormlyModule.
Use the available field types and wrappers to construct your form in the component (see Formly).