Introduction

AFD Postcode Evolution® for Magento 2 is a module that allows you to harness the full power of AFD Software’s Postcode Evolution® web service within your ecommerce store.

Currently the module adds the following functionality:

  • Typeahead style address searching on the following forms:
    • Checkout - Shipping and Billing
    • My Account - Address Management
  • Email address validation using AFD Software's email validation service on the following forms:
    • Checkout - Logged Out
    • Create New Account
    • My Account - Change email address
    • Contact Us
    • Newsletter Signup
  • Phone number validation and masking using AFD Software's phone number validation service on the following forms:
    • Checkout - Shipping and Billing
    • My Account - Address Management
    • Contact Us

In addition our typeahead integration can leverage AFD Software's Censation data set to append valuable geodemographic information to addresses that can be used later for marketing and analysis.

When inputting an address the user can either start typing an address until it appears in the results box or they can type in a postcode. Once a result is selected the fields in the form will be populated with the PAF data of the selected record.

Compatibility

AFD Postcode Evolution® for Magento is currently supported to run on the latest patch of the following Magento minor versions:

  • 2.0.*
  • 2.1.*
  • 2.2.*
  • 2.3.*

Both Community and Enterprise Editions are supported.

Installation and Setup

Composer

  • composer require afd/module-pce
  • php bin/magento setup:upgrade
  • php bin/magento setup:di:compile

Manual Install

  • Download the AFD Magento Extension - download
  • Extract the contents of the file into /app/code in relation to the Magento root directory
  • From the Magento Root folder run the following commands
    • php bin/magento module:enable --clear-static-content Afd_Pce
    • php bin/magento setup:upgrade
  • You may need to log out of the admin panel and log in again

Setup the Module

  • In the admin panel browse to Stores -> Configuration -> AFD Software
  • In the General Settings Tab choose authentication method Serial/Password and enter the serial and password that has been provided by AFD Software support. IMPORTANT - Serial and password should only be used for testing and evaluation purposes. In a production environment an ID and Token are required, these will be provided by AFD support.
  • Go to the checkout, the address search functionality should now be visible on the address forms.

General Settings

Account Settings

Authentication Method

Either serial/password or id/token.

IMPORTANT - Serial and password should only be used for testing and evaluation purposes. In a production environment an ID and Token are required, these will be provided by AFD support.

PCE URL

Unless you are using a custom AFD PCE server this can be left as the default URL.

AFD Serial

Your AFD software serial number.

AFD Password

Your AFD Password

AFD ID

Your AFD ID

AFD Token

Your AFD Token

Typeahead Settings

There are a number of configuration options for the magento extension that allow for customisation of the look, feel, and functionality of the forms.

Field Configuration

Placeholder Text

default - "Start typing your address"

This is the text that appears in the address search box before a user has interacted with it.

Move Country Above Street

default - Yes

Magento forms typically have the country field at the end of the form. As the appearance of the search box is dependent on which country is selected it is usually desirable to make the country field appear before the rest of the address. This setting moves the country field to the top of the address form.

Hide Typeahead Field After Selection

default - Yes

If set to Yes this will hide the address search box once the user has selected their address from the search results.

Enable Search Again Button

default - Yes

If Hide Typeahead Field After Selection is set to Yes then setting this to Yes will show a Search Again button that will reset the address form and once again show the search box.

Markup For Search Again Button

default - "Search again"

The markup for the search again button. By default it is plain text but it can accept HTML.

CSS for search Again Button

CSS rules to be applied to the search again button.

Clear Typeahaed Field After Selection

default - Yes

Setting to yes empties the contents of the search box after an address has been selected.

default - Yes

To create a cleaner and easier to use form this setting hides the address fields until after a result has been selected from the results list.

Enable Manual Entry Button

default - Yes

If Hide Address Fields Before Search has been set to Yes, enabling this will add a manual input button below the search box that when clicked will hide the search box and display the address form. A button will also be added to the address form that when clicked will hide the fields again and show the search box.

Markup for Manual Entry Button

default - "Manually enter address"

The markup for the manual input button. By default it is plain text but it can accept HTML.

Markup for Address Search Button

default - "Search for address"

The markup for the address search button. By default it is plain text but it can accept HTML.

CSS for manual input buttons

CSS rules for both of the manual input buttons.

Hide Empty Address Fields

default - Yes

If enabled, this setting will hide any empty fields from the address form when the result has been selected from the search results list.

Highlight Matching Search Strings in Results

default - Yes

When this setting is enabled, the results in the search results list will be altered so that any part of the result that matches the search query will be highlighted.

Display Postcode Before Address in Results

default - No

When set to Yes, this setting changes the format of the results in the search results list so that the Postcode is at the beginning of the result instead of the end.

Countries for which the Region Field Should be Hidden

default - UK, Isle of Man, Jersey and Guernsey

Region is not a field that is used in the addresses of all countries. The countries selected in this list will not display the region field in the address form.

Automatically Change Countries for Crown Dependencies

default - No

When enabled, if one of the three crown dependencies (Isle of Man, Jersey and Guernsey) are selected, when a result is selected the country will be changed to "United Kingdom". In PAF the name of the crown dependency occupies the "Town" field.

Country Configuration

Which Countries Should Typeahead be Activated On?

default - UK, Isle of Man, Jersey and Guernsey

Countries for which the search functionality should be enabled.

Results Quantity

Maximum Number of Results Returned

default - 5

Few Results Message

default - No

If zero or fewer than maximum number of results are returned, enabling this setting will show a suggestion that the user can manually enter their address by clicking on the button.

Few Results Message Text

default - "Can't see your address? Enter it manually"

The message that is displayed if Few Results Message is enabled.

Reverse Geocoding

This feature is only available for UK and it requires additional services to be enabled on your account. Contact our sales team if you require this service.

Enable Reverse Geocoding

default - No

Whether or not reverse geocoding should be added to the typeahead field.

Only Display on Mobile Devices

default - Yes

The quality of reverse geocoding lookup results are significantly higher on mobile devices that have GPS functionality. When this option is enabled the button will only be displayed on mobile devices.

Button Text

default - Find Address Automatically

This can accept HTML which is useful if an SVG icon is desired. An example of a target itcon is:

<svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1325 1024h-109q-26 0-45-19t-19-45v-128q0-26 19-45t45-19h109q-32-108-112.5-188.5t-188.5-112.5v109q0 26-19 45t-45 19h-128q-26 0-45-19t-19-45v-109q-108 32-188.5 112.5t-112.5 188.5h109q26 0 45 19t19 45v128q0 26-19 45t-45 19h-109q32 108 112.5 188.5t188.5 112.5v-109q0-26 19-45t45-19h128q26 0 45 19t19 45v109q108-32 188.5-112.5t112.5-188.5zm339-192v128q0 26-19 45t-45 19h-143q-37 161-154.5 278.5t-278.5 154.5v143q0 26-19 45t-45 19h-128q-26 0-45-19t-19-45v-143q-161-37-278.5-154.5t-154.5-278.5h-143q-26 0-45-19t-19-45v-128q0-26 19-45t45-19h143q37-161 154.5-278.5t278.5-154.5v-143q0-26 19-45t45-19h128q26 0 45 19t19 45v143q161 37 278.5 154.5t154.5 278.5h143q26 0 45 19t19 45z"></path></svg>

Advanced Options

Enable JavaScript Polyfill

Our Javascript requires the use of Promise which is not natively available in Internet Explorer 11. Enabling this will retrieve a polyfill from polyfill.io. You can safely disable this if you do not need to support IE 11 or you are using your own polyfills.

Email Validation Settings

Email address validation can be activated on the following forms:

  • Checkout - Logged Out
  • Create New Account
  • My Account - Change email address
  • Contact Us
  • Newsletter Signup

Validation occurs when the email control loses focus and has two stages. First, the syntax of the email address is validated, if the syntax is valid a request will be sent to AFD's servers to do a full validation.

While the email address is in an invalid state the submit button of the relevant form will be disabled. Once the email address has been validated the submit button will be enabled.

Below are the various options available for configuring the functionality.

Enable Email Validation

default - No

Global control for email validation.

Email Authentication Settings

Use default authentication settings

default - Yes

If you are using multiple features of this module and have different authentication details for email validation set this to No.

Authentication Method

Either serial/password or id/token.

IMPORTANT - Serial and password should only be used for testing and evaluation purposes. In a production environment an ID and Token are required, these will be provided by AFD support.

PCE URL

Unless you are using a custom AFD PCE server this can be left as the default URL.

AFD Serial

Your AFD software serial number.

AFD Password

Your AFD Password

AFD ID

Your AFD ID

AFD Token

Your AFD Token

Form Settings

Which forms email validation should be enabled on. The following forms can individually have email validation enabled or disabled:

  • My Account - Change Email Address
  • Register Account
  • Logged Out - Checkout
  • Contact Us Form
  • Newsletter Signup - Footer

Field Settings

Invalid Email Message

default - "Please enter a valid email address"

The error message that users will see when they enter an invalid email address.

Phone Validation Settings

Phone number validation can be activated on the following forms:

  • My Account - Add/Edit Address
  • Checkout
  • Contact Us Form

Validation occurs when the phone number control loses focus and has two stages. First, the format of the phone number is validated, if the format is valid for the given country a request will be sent to AFD's servers to do a full validation.

A default country dialling code can be set in the config options. When a user is typing a phone number into the phone control they will not need to add a dialling code for this country, however, if a user prefixes their number with either + or 00 followed by a country code then the country code that is given will be used for validation.

In addition to validation, the module will also mask the phone number so that it appears in the expected format for the given country. For example, 01624811711 will automatically be reformatted to 01624 811 711.

Below are the various options available for configuring the functionality.

Phone Authentication Settings

Use default authentication settings

default - Yes

If you are using multiple features of this module and have different authentication details for phone validation set this to No.

Authentication Method

Either serial/password or id/token.

IMPORTANT - Serial and password should only be used for testing and evaluation purposes. In a production environment an ID and Token are required, these will be provided by AFD support.

PCE URL

Unless you are using a custom AFD PCE server this can be left as the default URL.

AFD Serial

Your AFD software serial number.

AFD Password

Your AFD Password

AFD ID

Your AFD ID

AFD Token

Your AFD Token

Form Settings

Which forms phone validation should be enabled on. The following forms can individually have phone validation enabled or disabled:

  • My Account - Add/Edit Address
  • Checkout
  • Contact Us Form

Field Settings

Default international dialling code

default - "+44"

The default country code for the control. For whatever code is entered here, users will not be required to specify a country code to have their phone number validated.

Must be prefixed with +.

Invalid Phone Message

default - "Please enter a valid phone number"

The error message that users will see when they enter an invalid phone number.

Geodemographic Data

Introduction

This feature is only available in the Enterprise version of Magento

When a user searches for their address using the typeahead control, it is also possible to collect useful geodemographic data from various data sets that AFD makes available.

These data sets include:

  • All standard AFD Postcode Plus data
  • AFD Software's Censation geodemographic data set
  • Occupancy Information
  • Multiple Deprivation Indexes

Access to some of the data sets may incur additional costs, please get in touch with AFD Sales to find out more

This data can be stored as a native Magento [Custom Customer Address Attribute]() that can be used for customer segmentation, filtering and analysis.

Setup

Important This functionality requires that the attributes be setup as Visible on the frontend. While we hide these attributes on the frontend they are still present in the DOM and so potentially can be seen if the user investigates the DOM.

  • In Magento admin go to Stores -> Attributes -> Customer Address
  • Create a new attribute with the following settings:
    • Default Label - The name of the field
    • Attribute Code - The attribute code required (see Appendix A)
    • Show on Storefront - Yes
    • Forms to Use in - Both Forms

The rest of the fields are up to your discretion, depending on how you intend to use the data.

Now when an address is saved on the frontend the details will be visible in the admin panel. The data will be saved to the customer address record and also will be visible on the order view.

The details can now be seen in the order details page in Magento admin.

In addition, if you selected the options, it is possible to filter users according to these attributes like any other Magento "Custom Customer Address Attribute"

Appendix A - Available Additional Fields

Attribute Code Description
afd_organisation Full business name (includes any department)
afd_property Property (building-includes any sub-building).
afd_street Delivery Street (includes any sub-street)
afd_locality Locality (sometimes a village name – in ZipAddress used for Urbanization)
afd_town Postal Delivery Town (or City)
afd_postcode The Royal Mail Postcode for this address (or ZipCode)
afd_town Postal Delivery Town (City)
afd_postcode The Royal Mail Postcode for this address (or Zipcode)
afd_postal_county Royal Mail supplied postal county
afd_abbreviated_postal_county Royal Mail approved abbreviation is used where available for the postal county
afd_optional_county Postal counties including optional ones for most addresses which would otherwise not have a county name.
afd_abbreviated_optional_county Royal Mail approved abbreviation is used where available for the optional county
afd_traditional_county The traditional county name for this postcode
afd_administrative_county The administrative county name for this postcode
afd_dps The Delivery Point Suffix which along with the postcode uniquely identifies the letterbox.
afd_mailsort_code Used for obtaining bulk mail discounts.
afd_udprn Royal Mail Unique Delivery Point Reference Number assigned to this letter box.
afd_just_built AFDJustBuilt - Contains the date of inclusion on PAF for properties thought to be recently built. The date is stored numerically in descending format in the form YYYYMMDD. YYYY is the year, MM is the month and DD is the day. For example 20080304 is 04/03/2008.
afd_country Specifies the name of the country to search for when using International data and returns the name of the country that the result returned was for.
afd_country_iso Specifies the ISO code of the country to search for when using International data and returns the code for the country the result returned was for.
afd_phone STD Code
afd_grid_e Grid Easting as a 6 digit reference
afd_grid_n Grid Northing as a 6/7 digit reference
afd_latitude Latitude representation of Grid Reference in Decimal Format (WGS84)
afd_longitude Longitude representation of Grid Reference in Decimal Format (WGS84)
afd_urban_rural_code Provides a code which indicates if an area is mainly urban or rural and how sparsely populated those area’s are.
afd_urban_rural_name Provides a description which goes along with the UrbanRuralCode.
afd__soa_lower Lower level Super Output Area (Data Zone in Scotland, Super Output Area in Northern Ireland)
afd_soa_middle Middle level Super Output Area (Intermediate Geography in Scotland, not applicable for Northern Ireland).
afd_sub_country_name Provides the devolved or non-UK country name (e.g. England, Scotland, Wales etc.)
afd_ward_code Code identifying the electoral ward for this postcode
afd_ward_name Name identifying the electoral ward for this postcode
afd_authority_code Local/Unitary Authority for this Postcode (same as the start of the ward code).
afd_authority Local / Unitary Authority for this postcode
afd_constituency_code Parliamentary Constituency Code for this postcode
afd_constituency Parliamentary Constituency for this postcode
afd_devolved_constituency_code Devolved Constituency Code for this postcode (currently covers Scotland)
afd_devolved_constituency_name Devolved Constituency Name for this postcode (currently covers Scotland)
afd_eer_code Code identifying the European Electoral Region for this postcode
afd_eer_name Name identifying the European Electoral Region for this postcode
afd_LEACode Code identifying the Local Education Authority for this postcode
afd_lea_name Name identifying the Local Education Authority for this postcode
afd_tv_region ISBA TV Region (not TV Company)
afd_occupancy Indication of the type of occupants of properties found on the selected postcode
afd_occupancy_description Description matching the Occupancy
afd_address_type Indication of the type of property level data to capture to have the full address for a property on the selected postcode.
afd_address_type_description Description matching the Address Type
afd_nhs_code National Health Service Area Code
afd_nhs_name National Health Service Area Name
afd_pct_code National Heath Service Clinical Commisioning Group Code for England (Local Health Board Code in Wales, Community Health Partnership in Scotland, Local Commissioning Group in Northern Ireland, Primary Healthcare Directorate in the Isle of Man)
afd_pct_name Name matching the PCT Code field
afd_censation_code Censation Code assigned to this Postcode
afd_censation_label Provides a handle for the Censation Code
afd_affluence Affluence description
afd_lifestage LifeStage description
afd_additional_census_info Additional information from the Census.