How to embed Id-Collection-Component

This walkthrough explains how to wire up the id-collection-component to be used in a consumer application. Please ensure the local development machine is configured with the latest Angular6 (see readme for more details). You can download an example application here

Install the component in your project

As with all other component, run the following command to install the id-collection-component into the hosting application:

 npm install @esw/id-collection-component

One point to note is that (at the moment) the id-collection-component uses ngx-bootstrap's datepicker. So it needs to also be added to the project by running the following command:

 yarn add ngx-bootstrap@^2.0.3
 

Configure Module

In the module where you need to gain access to the component, import the IdCollectionModule and call the static forRoot() with configuration for the library. The following is an example of implementation (app generated using angular-cli default template):

import { BrowserModule } from  '@angular/platform-browser';
import { NgModule } from  '@angular/core';
import { FormsModule } from  '@angular/forms';
import { AppComponent } from  './app.component';
import { IdCollectionModule, IdCollectionModuleConfig } from  'id-collection-component';

const config: IdCollectionModuleConfig = {
    debug: true,
    env: 'DEV'
};

@NgModule({
    declarations: [ AppComponent ],
    imports: [ IdCollectionModule.forRoot(config), BrowserModule, FormsModule ],
    providers: [ ],
    bootstrap: [ AppComponent ]
})
export  class AppModule { }

The ICollectionModuleConfig allows us to specify some global configuration for the id-collection-component. The configuration is as follows:

| Property | Type | Description | |--|--|--| | debug | boolean | whether this is a debug version or not, enabling simply adds all the console.log outputs to the running component - useful when debugging issues and for info. | | env | string | Can be as follows: 'DEV', 'CI', 'TEST', 'PREPROD', 'PROD' - simply changes the api endpoint the component points at. |

Embed Component

Now we can embed our id-collection-component in an html template as follows:

<esw-idcollection></esw-idcollection>

Contents can be loaded by setting either the orderGuid property OR setting brandCountry property. Contents will automatically be loaded (this can be executed from code in the .ts file if you reference the component as well)

 <esw-idcollection [orderGuid]="myOrderGuid"></esw-idcollection>

or

<esw-idcollection [brandCountry]="myBrandCountry"></esw-idcollection>

When referencing the component in the hosting component.ts file as follows:

Template...
<esw-idcollection #idcollectcomp></esw-idcollection>

Ts file...
@ViewChild('idcollectcomp') idCollectionComponent: IdCollectionComponent;

It's the responsibility of the hosting app to call the load method of the component. Either using the OrderGuid loadConfigByOrder(orderGuid: string) method or with Brand and Country method loadConfigByBrandCountry(brandCode: string, countryCode: string).

Use OrderGuid if the app knows the Id Collection is required (Offline or PostCheckout method). Use Brand/Country if embedded (Checkout method).

IdCollectionComponent API Reference

The following describes the publicly available members of the component.

Properties

| Name | | Type| Description | |--|--|--|--|--| | acceptedGdprPolicy | | boolean | Whether GDPR policy has been accepted (checkbox checked). | | showSubmitButton| | boolean | Whether to show the submit button on the form (don't show when controlled by the hosting app). | | showGdprButton | | boolean | Whether to show the GDPR checkbox (can be set to accepted using acceptedGdprPolicy model). | | resultType| | ResultType | Enumerable ResultType { notFound = 6, alreadyCollected = 5,expired = 4, serverError = 3, sentSuccessfully = 2, collectionReady = 1, none = 0 } | | form| readonly | FormGroup | Dynamic form for collecting Identity information. | | collectionRules| readonly | CollectionRules | List of ALL collection rules configured (used to determine if Id needs collected in the ShouldCollect method). | | configutation| readonly | IdCollectionConfigService | All configuration values for the component. | | isLoading| readonly | boolean| Set to true when Id Collection form fields are loading from API. | | collectionData | readonly | CountryConfig| Config loaded from API (all fields). | | language | | string| Supported langauges are: 'en' (English), 'ru' (Russuan), 'fr' (French), 'de' (German) - applies to all lables BUT not form field labels and content as it's driven from the stored field data. | | orderGui | | string | Setting this will attempt to load the collection form with the passed in orderGuid. | | brandCountry | | BrandCountry | Setting this will attempt to load the collection form with the passed in brand and country. |

Events

| Name | Returns | Description | |--|--|--| | formRefreshed | config: CountryConfig | When the state of the collection info changes, the refresh is fired. | | formChanged | { isFormValid: Boolean, acceptedGdpr: Boolean, isFormReady: Boolean, formData: string }| Shows the state of the collection form - whether valid (required form fields are collected), whether the GDPR has been accepted, whether the form "isReady" i.e. is valid and GDPR policy accepted. | | languageChanged | string | Component auto detects the language from the loaded country I.e. collecting data for Russia will force the Russian language. Can still be overridden by setting the language property manually after this event has fired. Only applicable to labels (such as field required, GDPR text and submit button). |

Methods

| Name | Params | Returns | Description | |--|--|--|--| | loadConfigByOrder | orderGuid: string | void | Load fields using OrderGuid (OrderIdCollection record exists). | | loadConfigByBrandCountry| brandCode: string, countryCode: string | void| Load fields using Brand and Country (no OrderIdCollection record exists). | | submitIdCollection| orderGuid (optional) | { success: boolean;message: string; collectionId: string; error: any; result: any; } | Submit the form data to the Id Collection API - when the form is generated using Brand/Country instead of OrderGuid, then the guid of the newly created order must also be passed (this is because no order will exist as "requires collection" in the Id Collection data store and it must be added during the submit). | | shouldCollect | brandCode: string, countryCode: string | boolean | Checks if a brand and country combination require collection. |