Download the PHP package vsilva472/jquery-viacep without Composer
On this page you can find all versions of the php package vsilva472/jquery-viacep. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download vsilva472/jquery-viacep
More information about vsilva472/jquery-viacep
Files in vsilva472/jquery-viacep
Package jquery-viacep
Short Description Plugin jquery para autocompletar endereços a partir de um cep utilizando a api do viaCEP
License MIT
Homepage https://github.com/vsilva472/jquery-viacep
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package jquery-viacep
jQuery ViaCEP
Um plugin jQuery para autocompletar endereços a partir de um CEP utilizando a api do site ViaCEP com ~1,6Kb.
Elaborado de forma não intrusiva, ou seja, não é necessário alterar o código existente da aplicação.
Compatível com gerenciadores de Tags (como Google Tagmanager) e com suporte a múltiplos forms na mesma página. Compatível ainda com vários CMSs e Frameworks (Laravel, WooCommerce e etc).
Conteúdo
- Suporte de browser
- Instalação
- Via Git
- NPM
- Composer
- CDN
- Opções padrão
- Instruções de uso
- Via data-attributes
- Via classes css
- Seletores mistos
- Uso com jQuery Mask
- Eventos
- Exemplos avançados
- Exibindo loading
- Bloqueando FORM durante o loading
- Bloquear campos autocompletados
- Dropdown de estados sem UF
- Integrando com Laravel
- Integrando com Google Analytics
- Integrando com Google TagManager
- Integrando com Select2
- Campos gia, ibge, unidade e complemento
- Apoie o projeto
Suporte de Browser
 |
 |
 |
 |
 |
|---|---|---|---|---|
| IE 10+ ✔ | Último ✔ | Último ✔ | Último ✔ | Último ✔ |
Instalação
Instalação via GIT
git clone [email protected]:vsilva472/jquery-viacep.git (SSH) ou
git clone https://github.com/vsilva472/jquery-viacep.git (HTTPS)
Instalação via NPM
npm i @vsilva472/jquery-viacep --save
Instalação via Composer
composer require vsilva472/jquery-viacep
Instalação via CDN
https://www.jsdelivr.com/package/npm/@vsilva472/jquery-viacep
<script src="https://cdn.jsdelivr.net/npm/@vsilva472/jquery-viacep/dist/jquery-viacep.min.js"></script>
Opções padrão
| Atributo | Tipo | Padrão | Descrição |
|---|---|---|---|
| container | String | '[data-viacep]' |
Seletor do container dos campos (geralmente a tag <form>) |
| field_logradouro | String | '[data-viacep-endereco], .viacep-endereco' |
Seletor para o campo Endereço do form |
| field_bairro | String | '[data-viacep-bairro], .viacep-bairro' |
Seletor para o campo bairro do form |
| field_localidade | String | '[data-viacep-cidade], .viacep-cidade' |
Seletor para o campo Cidade do form |
| field_uf | String | '[data-viacep-estado], .viacep-estado' |
Seletor para o campo Estado do form |
| field_cep | String | '[data-viacep-cep], .viacep-cep' |
Seletor para o campo CEP do form |
Se seu projeto possui vários formulários e todos são padronizados, talvez seja mais prático para você alterar as opções padrão globalmente, dessa forma basta incluir o arquivo com as opções preenchidas e o plugin se encarregará do resto.
Instruções de uso
Usando com seletores padrão via data-attributes
Nota Se você utilizar os seletores padrão definidos em $.fn.viacep.defaults inalterados, não é necessário a chamada do plugin $('selector').viacep(options), pois o plugin já se auto instancia com essas opções.
Usando com seletores padrão via classes CSS
Usando com seletores mistos
O plugin é flexível o suficiente para misturar seletores padrão com personalizados.
O exemplo abaixo usa os seletores padrão de classe css para o campo bairro e o seletor padrão de data-attribute para o campo cidade e seletores personalizados para os demais campos.
Nota A chamada para o plugin deve ser feita em uma tag que englobe os campos a serem auto completados (geralmente na tag <form>).
Uso em conjunto com jQuery Mask
Este plugin não faz bind de valores no campo de cep, isto torna jquery-viacep um plugin compatível com outros plugins de máscaras como por exemplo o jQuery Mask de forma nativa.
Entretanto caso você precise/deseje fazer alguma programação customizada na(s) máscara(s) do(s) campo(s) antes e/ou depois de receber os dados da api, você pode estar consultando a api de eventos e identificar qual melhor evento se adapta a sua necessidade de customização da máscara.
Eventos
O plugin possui uma poderosa api de eventos que o torna extensível e flexível o suficiente para ser integrável em qualquer sistema que possua jQuery instalado.
| Evento | Descrição | Argumentos |
|---|---|---|
viacep.plugin.init |
Disparado logo após o plugin ser iniciado em um elemento | NULL |
viacep.ajax.before |
Disparado antes de efetuar a requisição para api do viaCEP | NULL |
viacep.ajax.complete |
Disparado no final do ciclo da requisição independente se a mesma foi obteve sucesso ou erro. | NULL |
viacep.ajax.error |
Disparado quando ocorre um erro na requisição (400, 500 etc.) | jqxhr, textStatus, error |
viacep.ajax.success |
Disparado quando a requisição é feita com sucesso e após os bind dos valores nos campos | response completo incluindo os campos unidade, ibge e gia da api do ViaCEP |
viacep.response.error |
Disparado quando a requisição foi feita com sucesso porém o objeto json da resposta da api contém o atributo erro |
cep, msg, response |
Exemplos avançados
Veja abaixo algumas aplicações avançadas do plugin utilizando a api de eventos do plugin.
Exibindo loading
Bloqueando FORM durante o loading
As vezes faz-se necessário bloquear o form durante a requisição para evitar múltiplas requisições. O exemplo abaixo ilustra essa situação.
Bloquear campos autocompletados
Algumas vezes devido a uma regra de negócio, não desejamos permitir que o usuário altere os campos depois que foram preenchidos. O exemplo abaixo ilustra esta situação deixando apenas o campo número liberado para preenchimento.
Dropdown de estados sem UF
Por padrão o plugin tentará setar o valor do campo estado com o atributo uf da resposta da api. Isto funcionará normalmente caso o campo estado seja um campo de texto ou seja um <select> com <option value="UF">.
Alguns projetos utilizam o nome do estado ao invés da uf nos <option>. O exemplo abaixo ilustra como proceder nesse caso.
Integrando com Laravel
Em frameworks como laravel é comum por questões de segurança a existência de um CSRF-TOKEN para evitar ataques, e por uma questão de comodidade geralmente já inserimos o header X-CSRF-TOKEN nas requisições ajax com um script do tipo:
Porém a api do viaCEP não completa a requisição se este header estiver presente. O exemplo abaixo ilustra como proceder neste caso desativando este header e reativando ao final da requisição.
Integrando com Google Analytics
Talvez seja interessante para e equibe de BI extrair algumas informações sobre essas buscas no google analytics. O exemplo abaixo ilustra como enviar um evento com o nome da cidade buscada para o GA. Você pode adpatar para sua necessidade.
Integrando com Google TagManager
O exemplo abaixo ilustra a situação anterior porém enviando o evento via TagManager ao invés do GA .
Integrando com Select2
Este plugin está programado para funcionar com a biblioteca Select2 de forma nativa.
Caso você precise de algum ajuste, você pode estar utilizando a api do select2 em conjunto com a api de eventos deste plugin, em específico o evento viacep.ajax.success para refazer o bind dos valores no select2. Veja:
Campos gia ibge unidade e complemento
Talvez em seu(s) formulário(s) você precise do(s) campo(s) gia e/ou ibge e/ou complemento e/ou unidade. Você pode estar populando estes campos de 3 formas:
-
Definindo-os nas configurações globais em
$.fn.viacep.defaults -
Definindo os campos na instancia do plugin
- Populando os campos via evento
viacep.ajax.success(recomendado).
Esta opção é a recomendada pois nela você tem maior controle sobre os dados recebidos e os campos que você precisa popular. Atente-se que nem sempre o resposta da api do viaCEP retorna com estes dados populados.
Apoie
Apoie o projeto enviando HTMLCOIN
Wallet: HqgaiK6T1o2JP4p3p34CZp2g3XnSsSdCXp
Licença
MIT
