Crie seu módulo de Auto-Completar endereço

Eis aqui uma ótima oportunidade para iniciarmos nossos estudos sobre módulos no Magento e ainda criarmos uma funcionalidade para auto-completar endereços assim que o cep do cliente for informado no formulário.

Mas não se empolgue muito. É realmente apenas o básico da criação de módulos, com um pouco de ajax com prototype, e uma base de dados desatualizada dos correios.

Porém, é um ótimo ponto de partida para você criar coisas incríveis.

Etapa 1 – O formulário

Vamos começar pela parte mais simples de todo o processo: o formulário de cadastro de endereço.

Neste exemplo faremos a alteração apenas no formulário de endereço de cobrança da página de checkout – ao finalizar o pedido. Todavia, o processo será exatamente o mesmo caso queira aplicar o mesmo efeito em outras páginas do site.

Para isso abra o arquivo billing.phtml que fica em:

app > design > frontend > base > default > template > persistent > checkout > onepage > billing.phtml

Não edite este arquivo. Faça uma cópia deste arquivo para o diretório “default/default” ou para seu “pacote/tema” customizado – e faça suas alterações na cópia.

Importante! Caso esteja utilizando uma versão anterior à 1.6.x, ignore o diretório “persistent” indicado acima.

Procure pelo input com id=”billing:postcode” e adicione o evento onblur=”buscar_end()”. O código deve ficar assim:

<input type="text" title="__('Zip/Postal Code') ?>" name="billing[postcode]" id="billing:postcode" value="escapeHtml($this->getAddress()->getPostcode()) ?>" class="input-text validate-zip-international helper('customer/address')->getAttributeValidationClass('postcode') ?>" onblur="buscar_end();" />

O que estamos fazendo aqui é disparar um evento javascript sempre que o cep for preenchido e o input perder o foco.

Dica! Particularmente eu prefiro re-organizar os campos deste formulário para deixar o campo cep acima dos demais campos de endereço, para que seja o primeiro campo a ser preenchido.

Agora precisamos criar o método buscar_end() na página.

Etapa 2 – Consulta AJAX

Ainda no mesmo arquivo billing.phtml vamos adicionar nosso código javascript, que utiliza o framework nativo do Magento (prototype) para fazer a chamada por AJAX, e que recebe o retorno dos dados em JSON.

Adicione ao final do arquivo:

//<![CDATA[
function buscar_end() {
    var url = 'getUrl('autocompletar/ajax/endereco') ?>';
    new Ajax.Request( url, { method: 'post',
        parameters: 'cep='+$('billing:postcode').value,
        onComplete: function(transport) {
            var res = transport.responseText.evalJSON();
            if ( res.resultado == '1' ) {
                $('billing:street1').value = res.tipo_logradouro+' '+res.logradouro;
                if ($('billing:street2')) $('billing:street2').value = res.bairro;
                $('billing:city').value = res.cidade;
                $('billing:region').value = res.uf;
            }
        }
    });
}
//]]>

Como você pode observar, não é um código difícil de ler. Iniciamos informando a url de consulta do nosso módulo (que iremos criar na sequência). Abaixo nós passamos como parâmetro AJAX o cep informado no campo “billing:postcode“. E por fim, se o código for executado com sucesso, nós recuperamos os valores por JSON e transferimos para os inputs correspondentes.

Agora sim… vamos criar a url, a configuração de nosso pequeno módulo.

Etapa 3 – Configurando o módulo

Antes de criarmos nosso arquivo, precisamos criar o diretório:

app > code > local > MarioSAM > AutoCompletar > etc > config.xml

É importante que você siga todos os passos à risca, inclusive o nome dos diretórios, espaços, maiúsculas e minúsculas. Depois que você ver seu exemplo funcionando, então você estará livre para fazer suas alterações.

Neste arquivo que moldamos o comportamento de nosso módulo, neste exemplo teremos apenas o seguinte:


    
        
            0.0.1
        
    
    
        
            
                standard
                
                    MarioSAM_AutoCompletar
                    autocompletar
                
            
        
    

Pra começar, informamos a versão do nosso módulo. Você deve encontrar esses parâmetros em todos os módulos.

Na sequência informamos o “routers“, que será nossa url de acesso ao módulo no frontend. Com o frontNameautocompletar“, como indicado no getUrl do seu javascript.

Acima do frontName temos o moduleMarioSAM_AutoCompletar“, que é a classe a ser executada quando alguém fizer uma solicitação à esse frontName. Obviamente ainda não temos essa classe, ainda…

Etapa 4 – A classe controladora

Antes de criarmos nossa classe, precisamos criar o diretório que armazena os controladores:

app > code > local > MarioSAM > AutoCompletar > controllers > AjaxController.php

A palavra Controller.php é para identificação do framework MVC utilizado pelo Magento. O que importa para nós é o que vem antes dessa palavra, neste exemplo: Ajax. Veja que precisamos passar essa palavra no getUrl do javascript para que ele saiba qual controller deve ser executado.

E o conteúdo deste controlador se resume em:

getRequest()->getParam('cep', false)).'&formato=json');
    }
}

Dentro deste arquivo temos uma function com nome “enderecoAction()“, onde Action() também faz parte do controle interno MVC utilizado pelo Magento, então o importante é o que vem antes dessa palavra, neste exemplo: endereco. Que também deve ser informado no código javascript getUrl, para que ele saiba qual função deve ser executada dentro deste controlador.

O que estamos fazendo aqui é uma solicitação de consulta à outro site, passando o cep como parâmetro e aguardando um retorno já formatado em JSON. O site em questão é o republicavirtual, que infelizmente possui uma base de dados já defasada.

Dependendo das configurações do seu servidor, a função @file_get_contents pode apresentar erro. Nesse caso consulte o suporte da sua hospedagem ou procure ajuda no fórum da Escola Magento.

Você também poderia fazer a consulta em outro site, como por exemplo: site dos correios. Vamos falar sobre isso mais adiante, antes, precisamos informar ao Magento que existe um novo módulo no sistema.

Etapa 5 – Habilitando o módulo

O Magento possui um diretório que lista quais módulos o sistema deve iniciar. E como acabamos de criar um novo módulo, precisamos informar ao sistema que este novo módulo deve ser carregado.

Para isso crie o arquivo MarioSAM_AutoCompletar.xml em:

app > etc > modules > MarioSAM_AutoCompletar.xml

O conteúdo deste arquivo é bem simples:


    
        
            true
            local
        
    

Ele apenas informa o nome do módulo, o local/diretório onde foi criado (codePool), e se deve ou não ser carregado (active=true).

Dica! Procure limpar o cache do sistema para ter certeza de que seu novo módulo será executado corretamente.

E com isso você já deve ter um formulário de endereço que preenche automaticamente os campos sempre que o cep é informado. Se isso não aconteceu, reveja o passo-a-passo, ou procure ajuda no fórum.

E os correios?

Os correios existem à mais de 350 anos aqui no Brasil, e ainda não alcançaram o estado de excelência em seus serviços mais básicos. Agora você imagine em algo que não é prioridade para os correios – como a internet.

Eu gostaria muito de criar um exemplo de módulo que utilizasse a API dos correios, onde pudéssemos fazer uma consulta rápida e fidedigna. Mas isso não existe!

Você até pode fazer uma requisição ao site dos correios passando uma url com parâmetros (GET) e obter uma página html de retorno. Então você utiliza esse html para filtrar e encontrar os campos que lhe interessam.

O problema é que esse processo além de ser “xunxo“, ainda é muito vulnerável. Qualquer alteração no código de retorno html, ou mesmo na url de consulta, ou ainda mesmo nas permissões de requisição, poderia interromper de imediato suas consultas à endereços. E você ficaria sem saber se algo foi alterado na estrutura, ou se é apenas o site dos correios fora do ar (de novo!).

Mas se ainda sim você quer fazer a consulta ao site dos correios, este exemplo continua valendo, basta que você faça as alterações necessárias na função enderecoAction().

Código disponível para download em: https://github.com/mariosam/AutoCompletarEndereco

Sucesso!