@mutt/widget-addresslookup

Mutt Forms Widget - Address Lookup

Introduction

Mutt Forms Vue widget for Address lookup.

It is designed to be integrated with Loqate.

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
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 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

"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:

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 before making a pull request.