npm package: @mutt/widget-addresslookup
Description: Mutt Forms Widget - Address Lookup
Author: Andy Pattenden
Latest version: 1.0.1

# Mutt Forms Widget - Address Lookup

## Introduction

[Mutt Forms Vue](https://github.com/boughtbymany/mutt-forms-vue) widget for Address lookup.

It is designed to be integrated with [Loqate](https://www.loqate.com/).

## Installation/Usage

The Mutt Address Lookup widget is assigned to the postcode field primarily but has the power to populate other address fields in the form based on the APi response from the address lookup. For that reason, we need to map out the field that will need to be prepopulated by the API response data.

The `addressLookup` options accept the following properties:

| Property                     | Type   | Required | Default                                                                                  | Description                                                    |
|------------------------------|--------|----------|------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| `key`                        | String | true     | null                                                                                     | API access key                                                 |
| `elements`                   | Object | true     | null                                                                                     | A list of objects defining the elements to be handled          |
| `countries`                  | String | false    | UK                                                                                       | A comma separated list of ISO country codes to search against. |
| `postcodePattern`            | RegExp | false    | /^([A-Za-z][A-Ha-hJ-Yj-y]?[0-9][A-Za-z0-9]? ?[0-9][A-Za-z]{2}|[Gg][Ii][Rr] ?0[Aa]{2})$/i | Regex pattern to be used to match against the postcode.        |
| `placeholder`                | String | false    | Enter a postcode                                                                         | Placeholder text for the search field.                         |
| `requiredErrorMessage`       | String | false    | Please enter a valid UK postcode                                                         | Message displayed when postcode field is empty                 |
| `invalidPatternErrorMessage` | String | false    | Please enter a valid UK postcode                                                         | Message displayed when postcode does not match pattern         |


Each element object takes the following parameters:

| Property                     | Type   | Required | Default                                                                                  | Description                                                    |
|------------------------------|--------|----------|------------------------------------------------------------------------------------------|----------------------------------------------------------------|
|`element`|String|true|null|The field name
|`mode`|String, Number (DEFAULT or 8, NONE or 3, POPULATE or 0, PRESERVE or 4, SEARCH or 1)|true|null|The action on the field
|`field`|String|true|null|The Address Lookup service field name to map to the element

>A comprehensive list of fields returned by PCA is available [here](https://www.loqate.com/resources/support/setup-guides/quick/?rd=pca#field_typesa)
Please note that field names may vary depending on version, looking at the XHR response is your best bet.

Usually, you would set `postcode` mode as `SEARCH` and the other fields as `POPULATE`.

### Complete Example

```JSON
"field_name": {
  "widget": "address-lookup",
  "addressLookup": {
    "key": "<provider key>",
    "countries": "UK,SWE",
    "postcodePattern": "^(([A-Za-z][A-Ha-hJ-Yj-y]?[0-9][A-Za-z0-9]? ?[0-9][A-Za-z]{2}|[Gg][Ii][Rr] ?0[Aa]{2})|(\\d{3}\\s?\\d{2}))$",
    "placeholder": "Please enter a UK or Swedish postcode",
    "requiredErrorMessage": "The postcode field is required",
    "invalidPatternErrorMessage": "Please enter a valid UK or Swedish postcode",
    "elements": [{
        "mode": "SEARCH",
        "element": "postcode",
        "field": "PostalCode"
      },
      {
        "mode": "POPULATE",
        "element": "line1",
        "field": "Line1"
      },
      {
        "mode": "POPULATE",
        "element": "line2",
        "field": "Line2"
      },
      {
        "mode": "POPULATE",
        "element": "city",
        "field": "City"
      },
      {
        "mode": "POPULATE",
        "element": "county",
        "field": "Province"
      },
      {
        "mode": "POPULATE",
        "element": "country",
        "field": "CountryName"
      },
      {
        "mode": "POPULATE",
        "element": "country_code",
        "field": "CountryIso2"
      }
    ]
  }
}
```

Add the Mutt widget as a global component:

```javascript
import Mutt from 'mutt-forms'
import MuttVue from 'mutt-forms-vue'
import MuttAddressLookup from '@mutt/widget-addresslookup'

Vue.use(MuttVue, {
  plugins: {
    MuttAddressLookup
  }
})

new Vue({
  render: h => h(APP),
}).$mount('#app')
```

## Contributing

Please make sure to read the [Contributing Guide](https://github.com/mutt-forms/widget-addresslookup/.github/CONTRIBUTING.md) before making a pull request.