README

Magento 2的AddressFinder模块允许您通过直观的搜索界面找到经过验证的澳大利亚和新西兰地址。

1. 安装

可以通过以下两种方式之一安装模块：

Composer（推荐）
手动

1.1 通过Composer安装

要使用Composer安装模块，请从您的Magento安装根目录开始

composer require addressfinder/module-magento2

这将自动获取适用于您的Magento安装的最新兼容版本。从您的Magento安装根目录开始

bin/magento module:enable AddressFinder_AddressFinder
bin/magento setup:upgrade

1.2 手动安装

要手动安装模块，请下载模块最新兼容版本的源代码

解压缩您下载的.zip / .tar.gz文件。将解压缩过程中创建的顶级文件夹的内容复制到您的Magento商店的以下位置（您必须手动创建这些文件夹）

app/code/AddressFinder/AddressFinder/

将内容复制到该位置后，您应该看到一个包含以下文件/文件夹的结构（但不限于）

app/code/AddressFinder/AddressFinder/Block/
app/code/AddressFinder/AddressFinder/etc/
app/code/AddressFinder/AddressFinder/Model/
app/code/AddressFinder/AddressFinder/registration.php
app/code/AddressFinder/AddressFinder/...

从您的Magento安装根目录开始

bin/magento module:enable AddressFinder_AddressFinder
bin/magento setup:upgrade

1.3 生产注意事项

虽然这超出了安装此模块的范围，但如果您在生产环境中运行您的Magento商店，您应该运行Magento代码编译器和部署静态文件

bin/magento setup:di:compile
bin/magento setup:static-content:deploy

2. 更新

更新模块的过程取决于您是否通过Composer或手动安装。

2.1 通过Composer更新

要从Composer更新模块，请从您的Magento安装根目录开始

composer update addressfinder/module-magento2
bin/magento setup:upgrade

如果您在生产环境中运行您的Magento商店，请参阅（1.3）生产注意事项部分。

2.2 手动更新

要手动更新模块，请参考（1.2）手动安装部分中的说明，下载最新兼容版本的源代码并将文件复制到您的Magento代码库中。复制完这些文件后，只需升级扩展即可

bin/magento setup:upgrade

如果您在生产环境中运行您的Magento商店，请参阅（1.3）生产注意事项部分。

3. 配置模块

模块的设置在 商店 -> 配置 -> 服务 -> AddressFinder 中控制。

大多数设置在Magento 2中都有合理的默认值。要自定义设置，您需要取消选中任何您想要自定义的设置的 使用系统值 选项。

3.1 基本功能

为了使模块以最基本的形式运行，您需要

将启用改为是。
为澳大利亚或新西兰注册许可证密钥，并在 许可证 字段中输入此密钥。

3.2 自定义功能

根据您的Magento商店的主题，如果您在结账页面上没有国家选择器，您可能需要配置 默认搜索国家。
AddressFinder功能遍布于整个Magento的多个形式。默认情况下，它会在所有支持的形式中启用，但您可以通过设置启用特定形式来限制它。
开启调试模式将在浏览器的控制台打印出AddressFinder JavaScript小部件的调试信息。
您可以向JavaScript小部件传递自定义的小部件选项。这必须是一个有效的JSON对象，适用于澳大利亚或新西兰。

4. 表单

AddressFinder模块通过附加表单在Magento中安装。默认情况下，我们支持以下前端表单

结账账单地址
结账收货地址
客户地址簿

此外，我们还支持以下管理表单

订单账单地址
订单收货地址

4.1 添加新的表单（高级）

当然，您可能希望添加对新表单的支持。幸运的是，这个过程相当简单，但是假设您具备一定程度的Magento开发知识。

重要：以下所有示例都将假设我们将使用名为Acme_CustomForm的模块。

4.1.1 模块创建

您首先需要创建自己的模块创建您的模块。首先创建以下文件夹结构

app/code/Acme/CustomForm/
app/code/Acme/CustomForm/etc/
app/code/Acme/CustomForm/Observer/Config/Source/Frontend/
app/code/Acme/CustomForm/Observer/FormConfig/Frontend/

在app/code/Acme/CustomForm/registration.php创建一个组件注册文件

<?php

use \Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(ComponentRegistrar::MODULE, 'Acme_CustomForm', __DIR__);

并在app/code/Acme/CustomForm/etc/module.xml添加一个模块声明文件

<?xml version="1.0"?>

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Acme_CustomForm" setup_version="0.1.0"/>
</config>

4.1.2 事件观察者

在您的模块中，您需要创建事件观察者，这样我们就可以将我们的自定义表单添加到AddressFinder模块中。为了简洁起见，我们将创建一个前端表单，但这个过程与几乎相同，适用于管理表单。

首先在app/code/Acme/CustomForm/etc/events.xml创建一个事件文件

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">

    <!--
        Attach frontend forms
        (to attach admin forms, simply listen to the event named `addressfinder_form_config_admin` instead)
    -->
    <event name="addressfinder_form_config">
        <observer name="acme_store_locator"
                  instance="Acme\CustomForm\Observer\FormConfig\Frontend\AddStoreLocator"/>
    </event>

    <!-- Attach form selector to admin (optional) -->
    <event name="addressfinder_config_source_forms_enabled">
        <observer name="acme_store_locator"
                  instance="Acme\CustomForm\Observer\Config\Source\Frontend\StoreLocator"/>
    </event>

</config>

4.1.3 表单实现

您会注意到在我们的事件观察者中提到了两个新的类。我们需要实现这些类。

第一个类将用于定义表单
第二个类将添加在管理中限制表单选择的能力。第二个类是可选的；只有当您想限制表单而不是显示所有表单时才需要。

首先在app/code/Acme/CustomForm/Observer/FormConfig/Frontend/AddStoreLocator.php创建表单声明

<?php

namespace Acme\CustomForm\Observer\FormConfig\Frontend;

use AddressFinder\AddressFinder\Observer\FormConfig\Base;
use Exception;
use Magento\Framework\Data\Collection;
use Magento\Framework\DataObject;

class AddStoreLocator extends Base
{
    const FORM_ID = 'frontend.store.locator';

    /**
     * @inheritDoc
     *
     * @throws Exception
     */
    protected function addForm(Collection $forms): void
    {
        $forms->addItem(new DataObject([
            // A unique form ID to identify this form within the AddressFinder module
            'id' => self::FORM_ID,

            // A semantic label
            'label' => 'Store Locatork',

            // The selector for where to instantiate the JavaScript widget
            'layoutSelectors' => ['input#street_1'],

            // The country selector that switches the form between AU and NZ
            'countryIdentifier' => 'select[name=country_id]',

            // The search box selector - this is where your users type to trigger the AddressFinder autocomplete
            'searchIdentifier' => 'input#street_1',

            // NZ-specific config
            'nz' => [
                // The value which the `countryIdentifier` is set as to represent NZ
                'countryValue' => 'NZ',

                // Varying element selectors to place the selected address result in
                'elements' => [
                    'address1' => 'input#street_1',
                    'suburb' => 'input#street_2',
                    'city' => 'input[name=city]',
                    'region' => 'input[name=region]',
                    'postcode' => 'input[name=postcode]',
                ],
                'regionMappings' => null,
            ],

            // AU-specific config
            'au' => [
                // The value which the `countryIdentifier` is set as to represent AU
                'countryValue' => 'AU',

                // Varying element selectors to place the selected address result in
                'elements' => [
                    'address1' => 'input#street_1',
                    'address2' => 'input#street_2',
                    'suburb' => 'input[name=city]',

                    // This helper from the base class we extend will allow us to
                    // support free-form state inputs as well as dropdown menus.
                    'state' => $this->getStateMappings('AU')
                        ? 'select[name=region_id]'
                        : 'input[name=region]',
                    'postcode' => 'input[name=postcode]',
                ],

                // State mappings for Australia (if they exist in your Magento installation)
                'stateMappings' => $this->getStateMappings('AU'),
            ],
        ]));
    }
}

现在我们已经添加了表单，我们可以选择性地在管理中添加限制表单选择到这个新表单的能力。默认情况下，所有配置的表单都是启用的，但用户可以在管理中限制这个列表。

为了将我们新的表单添加到这个列表中，创建app/code/Acme/CustomForm/Observer/Config/Source/Frontend/StoreLocator.php

<?php

namespace Acme\CustomForm\Observer\Config\Source\Frontend;

use Acme\CustomForm\Observer\FormConfig\Frontend\AddStoreLocator;
use Exception;
use Magento\Framework\Data\Collection;
use Magento\Framework\DataObject;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

class StoreLocator implements ObserverInterface
{
    /**
     * @inheritDoc
     *
     * @throws Exception
     */
    public function execute(Observer $observer): void
    {
        /** @var Collection $frontend */

        // If you were building an admin form, you'd call `getData('admin')` and append the form to that list
        $frontend = $observer->getEvent()->getData('frontend');

        $frontend->addItem(new DataObject([
            'label' => 'Store Locator',
            'value' => AddStoreLocator::FORM_ID,
        ]));
    }
}

恭喜！您现在已经为您的商店选择器配置了一个新的表单，用于与AddressFinder集成。🎉

5. 调试JavaScript小部件

要调试您的Magento商店中的JavaScript小部件，请打开浏览器的JavaScript控制台并输入

window.addressfinderDebugMode() // Followed by the `return`/`enter` key.

这将重新初始化小部件，并将调试标志设置为true，这样您就可以看到来自@addressfinder/addressfinder-webpage-tools npm包的控制台日志。

这适用于所有现代浏览器（以及IE11 💀）

addressfinder / module-magento2

维护者

详细信息