Download the PHP package addressfinder/module-magento2 without Composer

AddressFinder for Magento 2

The AddressFinder module for Magento 2 allows you to find verified Australian and New Zealand addresses with an intuitive, search-as-you-type interface.

1. Installation

The module may be installed one of two ways:

1. Composer (recommended)
2. Manual

1.1 Via Composer

To install the module via Composer, from the root directory of your Magento installation:

This will automatically fetch the latest compatible version of the module available to your Magento installation. From the root directory of your Magento installation:

1.2 Install manually

To install the module manually, download the source code for the latest compatible version of the module:

Extract the .zip / .tar.gz you have downloaded. Copy the contents of the top-level folder that was created during extraction into your Magento store in the following location (you must create these folders manually):

After copying the contents into this location, you should see a structure containing (but not limited to) the following files/folders:

From the root directory of your Magento installation:

1.3 Production considerations

Although outside the scope of installing this module, if you are running your Magento store in a production environment, you should run the Magento code compiler and deploy static files:

2. Updating

The process for updating the module depends on whether you have installed it via Composer or manually.

2.1 Via Composer

To update the module via Composer, from the root directory of your Magento installation:

If you are running your Magento store in a production environment, refer to Section (1.3) Production Considerations.

2.2 Update manually

To update the module manually, referring to the instructions in Section (1.2) Install Manually to download the latest compatible version and copy the files into your Magento codebase. After you have copied these files in, simply upgrade the extension:

If you are running your Magento store in a production environment, refer to Section (1.3) Production Considerations.

3. Configuring the module

The module's settings are controlled within Stores -> Configuration -> Services -> AddressFinder.

Most settings in Magento 2 are guarded with sensible defaults. To customise settings, you'll need to uncheck the use system value for any settings you would like to customise.

3.1 Basic functionality

To get the module functioning in its most basic form, you'll need to:

1. Change Enabled to Yes.
2. Sign up for a licence key for Australia or New Zealand and enter this in the License field.

3.2 Customisation features

1. Depending on the theme your Magento store has, you may need to configure the Default Search Country if your checkout has no country selector.
2. AddressFinder functions across many forms throughout Magento. The default is to enable it in all supported forms, however you may restrict this with the Enable Specific Forms setting.
3. Turning on Debug Mode will print debug messages from the AddressFinder JavaScript widget to the browser's console.
4. You may pass custom Widget Options to the JavaScript widget. This must be a JSON object valid for Australia or New Zealand.

4. Forms

The AddressFinder module is installed within Magento by attaching forms. Out of the box, we support the following frontend forms:

1. Checkout billing address
2. Checkout shipping address
3. Customer address book

In addition, we support the following admin forms:

1. Order billing address
2. Order shipping address

4.1 Adding a new form (advanced)

Of course, you may wish to add support for a new form. Luckily, this process is fairly straightforward, however a level of Magento development knowledge is assumed.

Important: All of the examples to follow will assume we'll be working with a module called Acme_CustomForm.

4.1.1 Module creation

You'll firstly need your own module create your own module. Begin by creating the following folder structure:

Create a component registration file at app/code/Acme/CustomForm/registration.php:

And add a module declaration file at app/code/Acme/CustomForm/etc/module.xml:

4.1.2 Event observers

Within your module, you'll need to create event observers that'll allow us to add our custom forms to the AddressFinder module. We'll create a frontend form for brevity's, however the process is almost identical for admin forms.

Begin by creating an events file at app/code/Acme/CustomForm/etc/events.xml:

4.1.3 Form implementation

You'll notice we referred to two new classes within our event observers. We need to implement these classes.:

1. The first class will be used to define the form
2. The second class will add the ability to restrict form selection in the admin. The second class is optional; only required if you wish to restrict forms instead of showing all.

Start by creating the form declaration at app/code/Acme/CustomForm/Observer/FormConfig/Frontend/AddStoreLocator.php:

Now we've added the form, we can optionally add the ability to restrict form selection to this new form within the admin. By default, all configured forms are enabled, however the user has the ability to restrict this list in the admin.

In order to add our new form to this list, create app/code/Acme/CustomForm/Observer/Config/Source/Frontend/StoreLocator.php:

Congratulations! You have now configured up a new form for your store selector to integrate with AddressFinder. 🎉

5. Debugging JavaScript widget

To debug the JavaScript widget within your Magento store, pull up your browser's JavaScript console and type:

This will reinitialise the widget, with the debug flag set to true, so you can see console logs from the @addressfinder/addressfinder-webpage-tools npm package.

This works in all modern browsers (and IE11 💀)