@snsw/var-nswpoint-angular

SNWS Address Entry

SNSW Address entry provides a universal module to handle front-end address data collection.

This entry component main components are:

• snsw-address-entry-v1 - uses snws point v1 api endpoint, with snsw point javascript autocomplete
• snsw-address-entry-v2 - uses snsw point v2 api endpoint, with angular material autocomplete

Setup

#####Add to package.json:

npm install @snsw/var-nswpoint-angular --save

yarn add @snsw/var-nswpoint-angular

#####Importing it in module file: In an Angular module add:

VarNswpointAngularModule.forRoot({
  nswPointV1ApiKey: environment.nswPointAddressValidation.apiKey
  nswPointV2ApiKey: environment.nswPointAddressValidation.apiKeyv2
  adminBoundariesEndPoint: environment.nswPointAddressValidation.adminBoundariesEndPoint
}),

• Depending on the version used, given API key must be present.

• adminBoundariesEndPoint - is required ONLY if you are using v1 and want to get LGA(Local Gov Area) data from nsw point

#####Using it in a component Example use in template driven form .html:

<fieldset ngModelGroup="residentialAddress">
    <snsw-address-entry-v1
      label="Residential address"
      [populateAddress]="customer?.residentialAddress"
      [addressConfigOverride]="configOverride"
      (addressChange)="onAddress($event)"
      (hiddenFormControls)="hiddenFormControls = $event"
    >
    </snsw-address-entry-v1>
</fieldset>

Example use in Reactive driven form .html

<div formGroupName="businessAddress">
  <snsw-address-entry-v2
    label="Address of work location"
    [populateAddress]="applicationDetails?.businessAddress"
    [addressConfigOverride]="addressConfigOverride"
    (hiddenFormControls)="hiddenFormControls = $event"
  >
  </snsw-address-entry-v2>
</div>

Defaults and inputs

• @Input() populateAddress: Address; // is the existing address object, also used to prefill
• @Input() label: string; // the label of the input section
• @Input() placeholder: string; // address lookup search input placeholder
• @Input() modifierClass: string; // this string is added to all of the input elements
• @Input() allowManualEntry = true; // Allow manual entry, toggles the show of the manual entry button
• @Input() searchInputHelpText = Start typing and select your address from the results that appear.<br> If you are unable to locate your address please enter it manually.; // Default text under the address component in gray
• @Input() addressConfigOverride: AddressConfig = {};
• @Output() addressChange: EventEmitter = new EventEmitter();
• @Output() hiddenFormControls: EventEmitter<string[]> = new EventEmitter<string[]>(); // Returns the names of hidden formControlNames

#####Address config interface

export interface AddressConfig {
  poBoxType?: AddressConfigItem;
  poBoxNumber?: AddressConfigItem;
  unitNumber?: AddressConfigItem;
  streetNumber?: AddressConfigItem;
  street?: AddressConfigItem;
  streetType?: AddressConfigItem;
  locality?: AddressConfigItem;
  state?: AddressConfigItem;
  postalCode?: AddressConfigItem;
  country?: AddressConfigItem;
  manualLocalGovernmentArea?: AddressConfigItem; 
  debugComponent?: boolean; // this makes the component more verbose, log level is debug
  prefillAddress?: boolean; // Allows to continue with just formattedAddress
  showPostalDeliveryFields?: boolean; // if true, shows PO box type and number, this mode turns off street info
  addLocalGovernmentAreaData?: boolean; // Used to toggle adding additional address data: lgaAbbreviatedName, lgaName, lgaPid
  addMetadataObjectToAddress?: boolean; // Toggles to add the entire additional address data to Address object on metadata field, addLocalGovernmentAreaData has to be true
  showManualLocalGovernmentAreaSelectBox?: boolean; // If we should allow user to select LGA data manually, addLocalGovernmentAreaData has to be true
  manualLocalGovernmentAreaOptions?: LocalGovernmentArea[]; // Shown LGA options for user manual selection
  allowedState?: StateCode; //Possible statecode StateCode.NSW, StateCode.QLD, etc..
  addressStateFieldAsFreeTextInput?: boolean; // boolean value to determine is manual state selection is an input field
  allFormAdditionalValidators?: ValidatorFn[]; // Additional validators that will be added to the search input formControl
  allFormAdditionalAsyncValidators?: AsyncValidatorFn[]; // Additional async validators that will be added to the search input formControl
  v2?: NswPointV2;
}

export interface AddressConfigItem {
  pattern?: RegExp;
  required?: boolean;
  label?: string;
  additionalValidators?: ValidatorFn[];
  additionalAsyncValidators?: AsyncValidatorFn[];
}

export interface NswPointV2 {
  maxNumberOfResults?: string; // NSW Point Predictive1 API configuration
  addressType?: AddressType; // NSW Point Predictive1 API configuration
  suggestionDataset?: SuggestionDataset; // NSW Point API Predictive1 API configuration 
  startSearchMinLength?: number; // When user types we do query over minimum chracater requirement
  delaySearchStartInMs?: number; // When user types we wait given milliseconds before we do predictive1 query
}

• NSW POINT V2 API docs

#####Default addressConfig

{
    poBoxNumber: { 
        required: true, 
        label: 'Postal delivery number' 
    },
    poBoxType: { 
        required: true, 
        label: 'Postal delivery type' 
    },
    unitNumber: AddressConfigItem { 
        required: true, 
        label: 'Unit number' 
    },
    streetNumber: AddressConfigItem { 
        required: true, 
        label: 'Street number' 
    },
    street: AddressConfigItem { 
        required: true, 
        label: 'Street name' 
    },
    streetType: AddressConfigItem { 
        required: true, 
        label: 'Street type' 
    },
    locality: AddressConfigItem { 
        required: true, 
        label: 'Suburb' 
    },
    state: AddressConfigItem { 
        required: true, 
        label: 'State', 
        pattern: /.+/ 
    },
    postalCode: AddressConfigItem { 
        required: true, 
        label: 'Postal code', 
        pattern: /.+/ 
    },
    country: AddressConfigItem { 
        required: true, 
        label: 'Country' 
    },
    manualLocalGovernmentArea: {
        required: true, 
        label: 'Local Government Area'
    },
    showPostalDeliveryFields: false,
    addLocalGovernmentAreaData: false,
    addMetadataObjectToAddress: false,
    allowedState: undefined,
    v2?: NswPointV2 = {
        maxNumberOfResults?: string = 5;
        addressType?: AddressType = AddressType.ALL;
        suggestionDataset?: SuggestionDataset = SuggestionDataset.ALL;
        startSearchMinLength?: number = 3;
        delaySearchStartInMs?: number = 300;
    }; 
}

Optional metadata Object structure in v1:

"metadata": {
    "coodinates": [
        150.80302439,
        -33.62115592
    ],
    "adminBoundaries": {
        "abs": {
            "mb_2016_code": "10354460000",
            "sa1_2016_main_code": "12404146725",
            "sa2_2016_main_code": "124041467",
            "sa3_2016_code": "12404",
            "sa4_2016_code": "124"
        },
        "comm_electoral": {
            "comm_electoral_pid": "NSW33",
            "comm_electoral_name": "MACQUARIE"
        },
        "lga": {
            "lga_pid": "NSW277",
            "lga_name": "HAWKESBURY CITY COUNCIL",
            "lga_abbreviated_name": "HAWKESBURY"
        },
        "state_electoral": [
            {
                "state_electoral_pid": "NSW143",
                "state_electoral_name": "HAWKESBURY",
                "state_electoral_type": "Legislative Assembly",
                "state_electoral_class_code": "2"
            }
        ]
    }
},

V2 is quite similar but with camel case