Yireo_LokiCheckoutPostcodeNl

This is an add-on package for adding support for the Postcode NL address validation and autocompletion to the LokiCheckout.

Overview of this module

This module changes the layout of an address form, so that a streetname and city can be determined by entering a postcode and housenumber (plus housenumber addition). Because the Magento core stores the street as multiple streetlines, the fields are renamed by this module: The field street0 is renamed to Streetname, the field street1 is renamed to House Number, the field street2 is renamed to House Number Addition. The field street3 is not handled by this module.

The fields Streetname and City are disabled when autocompletion is enabled.

An additional checkbox Use autocompletion is added to allow customers to disable the Postcode NL lookup. When autocompletion is disabled (HTML attribute disabled), the fields Streetname and City are enabled again.

Thanks Trinos

Portions of this module are shamelessly copied from the Trinos_PostcodeNL module. Thank you, Trinos, for kickstarting this module. Note that this module is not depending on the Trinos module though.

Installation

Install this package via composer (assuming you have setup the composer.yireo.com repository correctly already):

composer require yireo/magento2-loki-checkout-postcode-nl

Next, enable this module:

bin/magento module:enable Yireo_LokiCheckoutPostcodeNl

Basic configuration

Configure the Postcode NL settings via the backend (Store > Configuration > Yireo > Yireo Loki Checkout > Postcode NL) or via the CLI:

magerun2 config:set yireo_loki_checkout/postcode_nl/enable 1
magerun2 config:set yireo_loki_checkout/postcode_nl/api_key YOUR_API_KEY
magerun2 config:set yireo_loki_checkout/postcode_nl/api_secret YOUR_API_SECRET

In the backend, you can also validate the credentials right away via the button Validate API credentials.

Dealing with streetlines

We recommend you to set the configuration value customer/address/street_lines to be 3.

If the configuration value customer/address/street_lines is 3, both the field House Number and House Number Addition are taken into account when dealing with the Postcode NL autocompletion. When there are multiple options for the housenumber addition, the House Number Addition changes from an input field to a select field. When there are no options to choose from, you can also disable the field itself by setting the configuration option Disable Empty House Number Addition to Yes. Likewise, the configuration option Require Housenumber to be Numeric can be enabled to force the value of the field House Number to be numeric.

If the configuration value customer/address/street_lines is 2, the field House Number Addition is never shown. Instead, the value of House Number allows for adding the addition as well (like: 10A). Here, it is assumed that the numerical prefix is the value for the house number (10) and the remainder is the addition (A). The configuration option Require Housenumber to be Numeric has no effect at this moment.

Optimize address templates

Because this module assumes that the streetname, housenumber and housenumber addition are stored as separate street lines, the address template (so, the configuration option with path customer/address_templates/html) is best changed. The following is identical to the default value, but with HTML <br/> elements removed:

{{depend prefix}}{{var prefix}} {{/depend}}{{var firstname}} {{depend middlename}}{{var middlename}} {{/depend}}{{var lastname}}{{depend suffix}} {{var suffix}}{{/depend}}{{depend firstname}}<br />{{/depend}}
{{depend company}}{{var company}}<br />{{/depend}}
{{depend street1}}{{var street1}}{{/depend}}
{{depend street2}}{{var street2}}{{/depend}}
{{depend street3}}{{var street3}}{{/depend}}
{{depend street4}}{{var street4}}{{/depend}}<br/>
{{if city}}{{var city}},  {{/if}}{{if region}}{{var region}}, {{/if}}{{if postcode}}{{var postcode}}{{/if}}<br />
{{var country}}<br />
{{depend telephone}}T: <a href="tel:{{var telephone}}">{{var telephone}}</a>{{/depend}}
{{depend fax}}<br />F: {{var fax}}{{/depend}}
{{depend vat_id}}<br />VAT: {{var vat_id}}{{/depend}}

Debugging

When the configuration option Debug is enabled, a new block is shown in the checkout (with yellow background). The autocompletion state (saved to the checkout session) is shown.

Possible errors are shown as well. For instance Housenumber addition is not available: A [street1, street2] would tell you that a specific local error is shown for the components street1 and street2.

The raw API data show the response from the Postcode NL API.

CLI usage

This module also comes with a simple CLI command to check for specific addresses:

bin/magento loki-checkout:postcode-nl:check 1000AA 1 A

Support

For getting support, create an Issue under the following project URL:

https://gitlab.yireo.com/loki-checkout/Yireo_LokiCheckoutPostcodeNl