Related Github Documents
Document Properties
Kbid
2945M6
Last Modified
02-Aug-2021
Added to KB
18-Jun-2020
Public Access
Everyone
Status
Online
Doc Type
Guidelines, Concepts & Cookbooks
Product
Intershop Progressive Web App

Guide - Intershop Progressive Web App - Forms

Forms

The Intershop PWA has switched to using formly to define and build forms.
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

  • Reusable 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
  • 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.
  • There are still some deprecated form components which you can find in app/shared/forms/components/<form-name> or app/shared/address-forms/components/<form-name>

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; 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).

The Address Form as an Example of a Reusable Form

How to Use the formly-address-form Component

The following steps describe how to use the formly-address-form component on your form (see also the example below):

Container component:

  1. Create a FormGroup. It will be populated with an address control.

Container template:

  1. Add a <ish-formly-address-form> component to your template
  2. Pass your FormGroup via the parentForm input.
  3. Optional: Define whether you want to display business customer addresses via the businessCustomer input.
  4. Optional: Define whether you want to have the address form pre-filled via the prefilledAddress input.

How to Create a New Country Specific Form

Use the address-form-configuration (or shortcut afc) schematic with your desired countryCode parameter.
This will create a new configuration under src/app/shared/formly-address-forms/configurations and register it in the formlyAddressFormsModule.
An empty example configuration looks like this:

...

@Injectable()
export class AddressFormEXConfiguration extends AddressFormConfiguration {
  countryCode = 'EX';

  constructor() {
    super();
  }

  getModel(model: Partial<Address> = {}): Partial<Address> {
    return {
      ...model,
    };
  }

  getFieldConfiguration(): FormlyFieldConfig[] {
    return [];
  }
}
  • getFieldConfiguration and getModel will automatically be called by the formly-address-form component when a new country is selected. They are used to populate the address form. The businessCustomer attribute will be set automatically, based on what you passed to the formly-address-form. You can use it to adjust the configuration and model.

  • Define the field configuration in getFieldConfiguration.

  • Define the model for the country form in getModel. The method will be called with the previous model to make keeping field values between countries possible.

  • use the addressesFieldConfiguration helper method to quickly reuse common address field configurations (see standardFields).

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets