O Google Maps (Mapas) é um serviço gratuito de pesquisa e visualização de mapas e imagens de satélite da Terra. Além do uso gratuito da funcionalidade através do site da ferramenta, o Google também disponibiliza uma API para integração com sistemas de terceiros, tendo planos gratuitos e pagos.

Pré-requisitos

Antes de começar a seguir os passos do tutorial é preciso ter certeza de que se tem um ambiente minimamente preparado para reproduzir o exemplo. Abaixo estão os requisitos principais.

Requisitos:

1. Possuir uma conta Google.
2. Projeto do tipo web ou mobile criado. Caso haja dúvidas de como criar esse tipo de projeto acesse o link ( Criar projeto );
3. Precisará ativar as 3 API'S que serão fundamentais para o funcionamento do componente e evitar erros referente à API KEY, são elas: Maps JavaScript API, Geocoding API,  Directions API, Places API.

Abaixo (Figura 1), mostra como deve ficar após ativar corretamente as API'S.

Figura 1 - As 4 API's necessárias

Visão geral: exemplo

Nesse tutorial iremos criar uma aplicação onde o usuário irá inserir uma localização inicial, uma localização de destino e o sistema irá exibir o melhor caminho entre os 2 pontos. Os campos onde serão inseridos os endereços terão um auto completar para facilitar a busca de endereços (Figura 2).

Figura 2 - Exemplo de uso da API do Google Maps no Cronapp.

Passos

Estamos utilizando um projeto mobile como exemplo, porém é possível seguir os mesmos passos em um projeto web.

Obter a chave/autenticação

Para podermos utilizar a API do Google maps, será necessário gerar uma chave de autenticação (Token) no site da API da ferramenta.

Nesse exemplo iremos utilizar a chave padrão, de uso gratuito, porém limitado. Para saber se sua aplicação poderá utilizar a versão gratuita da API, acesse a página de Limites de uso do Google Maps JavaScript API para mais informações.

Adicionando Plugin do Google Maps API

Para que você tenha acesso à categoria de blocos referente ao Google Maps, você precisa fazer os passos da figura 3.

Figura 3 - Adicionando a API ao seu projeto. 

1. Clique em Plugin no menu do sistema;
2. Em seguida, Instalar Plugins;
3. Pesquise por "maps" no campo de busca e Google Maps Api;
4. Clique em avançar e depois em finalizar para concluir.

Exibição do mapa

Será necessário adicionar um componente visual em nossa página e criar um bloco de programação para solicitar o recurso.

Componente visual

Primeiramente vamos à views onde irá aparecer o mapa, no nosso exemplo iremos usar a home do projeto mobile.

Com a página aberta, arrastamos o componente Google Maps para o centro da página (Figura 4).

Figura 4 - Arrastando componente do Google Maps

Inserindo o Token da API

Após inserirmos anteriormente o componente na view, agora é necessário colocarmos o token para que o componente funcione corretamente, siga os passos referentes à Figura 4.1.

Figura 4.1 - Adicionando o token gerado no site do Google ao componente 

1. Clique no componente Google Maps para selecioná-lo;
2. Clique na aba de configuração;
3. Clique em PROPRIEDADES;
4. Em seguida, no campo token, cole a Chave de API gerada a partir da sua conta no Google maps.
5. Este campo Identificador, não é o mesmo que utilizamos para chamar o componente nos blocos de programação.

Identificador

Para que o componente seja chamado no bloco de programação, é necessário saber o Identificador necessário, para visualizar, clique no componente e após isso, desagrupe clicando no cadeado que aparecerá nos botões de balão.

Após desagrupar, clique na imagem dentro do componente (1 da figura 4.2) e vá até o campo Identificador das Propriedades (2 da figura 4.2), note que o identificador possui o padrão "map3824", termo map + 4 números aleatórios, verifique também no destaque 3 da imagem 4.2 que a estrutura DOM exibirá a div com o nome do Identificador, será esse identificador que usaremos nos blocos de programação.

Figura 4.2 - Obtendo o Identificador

Bloco de programação 

Agora criaremos um bloco de programação do lado cliente mobile que irá chamar o recurso e gerar a renderização do mapa em nossa página. 

Clique com o botão direito do mouse na pasta Mobile (Localização: em Blocos de Programação/Mobile  ), selecione Novo > Bloco de Programação, ao abrir a janela "Novo", selecione a opção Bloco de Programação Vazio (Low-Code), avance, em seguida, adicione ao campo Nome do Arquivo "ApiGoogleMaps", no campo Nome da Função escreva "Executar" e clique em Finalizar. (Figura 4.3)

Figura 4.3 - Criando o bloco de programação APIGoogleMaps.

Com a função do Bloco de Programação gerada, vamos adicionar os blocos: Se Faça e Não (categoria Lógica), mais os blocos Mapa inicializado?, Inicializar mapa e Criar coordenada (categoria Google Maps), organizados como na Figura 4.4. Nos parâmetros "Id do mapa" informe o Id do componente mapa que arrastamos na tela home anteriormente.

O objetivo dessa função é inicializar o mapa ao ser chamado e evitar que seja feita uma nova requisição caso a página seja atualizada. O bloco Criar coordenada informa o ponto central do mapa ao ser inicializado.

Figura 4.4 - Blocos de programação que exibe o mapa na tela.

Precisamos chamar o evento que acabamos de criar ao iniciar a página, então vamos usar o próprio controle do mapa para realizar essa chamada. Basta seguir os passos da Figura 4.6.

Figura 4.6 - Sequência para chamar um evento na inicialização do componente.

1. Selecionar o componente Mapa na área de edição;
2. Selecionar a aba de Configurações;
3. Selecionar a aba Eventos;
4. Clique nos "..." no evento Ao Iniciar;
5. Clique nos "..." para selecionarmos o bloco que será chamado;
6. Selecione a função Executar do bloco APIGoogleMaps;
7. Clique em Selecionar e em seguida em OK para concluir.

Testando o carregamento do mapa

Nesse momento o mapa já deverá ser exibido na tela. Salve os arquivos e execute o sistema. Após abrir a aplicação como mobile, informe login e senha "admin" e confirme para acessar a página home e visualizar o mapa, como na Figura 4.7.

Figura 4.7 - Rodando a aplicação.

Adicionando auto completar e rota

Iremos adicionar 2 campos de texto onde o usuário irá digitar o endereço de origem e de destino e um botão para executar a ação de exibir a rota no mapa. Enquanto o usuário digita o endereço, a aplicação irá sugerir endereços através do auto completar do campo.

Inserir campos com o auto completar

Em nossa tela, arraste 2 componentes visuais Entrada de texto e um Botão, altere seus rótulos para "Saída", "Destino" e "Rota" respectivamente. Para facilitar a identificação dos campos no momento da formos criar as funções em blocos (Figura 5).

Figura 5 - Arrastando componentes

Criar blocos auto completar

De volta ao bloco de Programação do tipo cliente, iremos criar outra função dentro do arquivo de bloco de programação que criamos anteriormente.

Figura 5.1 - Primeira parte do AutoCompletarSaida.

1. Arraste o bloco Para (categoria Funções) para criar uma nova função dentro do arquivo "APIGoogleMaps" e renomeie a nova função para "AutoCompletarSaida";
2. Arraste o bloco Criar o autocompletar (categoria Google Maps);
3. Selecione, no parâmetro Id do mapa, o id do componente Google Maps que inserimos na view;
4. No parâmetro Id do input, o id do componente texto de saída;
5. No parâmetro Tipo de busca modifique para Endereço, forçando o auto completar retornar somente endereços. Precisaremos criar uma variável de escopo para podermos usar o retorno desse bloco na renderização da rota que iremos criar logo mais;
6. Usaremos uma variável de escopo para alimentar a função que vai gerar a rota, assim, arraste o bloco Cria variável de escopo (categoria Formulário), inserindo "saida" no parâmetro Nome e arrastando o bloco "Item" (categoria Variáveis) para encaixar no parâmetro Valor.

O AutocompletarSaida já está funcionando. Porém, quando um usuário começar a digitar um endereço irá aparecer os endereços mais relevantes do mundo inteiro. Podemos melhorar isso restringindo uma área no mapa (Figura 5.2) onde só aparecerão os endereços contidos dentro daquela região.

Figura 5.2 - Os endereços que aparecerão no auto completar ficarão restritos a essa região da grande Salvador.

Restringindo área do auto completar - Saída

Ainda na função "AutoCompletarSaida", siga os passos abaixo para limitar a região de pesquisa.

Figura 5.3 - Aparência final da função AutoCompletarSaida.

1. Arraste os blocos Pontos do retângulo (categoria Google Maps) para encaixar no parâmetro Limite de busca;
2. Arraste os blocos Criar coordenada (categoria Google Maps), passando as coordenadas. Oeste-Sul e Leste-Norte de um retângulo. Nesse exemplo iremos utilizar a área da região informada na Figura 5.2;
3. Finalizaremos esse bloco alterando o parâmetro Busca restrita? para Verdadeiro, limitando a consulta à região que informamos. O bloco deve ficar como na Figura 5.3.

Restringindo área do auto completar - Destino

Auto completar do campo Destino será semelhante, então iremos criar uma nova função e copiar o que fizemos na função do campo saída.

Figura 5.4 - Aparência final da função AutoCompletarDestino. 

1. Arrastaremos novamente o bloco Para (seção Funções), criando uma nova função dentro do arquivo "APIGoogleMaps" e renomearemos a nova função para "AutoCompletarDestino";

2. Copiaremos o bloco Criar o autocompletar e colaremos na nova função AutoCompletarDestino; 

3. Alteraremos os parâmetros Id do mapa do bloco Criar o autocompletar para o id do componente Google Maps;
4. Alteraremos o parâmetro Id do Input o id do componente de texto referente ao destino;
5. Colocaremos o parâmetro Nome do bloco Cria variável de escopo para "destino", e por fim, colocaremos a variável item no parâmetro Valor.

Chamar as funções auto completar

Com as 2 funções do autocompletar criadas (saída e destino), voltamos à primeira função que criamos (Executar) e arrastaremos as funções que estão na categoria Funções para a área Comandos do bloco Inicializar mapa (Figura 5.5). Após isso, ao iniciar o mapa, as funções de auto completar dos campos saída e destino serão chamadas.

Figura 5.5 - Chamada das funções de auto completar no momento da criação do mapa.

Criando a Rota

Criaremos uma nova função chamada "GeraRota" que irá receber os pontos de origem e destino, calcular e renderizar a melhor rota no mapa.

Inicialmente vamos criar 2 variáveis que receberão o conteúdo do autocompletar. Usaremos os blocos definir (categoria Variáveis) e Obtém variável de escopo (categoria Formulário), informando o nome das variáveis, em nosso exemplo iremos dar os nomes de "destino" e "saida", mas é importante que as variáveis estejam iguais ao da função do auto completar.(Figura 5.6).

Figura 5.6 - Iniciando a função que exibe a rota no mapa. 

Após essa etapa, vamos seguir os passos da Figura 5.7.

Figura 5.7 - Bloco GeraRota finalizado

1. Vamos precisar do bloco Direção da rota (categoria Google Maps), que calculará o melhor caminho;
2. Em seguida, ele irá receber o bloco Criar rota (categoria Google Maps), para gerar a requisição;
3. Colocaremos no Criar rota, o bloco Criar coordenada (categoria Google Maps), que gera a coordenada baseada nos pontos de latitude e longitude;
4. Usaremos o bloco Obter propriedade do autocompletar (categoria Google Maps) responsável por coletar os pontos de latitude e longitude dos endereços passados pelo usuário utilizando as variáveis que criamos;
5. Finalizamos essa função com o bloco Desenha rota (categoria Google Maps), que receberá o Identificador do mapa, o retorno do caminho do bloco Direção da rota e uma propriedade. Este último bloco renderizará a rota por cima do mapa;

6. Em Opção avançada do bloco Desenha rota, adicionaremos uma propriedade que altera o zoom e centraliza o mapa para melhor visualização da rota. A opção deverá ser passada em formato JSON, informado a seguir:

   Opções avançadas do bloco Desenhar rota

   {"preserveViewport": false}

Ao final, o nosso bloco deverá estar como na Figura 5.7.

Teste

Salve os arquivos alterados e execute a aplicação (F9) ou Debug (F11). Após abrir a aplicação, informe login e senha "admin" e confirme para acessar a página home e visualizar o mapa, informe endereços dentro da cidade de salvador, pois restringimos a busca nessa área. Nesse momento, o Auto completar deve estar funcionando e exibindo endereços com nomes parecidos, a exemplo da Figura 5.8.

Figura 5.8 - Resultado final da nossa aplicação.

Após o preenchimento dos endereços, clicamos no botão "Rota" e o caminho deve ser renderizado no mapa como na Figura 5.9.

Figura 5.9 - Resultado final da nossa aplicação.

Outras funcionalidades

A API do Google Maps possui uma série de funcionalidades interessantes. Apesar de não fazer parte do escopo inicial do tutorial, vamos mostrar como inserir um marcador e desenhar um polígono no mapa.

Bloco marcador

É possível adicionar uma imagem como marcador em um local no mapa, destacando-o. Para isso, vamos seguir os passos da Figura 6.

Figura 6 - Função Criar marcador

1. Criaremos uma nova função chamada "Adicionar Marcador";
2. Arrastaremos o bloco Criar marcador (categoria Google Maps);
3. Arraste também o bloco Criar coordenada (categoria Google Maps) onde passaremos a longitude e latitude desse ponto;
4. No bloco Criar marcador devemos passar alguns dados, começaremos selecionando no parâmetro Id do mapa o id do componente Google Maps que usamos na view;
5. No parâmetro Id do marcador escreveremos o Identificador do marcador (nesse exemplo: cronappId);
6. O parâmetro Título que exibirá um tooltip quando o ponteiro do mouse passar por cima, receberá o texto "Sede Cronapp";
7. Em ícone devemos informar o endereço da imagem;
8. Em Janela de informações podemos adicionar um texto com informações do local, inclusive usando HTML e CSS. O bloco ficará como na Figura 6. 

<h2 style="text-align: center;">Sede do Cronapp</h2>

Desenhar um polígono no mapa

É possível desenhar polígonos em cima do mapa para destacar uma região. Nesse exemplo iremos adicionar um círculo.

Usaremos o bloco Desenha círculo (categoria Google Maps). Como parâmetro, informe o Id do mapa e do círculo que estamos criando (nesse exemplo: IdCirculo), o ponto central do círculo, o tamanho do raio em metros, a cor do interior do círculo, cor do seu contorno e a transparência do preenchimento interior que varia entre 0 e 1 (Figura 6.1). 

Figura 6.1 - Função Desenha Círculo

Chamada das funções

Arraste os blocos das funções recém-criadas que estão na categoria Funções para a lista de comandos do bloco Inicializar mapa da função principal, como fizemos anteriormente (Figura 6.2).

Figura 6.2 - Chamando as funções Criar marcador e Desenha Círculo

Resultado final

Ao rodarmos nossa aplicação, visualizaremos o marcador que criamos (Figura 6.3).

Figura 6.3 - Marcador com sua janela de informações mais tooltip e o círculo criado em volta do ponto informado