Tutorial

Primeiros passos

A primeira etapa para uso da GeoMap BR é a preparação da página Web a partir da incorporação dos arquivos da própria biblioteca. Também é importante incorporar os recursos externos que ela usa, que são as bibliotecas jQuery, D3, GeoStats e Numeral.

Faça o download da API e extraia a mesma na pasta raíz do projeto. Em seguida, faça a inclusão da API conforme o exemplo abaixo.

<script src="http://code.jquery.com/jquery-3.2.1.min.js"></script>
                                        
<script src="http://d3js.org/d3.v3.min.js"></script>
<script src="http://d3js.org/topojson.v1.min.js"></script>
<script src="http://d3js.org/queue.v1.min.js"></script>
<script src="geomapbr/js/geomapbr.js"></script>
<script src="geomapbr/js/geostats.min.js"></script>
<script src="http://cdnjs.cloudflare.com/ajax/libs/numeral.js/2.0.6/numeral.min.js"></script>
<link rel=stylesheet href="geomapbr/css/geomapbr.css">

O próximo passo é a criação e configuração do componente da página que receberá o mapa. Esse componente deve ser um elemento div, com um identificador que será usado como referência para a biblioteca.

<div id="mapa"></div>

Agora vamos definir o tamanho do mapa. Essa configuração deve ser feita por meio de regras CSS.

<style>
    #mapa {
        height: 500px;
        width: 600px;
        border: thin black solid;
    }
</style>

Criação do mapa

A criação do mapa é feita por meio de comandos em JavaScript.

Para que o mapa seja exibido logo após o carregamento da página, utilizaremos o evento onload. Dentro do método criaremos uma instância que fará referência a classe geoMapBR, o que permitirá fazer a chamada dos métodos para geração e configuração do mapa.

<script>
    var gmb;
    $(window).on('load', function () {
        gmb = new geoMapBR("mapa");
        gmb.gerarMapa();
    });
</script>

A ação acima resultará no desenho de um mapa brasileiro com suas divisões municipais e estaduais (default), sendo possível navegar pelos municípios por meio de zoom e, ao clicar sobre algum, obter informações quanto a sua localização por meio de uma janela flutuante.


Adicionando dados

A API GeoMap BR foi projetada para receber uma base de dados no formato csv, e permite que estes dados estejam separados por vírgula(,), ponto e vírgula (;), barra vertical (|) ou ainda tabulação (\t).

A base de dados precisa ter uma estrutura básica de pelo menos duas colunas, sendo uma referente ao código do município e outra referente ao valor do registro. Quanto ao código do município, a API permite que o mesmo esteja em sua forma abreviada (sem dígito verificador) ou não.

Para fazer o carregamento da base de dados, é necessário utilizar o elemento input file.

<input type="file" id="dados" accept=".csv">

Além dos dados, o usuário deve informar os atributos dos dados que serão aplicados ao mapa. Estão são: id do registro (opcional), código do município (obrigatório), descritor do registro (opcional) e valor do registro (obrigatório).

Trabalharemos neste tutorial apenas com os dois campos obrigatórios. Vamos incluir dois elementos select para fazer a seleção dos campos e um botão para aplicar as configurações ao mapa.

Código do município <select id="campoCodMunicipio"> </select>
Valor <select id="campoValor"> </select>

<input type="button" value="Aplicar Mapa" id="botaoAplicar">

Após isso, faremos a chamada do método que seta a base de dados no mapa. Este método é assíncrono, ou seja, sua execução não acontece por completo imediatamente após a sua chamada. Qualquer funcionalidade que dependa da base de dados só poderá ser executada após a leitura completa do arquivo, como o caso da função que retorna os atributos dos dados. Definiremos esta função como callback do método de inserção de dados, e faremos uma rotina para preencher os selects que criamos com estes atributos, tudo isso através de recursos do jQuery, conforme abaixo.

$(document).ready(function () {

    $("#dados").change(function () {

        gmb.setDados(document.getElementById("dados").files, function () {

            let atributos = gmb.getAtributos();

            let campos = [];
            campos[1] = document.getElementById("campoCodMunicipio");
            campos[2] = document.getElementById("campoValor");

            for (var i = 0; i < atributos.length; i++) {
                campos.forEach(function (d) {
                    opt = document.createElement("option");
                    opt.value = i;
                    opt.text = atributos[i];
                    d.appendChild(opt);
                });
            }

        });
    });
});

Agora vamos escrever o código do evento click do botão para enviar à API os campos escolhidos pelo usuário e aplicar ao mapa os dados.

$(document).ready(function () {
                            
    $('#botaoAplicar').click(function () {

        gmb.setCampoCodMunicipio($('#campoCodMunicipio :selected').text());
        gmb.setCampoValor($('#campoValor :selected').text());
        
        gmb.gerarMapa();

    });

});

Desta forma, o usuário já é capaz de selecionar os campos do arquivo de dados e realizar as aplicações. Como não foram definidas configurações de exibição de dados, serão assumidos valores default, ou seja, operação média, método de classificação quebras naturais, cinco classes, duas casas decimais e esquema de cores vermelho.


Configurando a exibição de dados

A API permite que manipulemos a forma com que os dados serão exibidos. É possível definir a operação que será realizada com os dados, ou seja, nos registros referentes ao mesmo município podemos realizar média, soma, ou contagem dos mesmos. A classificação de dados ocorre por meio da definição do método que se pretende utilizar, podendo ser quebras naturais, intervalos iguais, quantis, desvio padrão e intervalos manuais. Podemos definir a quantidade de classes que queremos gerar, o número de casas decimais e ainda a coloração que será aplicada ao mapa baseada na classificação.

Para testar algumas funcionalidades, vamos inserir um select para as operações, um select para os métodos, um input text para quantidade de classes, um select para as cores e um input checkbox como opção do usuário inverter as cores do mapa. Vamos inserir apenas algumas opções neste campos para realizar testes.

Operação <select id="operacao">
    <option value="contagem">Contagem</option>
    <option value="media">Média</option>
    <option value="soma">Soma</option>
</select>

Método <select id="metodo">
    <option value="quebras-naturais">Quebras naturais</option>
    <option value="quantis">Quantis</option>
    </select>

Nº classes <input type="text" id="classes">

Coloração <select id="cor">
    <option value="azul">Azul</option>
    <option value="verde">Verde</option>
    <option value="vermelho">Vermelho</option>
</select>

<input type="checkbox" id="inverterCores"> Inverter cores

Para capturar as opções do usuário, é necessário inserir o código abaixo ao conteúdo do código do botão Aplicar.

if ($('#operacao :selected').val() == "contagem")
    gmb.setOperacaoContagem();
else if ($('#operacao :selected').val() == "media")
    gmb.setOperacaoMedia();
else
    gmb.setOperacaoSoma();

if ($('#metodo :selected').val() == "quebras-naturais")
    gmb.setMetodoQuebrasNaturais();
else
    gmb.setMetodoQuantil();

gmb.setQtdClasses($('#classes').val());

if ($('#cor :selected').val() == "azul")
    gmb.setCorAzul();
else if ($('#cor :selected').val() == "verde")
    gmb.setCorVerde();
else
    gmb.setCorVermelha();

Agora a aplicação permite configurar a apresentação dos dados ao mapa de acordo com as funções que definimos.


Limites regionais

Vamos criar alguns input checkbox para o usuário marcar os limites regionais que deseja que seja desenhado ao mapa.

<input type="checkbox" id="desenhaMunicipios"> Municípios
<input type="checkbox" id="desenhaMicrorregioes"> Microrregiões
<input type="checkbox" id="desenhaMesorregioes"> Mesorregiões
<input type="checkbox" id="desenhaEstados"> Estados
<input type="checkbox" id="desenhaRegioes"> Regiões

Agora podemos associar a seleção do componente e setar ao mapa a opção através do botão Aplicar. Vamos adicionar os métodos abaixo ao código do evento click do botão Aplicar para enviar as informações.

gmb.setDesenhaBordaMunicipio($('#desenhaMunicipios').is(':checked'));
gmb.setDesenhaBordaMicrorregiao($('#desenhaMicrorregioes').is(':checked'));
gmb.setDesenhaBordaMesorregiao($('#desenhaMesorregioes').is(':checked'));
gmb.setDesenhaBordaEstado($('#desenhaEstados').is(':checked'));
gmb.setDesenhaBordaRegiao($('#desenhaRegioes').is(':checked'));

Podemos testar agora o desenho dos limites de mapa de acordo com o desejo do usuário.


Aplicando filtro

Suponhamos que queiramos trabalhar com dados de mesorregiões. Vamos adicionar dois elementos select para o usuário filtrar a mesorregião que gostaria de exibir. O primeiro para selecionar o estado e o segundo a mesorregião.

Estado <select id="filtroEstado"> </select>
Mesorregião <select id="filtroMesorregiao"> </select>

Agora é necessário carregar um select com o nome dos estados e, de acordo com o estado selecionado, o outro select será carregado com as mesorregiões deste. Como definimos que a API será inicializada com o carregamento da página, precisamos setar um timeout antes de chamar a função que retorna os dados dos estados, afim de garantir que os mesmo já estão disponiveis na hora de sua chamada.

$(document).ready(function () {
                                                          
    setTimeout(function () {
        let data = gmb.getListaEstados();
        for (let i = 0; i < data.length; i++) {
            opt = document.createElement("option");
            opt.value = data[i].cod;
            opt.text = data[i].nome;
            document.getElementById("filtroEstado").appendChild(opt);
        }
    }, 3000);

    $('#filtroEstado').change(function () {

        $('#filtroMesorregiao option').remove();

        let data = gmb.getListaMesorregioes($('#filtroEstado :selected').val());
        for (let i = 0; i < data.length; i++) {
            opt = document.createElement("option");
            opt.value = data[i].cod;
            opt.text = data[i].nome;
            document.getElementById("filtroMesorregiao").appendChild(opt);
        }
    });

});

Quando adicionamos dados referente a todo território brasileiro, ao filtrarmos, os limites dos dados devem mudar para a classificação ser compatível com a área filtrada. Vamos adicionar um input checkbox para o usuário marcar se deseja que a classificação seja de acordo com o filtro ou referente a massas de dados.

<input type="checkbox" id="intervalFiltro"> Classificação de acordo com o filtro

Agora, vamos editar o botão Aplicar e incluir os métodos abaixo para que sejam setados o filtro e a opção de classificação.

gmb.setFiltroMesorregiao($('#filtroMesorregiao :selected').val());
gmb.setAtivaClassificacaoPorFiltro($('#intervalFiltro').is(':checked'));

Podemos filtrar agora as mesorregiões de todo o Brasil e adequar a classificação dos dados de acordo com o filtro aplicado.


Configurando série temporal

Para criar um mapa dinâmico que exiba uma série temporal de dados, é preciso definir o campo onde se iniciará a leitura dos dados, e esta somente findará no último campo do arquivo.

Vamos criar um elemento input checkbox para ativar a série, um input text para setar o tempo em segundos para trocar de atributo, e outro input checkbox para ativar o loop.

<input type="checkbox" id="ativarSerie"> Ativar
<input type="text" id="tempoSerie"> Tempo em segundos
<input type="checkbox" id="loop"> Loop

Agora podemos associar os valores do componente e ativar a série temporal no mapa, bem como o tempo de transição entre os campos e a opção de loop ao término de cada ciclo através do botão Aplicar. Lembrando que a opção de mapa dinâmico não funciona sem uma entrada de dados. Vamos adicionar os métodos abaixo ao código do evento click do botão para enviar as informações.

gmb.setSerieTemporalAtivar($('#ativarSerie').is(':checked'));
gmb.setSerieTemporalTempo($('#tempoSerie').val());
gmb.setSerieTemporalLoop($('#loop').is(':checked'));

Podemos testar agora a visualização temporal dos dados, setando o tempo em segundos para troca entre os campos.