{"id":3042,"date":"2021-04-20T20:29:27","date_gmt":"2021-04-20T23:29:27","guid":{"rendered":"https:\/\/www.magenteiro.com\/blog\/?p=3042"},"modified":"2022-03-01T02:45:05","modified_gmt":"2022-03-01T05:45:05","slug":"campo-endereco-checkout-tutorial","status":"publish","type":"post","link":"https:\/\/www.magenteiro.com\/blog\/magento-2\/campo-endereco-checkout-tutorial\/","title":{"rendered":"Novo campo de endere\u00e7o no checkout – Passo a passo"},"content":{"rendered":"\n

Para se fazer um pedido no Magento \u00e9 preciso informar um endere\u00e7o de cobran\u00e7a durante o processo de checkout. Se estiver realizando uma compra que exija que um ou mais produtos sejam entregues, um endere\u00e7o de entrega tamb\u00e9m \u00e9 solicitado.<\/p>\n\n\n\n

Voc\u00ea pode adicionar novos campos nos formul\u00e1rios de checkout do Magento. Ao longo deste artigo veremos como adicionar um novo campo no formul\u00e1rio de endere\u00e7o de entrega e\/ou de cobran\u00e7a. <\/p>\n\n\n\n

Para fins deste exemplo, vamos criar um novo campo de endere\u00e7o chamado “Refer\u00eancia para Entrega”.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Para fazer isso voc\u00ea precisar\u00e1:<\/p>\n\n\n\n

  1. Adicionar o campo no Layout<\/a><\/li>
  2. Adicionar um mixin JavaScript para modificar o que est\u00e1 sendo enviado<\/a><\/li>
  3. Carregar o mixin<\/a><\/li>
  4. Adicionar o campo no Model de endere\u00e7o<\/a><\/li>
  5. Acessar o valor que est\u00e1 sendo enviado no lado do servidor<\/a><\/li>
  6. Conclus\u00e3o<\/a><\/li>
  7. M\u00f3dulo final<\/a><\/li><\/ol>\n\n\n\n

    Adicionando campo no LayoutProcessor<\/h2>\n\n\n\n

    Tanto os campos de endere\u00e7o de cobran\u00e7a quanto os de entrega s\u00e3o gerados dinamicamente. Isto \u00e9, atrav\u00e9s de classes PHP que injetam estes campos no m\u00e9todo \\Magento\\Checkout\\Block\\Checkout\\LayoutProcessor::process<\/code>. <\/p>\n\n\n\n

    Sendo assim, a melhor forma para se injetar um novo campo neste m\u00e9todo \u00e9 atrav\u00e9s do uso de Plugins – um componente comum no Magento 2, e amplamente explicado no Magento 2: O Curso<\/a>.<\/p>\n\n\n\n

    O trecho de c\u00f3digo abaixo pode ser usado num Plugin do tipo before<\/em> para o m\u00e9todo acima.<\/p>\n\n\n\n

    <?php\n\/\/ ...\n    \/**\n     * @param \\Magento\\Checkout\\Block\\Checkout\\LayoutProcessor $subject\n     * @param array                                            $jsLayout\n     *\n     * @return array[]\n     *\/\n    public function beforeProcess(\\Magento\\Checkout\\Block\\Checkout\\LayoutProcessor $subject, $jsLayout)\n    {\n        $customAttributeCode = 'referencia_entrega';\n        $customField = ['component'                         => 'Magento_Ui\/js\/form\/element\/abstract',\n                        'config'                  => [\/\/customScope \u00e9 usado para agrupar elementos em um form simples\n                                                      \/\/ (assim eles podem ser validados separadamente)\n                                                      'customScope' => 'shippingAddress.custom_attributes',\n                                                      'customEntry' => null,\n                                                      'template'    => 'ui\/form\/field',\n                                                      'elementTmpl' => 'ui\/form\/element\/input',\n                                                      'tooltip'     => [\n                                                          'description' => 'Usado pelo servi\u00e7o de entrega',\n                                                          ],],\n                        'dataScope'                         => 'shippingAddress.custom_attributes'\n                            . '.' . $customAttributeCode,\n                        'label'                             => 'Refer\u00eancia para Entrega',\n                        'provider'                          => 'checkoutProvider',\n                        'sortOrder'                         => 70,\n                        'validation'                        => ['required-entry' => false],\n                        'options'                           => [],\n                        'filterBy'                          => null,\n                        'customEntry'                       => null,\n                        'visible'                           => true,\n                        'value'                             => '' \/\/ valor padr\u00e3o\n        ];\n\n        $jsLayout['components']['checkout']['children']['steps']['children']['shipping-step']['children']['shippingAddress']['children']['shipping-address-fieldset']['children'][$customAttributeCode]\n            = $customField;\n\n        return [$jsLayout];\n    }\n\n<\/pre>\n\n\n\n
    No exemplo acima, adicionamos o campo de “Refer\u00eancia de endere\u00e7o” no endere\u00e7o de entrega. Fizemos isso adicionando o campo na propriedade customAttributes<\/code> do Magento_Checkout\/js\/model\/new-customer-address.js<\/code>, que \u00e9 um objeto que lista os atributos de endere\u00e7o pr\u00e9-definido e faz a associa\u00e7\u00e3o com o atributo correspondente do lado do servidor usando a interface \\Magento\\Quote\\Api\\Data\\AddressInterface<\/code>.<\/p>\n\n\n\n
    A propriedade customAttributes foi desenhada para conter atributos de endere\u00e7o do tipo EAC e relacionada com o m\u00e9todo \\Magento\\Quote\\Model\\Quote\\Address\\CustomAttributeListInterface::getAttributes<\/code>. O exemplo acima vai lidar automaticamente com a grava\u00e7\u00e3o do atributo dentro do local storage no frontend da loja. N\u00e3o \u00e9 legal?<\/p>\n\n\n\n
    Alternativa: Usando Inje\u00e7\u00e3o de Depend\u00eancia<\/h3>\n\n\n\n
    Opcionalmente, ao inv\u00e9s de adicionar um Plugin, voc\u00ea pode fazer uso de Inje\u00e7\u00e3o de Depend\u00eancia<\/a>. Para fazer desta forma, adicione o LayoutProcessor<\/code> (que adiciona um campo personalizado de endere\u00e7o \u00e0 classe de formul\u00e1rio de endere\u00e7o) dentro do diret\u00f3rio <seu_modulo>\/Block\/Checkout<\/code>. A classe deve implementar \\Magento\\Checkout\\Block\\Checkout\\LayoutProcessorInterface<\/code>. Use o c\u00f3digo acima na sua implementa\u00e7\u00e3o de \\Magento\\Checkout\\Block\\Checkout\\LayoutProcessorInterface::process()<\/code> na sua classe.<\/p>\n\n\n\n
    Depois \u00e9 s\u00f3 adicionar o LayoutProcessor na lista de “processors”, especificando o seguinte:<\/p>\n\n\n\n
    <type name=\"Magento\\Checkout\\Block\\Onepage\">\n        <arguments>\n            <argument name=\"layoutProcessors\" xsi:type=\"array\">\n                <item name=\"%nome_unico%\" xsi:type=\"object\">%seu\\modulo\\seu\\LayoutProcessor%<\/item>\n            <\/argument>\n        <\/arguments>\n<\/type>\n<\/pre>\n\n\n\n
    Onde %nomeunico% e %seu\\modulo\\seu\\LayoutProcessor% devem ser trocados por valores reais, de acordo com aqueles definidos no <seu_modulo>\/etc\/frontend\/di.xml<\/code>.<\/p>\n\n\n\n
    Adicione um mixin JavaScript<\/h2>\n\n\n\n
    Mixins<\/em> s\u00e3o como Plugins para JavaScript no Magento. Neste exerc\u00edcio eles nos permitir\u00e3o mudar o comportamento do componente respons\u00e1vel pelo envio de dados do formul\u00e1rio.<\/p>\n\n\n\n
    No seu m\u00f3dulo, defina um mixin<\/em> como um m\u00f3dulo AMD separado, que retorna um m\u00e9todo (callback). Adicione o mixin<\/em> em qualquer lugar em <seu_modulo>\/view\/frontend\/web<\/code>. N\u00e3o h\u00e1 requisitos ou restri\u00e7\u00f5es para o nome dele.<\/p>\n\n\n\n
    O c\u00f3digo abaixo \u00e9 um exemplo de mixin<\/em> para mudar o comportamento de Magento_Checkout\/js\/action\/set-shipping-information<\/code>, que \u00e9 o componente respons\u00e1vel pelo envio dos dados do formul\u00e1rio entre os passos de cobran\u00e7a e entrega.<\/p>\n\n\n\n
    \/*jshint browser:true jquery:true*\/\n\/*global alert*\/\ndefine([\n    'jquery',\n    'mage\/utils\/wrapper',\n    'Magento_Checkout\/js\/model\/quote'\n], function ($, wrapper, quote) {\n    'use strict';\n\n    return function (setShippingInformationAction) {\n\n        return wrapper.wrap(setShippingInformationAction, function (originalAction) {\n            var shippingAddress = quote.shippingAddress();\n            if (shippingAddress['extension_attributes'] === undefined) {\n                shippingAddress['extension_attributes'] = {};\n            }\n\n            var attribute = shippingAddress.customAttributes.find(\n                function (element) {\n                    return element.attribute_code === 'referencia_entrega';\n                }\n            );\n\n            shippingAddress['extension_attributes']['referencia_entrega'] = attribute.value;\n\n            \/\/ chama o m\u00e9todo original ('Magento_Checkout\/js\/action\/set-shipping-information')\n            return originalAction();\n        });\n    };\n});\n<\/pre>\n\n\n\n
    Ao adicionar um campo no endere\u00e7o de cobran\u00e7a, voc\u00ea deve modificar o comportamento de Magento_Checkout\/js\/action\/place-order<\/code> ou Magento_Checkout\/js\/action\/set-payment-information<\/code> dependendo do momento que voc\u00ea deseja passar o valor do campo personalizado para o servidor. Um exemplo de um mixin<\/em> que modifica um destes componentes pode ser visto no place-order-mixin.js<\/a> do m\u00f3dulo Magento_CheckoutAgreements<\/code>.<\/p>\n\n\n\n
    Carregue o seu mixin<\/h2>\n\n\n\n
    Para registrar o mixin<\/em> que acabamos de criar, precisamos inserir o conte\u00fado abaixo no arquivo <seu_modulo>\/view\/frontend\/requirejs-config.js<\/code>:<\/p>\n\n\n\n
    var config = {\n    config: {\n        mixins: {\n            'Magento_Checkout\/js\/action\/set-shipping-information': {\n                'Magenteiro_CampoEndereco\/js\/referencia-endereco-mixin': true\n            }\n        }\n    }\n};\n<\/pre>\n\n\n\n
    No meu caso, o nome que dei para meu mixin<\/em> no passo anterior foi referencia-endereco-mixin.js<\/code>. Altere isso e o nome do m\u00f3dulo de acordo com sua necessidade.<\/p>\n\n\n\n
    Adicionar o campo no Model<\/h2>\n\n\n\n
    Para fazer o Model<\/em> de endere\u00e7o enxergar o nosso atributo no backend (lado do servidor), precisamos adicionar o arquivo extension_attributes.xml<\/code> em <seu_modulo>\/etc\/<\/code>.<\/p>\n\n\n\n
    Veja o exemplo:<\/p>\n\n\n\n
    <?xml version=\"1.0\"?>\n<config xmlns:xsi=\"http:\/\/www.w3.org\/2001\/XMLSchema-instance\" xsi:noNamespaceSchemaLocation=\"urn:magento:framework:Api\/etc\/extension_attributes.xsd\">\n    <extension_attributes for=\"Magento\\Quote\\Api\\Data\\AddressInterface\">\n        <attribute code=\"referencia_entrega\" type=\"string\" \/>\n    <\/extension_attributes>\n<\/config><\/pre>\n\n\n\n
    Lembre-se de apagar o diret\u00f3rio generated\/code<\/code> quando fizer o setup:di:compile<\/code>. Novos m\u00e9todos ser\u00e3o adicionados em generated\/code\/Magento\/Quote\/Api\/Data\/AddressExtension.php<\/code>.<\/p>\n\n\n\n
    Acessando o valor do lado do servidor<\/h2>\n\n\n\n
    Se voc\u00ea seguiu os passos anteriores, o seu atributo j\u00e1 est\u00e1 dispon\u00edvel no backend, pois o Magento gerou novamente a interface de endere\u00e7o com o novo elemento.<\/p>\n\n\n\n
    Voc\u00ea pode obter esses valores quando cria uma nova inst\u00e2ncia de Magento\/Quote\/Api\/Data\/AddressInterface.php<\/code>.  Veja um exemplo simples:<\/p>\n\n\n\n
    <?php\n\n\/\/ ... \/\/\n\nuse Magento\\Checkout\\Api\\Data\\ShippingInformationInterface;\nuse Magento\\Framework\\View\\Element\\Template;\nuse Magento\\Framework\\View\\Element\\Template\\Context;\n\nclass MyBlock extends Template {\n\n    \/**\n     * @var ShippingInformationInterface\n     *\/\n    private $_addressInformation;\n\n    \/**\n     * @param Context $context\n     * @param ShippingInformationInterface $addressInformation\n     * @param array $data\n     *\/\n    public function __construct(\n        Context $context,\n        ShippingInformationInterface $addressInformation,\n        array $data = []\n    ) {\n        $this->_addressInformation = $addressInformation;\n        parent::__construct($context, $data);\n    }\n\n    \/**\n     * Get custom Shipping Charge\n     *\n     * @return String\n     *\/\n    public function getShippingCharge()\n    {\n        $extAttributes = $this->_addressInformation->getExtensionAttributes();\n        return $extAttributes->getReferenciaEndereco(); \/\/pega atributo personalizado.\n    }\n}\n<\/pre>\n\n\n\n
    <\/p>\n\n\n\n
    Conclus\u00e3o e ressalvas<\/h2>\n\n\n\n
    O exemplo acima mostrou como adicionar um novo campo de endere\u00e7o ao nosso checkout Magento.<\/p>\n\n\n\n
    Fizemos isso usando extension attributes<\/em>, um recurso novo implementado no Magento 2. Ele nos possibilita inserir novos e (nem sempre) complexos atributos \u00e0 interfaces como as de produto, cliente, endere\u00e7o, etc.<\/p>\n\n\n\n
    No entanto, um extension_attribute<\/code> n\u00e3o<\/strong> \u00e9 persistido na base de dados nem vis\u00edvel no admin por padr\u00e3o. Voc\u00ea pode usar esta abordagem do jeito que est\u00e1 aqui para algum tipo de integra\u00e7\u00e3o ou regra de neg\u00f3cio que n\u00e3o precise de persist\u00eancia no banco.<\/p>\n\n\n\n
    Se ter este valor no banco e eventualmente exibido no admin da loja \u00e9 um pr\u00e9-requisito para sua necessidade, voc\u00ea ent\u00e3o precisar\u00e1 implementar um outro Plugin para salvar estes valores por l\u00e1 em novas colunas ou tabelas.<\/p>\n\n\n\n
    Quem sabe n\u00e3o abordamos isto em outro artigo. Comente!<\/p>\n\n\n\n
    Refer\u00eancia: Documenta\u00e7\u00e3o Oficial (em Ingl\u00eas)<\/a><\/p>\n\n\n\n
    M\u00f3dulo final (do exemplo)<\/h2>\n\n\n\n
    Se desejar, fa\u00e7a download do nosso m\u00f3dulo do exemplo acima. Basta preencher o form abaixo.<\/p>\n\n\n\n