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:
- Possuir uma conta Google.
- Projeto do tipo mobile criado. Caso haja dúvidas de como criar esse tipo de projeto acesse o link ( Criar projeto );
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 1).
Figura 1 - Exemplo de uso da API do Google Maps no CronApp.
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. 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.
Atualização
Lembramos que a partir do dia 18 de julho de 2018, o Google mudou sua politica de cobrança pelo uso das APIs do Google maps, apesar de ainda possuir um uso gratuito, porém limitado, é necessário criar uma conta de faturamento para poder obter o token da API.
Veja mais informações sobre as mudanças e seus preços em: Guia para usuários existentes.
Acesse a página Obter uma chave/autenticação no google developers, faça o login com uma conta Google e clique em "Get Started" (Obter uma chave) (Figura 2).
Figura 2 - Primeiro passo para obter a chave de autenticação.
Após essa etapa, você será direcionado para a tela de ativação na plataforma do Google Maps, selecione pelo menos um dos três produtos oferecidos (Maps, Routes e Places). (Figura 3)
Figura 3 - Seleção dos produtos oferecidos pela plataforma.
Na janela de seleção do projeto, Informe o nome do seu projeto ou selecione-o, caso já exista, e clique em "Next" para avançar para próxima etapa. (Figura 4)Figura 4 - Informando o nome do projeto.
Seremos direcionados a tela de seleção de conta de faturamento, caso não possua, terá que criar uma. Após o cadastro dos seus dados e cartão de crédito, uma tela de confirmação da ativação da API aparecerá, clique em "Próxima". (Figura 5)
Figura 5 - Ativação das APIs selecionadas anteriormente.
Ao final, o sistema irá gerar uma chave (Token) parecida com a da figura 6, copie e salve.
Figura 6 - Chave de autenticação gerada.
Adicionando Plugin do Google Maps API
Com o projeto criado e aberto no CronApp, clique no ícone do gluonsoft para importar a API do google maps, como informado na Figura 7.
Mais sobre
Figura 7 - Importando o gluonsoft ao seu projeto.
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 abrir uma das views onde irá aparecer o mapa, no nosso exemplo iremos usar a home.view.html que fica em "Códigos Fontes / Principal / Códigos Fontes Cliente / views / logged/".
Com a página aberta, arrastamos o componente Google Maps para o centro da página (Figura 8).
Figura 8 - Arrastando componente do Google Maps
Para adicionarmos o Token no componente, basta seguir os passos: selecione o componente arrastado, clique nas opções do controle, selecione a propriedade "MAPA" e por fim, insira a chave gerada anteriormente no campo "Token", como na Figura 9.
Figura 9 - Adicionando o token gerado no site do Google ao componente
Bloco de programação
Agora iremos Criar um bloco de programação do lado cliente que irá chamar o recurso e gerar a renderização do mapa em nossa página.
Clique com o botão de menu do mouse na pasta Bloco de Programação ( localizada em "Código Fonte / Principal / Código Fonte Cliente / js /") e selecione Novo → Bloco de Programação, adicione o nome do Arquivo e clique em finalizar. (Figura 10)
Figura 10 - 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 11. Nos parâmetros "Id do mapa" informe o Id do componente mapa que arrastamos na tela home.view.html anteriormente.
Observação:
É necessário informar o nome do Formulário de referência (nesse tutorial estamos usando home.view.html) na janela de Propriedades do bloco de programação. Essa janela é aberta ao clicar na engrenagem no canto direito / superior da tela de edição do bloco de programação.
O objetivo dessa função é inicializar o mapa ao ser chamada 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 11 - Blocos de programação que exibe o mapa na tela.
Mais sobre
Para obter a coordenada geográfica de um local no site do Google Maps, basta clicar em um ponto e arrastá-lo para o centro do mapa, o endereço (URL) será alterado informando as coordenadas do ponto central no mapa.
No exemplo abaixo (Figura 12), as coordenadas são: -13.0011623 de latitude e -38.4685141 de longitude.
Figura 12 - Selecionando a coordenada geográfica de um ponto no mapa.
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 13: Selecionar o componente do mapa (1), na aba eventos (2) selecione a propriedade "Ao iniciar" (3), clique em "…" (4) na janela "Events" para procurar o evento e finalize selecionando a função que acabamos de criar (5).
Figura 13 - Sequência para chamar um evento na inicialização do componente.
Testando o carregamento do mapa
Nesse momento o mapa já deverá ser exibido na tela. 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, como na Figura 14.
Figura 14 - Rodando a aplicação.
Adicionando auto completar e rota
Nesse momento 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, altere as propriedades "Identificador" dos campos para "inputSaida" e "inputDestino" como na Figura 15.
Figura 15 - Renomeando o identificador do campo Saída.
Criação dos blocos auto completar
De volta ao bloco de Programação do lado cliente, vamos arrastar o bloco "Para" (categoria Funções) para criar uma nova função dentro do arquivo "APIGoogleMaps". Renomeie a nova função para "AutoCompletarSaida" e arraste também o bloco "Criar o autocompletar" (categoria Google Maps), selecionando o identificador do campo de saída (inputSaida). (Figura 16)
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. Adiantaremos essa etapa arrastando 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, veja o exemplo na Figura 16.
Figura 16 - Primeira parte do AutoCompletarSaida.
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 onde só aparecerão os endereços contidos dentro daquela região.
Para isso, arraste os blocos "Pontos do retângulo" (categoria Google Maps) para encaixar no parâmetro "Limite de busca" e o bloco "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 17.
Figura 17 - Os endereços que aparecerão no auto completar ficarão restritos a essa região da grande Salvador.
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 18.
Figura 18 - Aparência final da função AutoCompletarSaida.
O 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.
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". Copiaremos o bloco "Criar o autocompletar" que criamos da função "AutoCompletarDestino" e colaremos na nova função "AutoCompletarDestino", todos os blocos que estão ligados ao bloco "Criar o autocompletar" devem ir junto para a nova função. Por fim, alteraremos os parâmetros "Id do componente" do bloco "Criar o autocompletar" para "inputDestino" e o parâmetro "Nome" no bloco "Criar variável de escopo" para "destino". (Figura 19)
Figura 19 - Aparência final da função AutoCompletarDestino.
Chamar as funções autocompletar
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 20). Após isso, ao iniciar o mapa as funções de auto completar dos campos saída e destino serão chamadas.
Figura 20 - 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 da variável que criamos nas funções de autocompletar anteriormente, em nosso exemplo iremos dar os nomes de "destino" e "saida" (Figura 21).
Figura 21 - Iniciando a função que exibe a rota no mapa.
Após essa etapa, vamos precisar dos blocos: "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; o bloco "Criar coordenada" (categoria Google Maps), que gera a coordenada baseada nos pontos de latitude e longitude; bloco "Criar rota" (categoria Google Maps), para gerar a requisição e "Direção da rota" (categoria Google Maps), este calculará o melhor caminho.
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.
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:
{"preserveViewport": false}
Mais sobre
Para mais informações sobre as propriedades, acesse a documentação oficial do Google Maps.
Ao final, o nosso bloco deverá estar como na Figura 22.
Figura 22 - Bloco GeraRota finalizado.
Testando o uso da ferramenta
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 23.
Figura 23 - Resultado final da nossa aplicação.
Após o preenchimentos dos endereços, clicamos no botão "Rota" e o caminho devem ser renderizado no mapa como na Figura 24.
Figura 24 - 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 um imagem como marcador em um local no mapa, destacando-o.
Para isso, vamos criar uma nova função chamada "Adicionar Marcador" e usar o bloco "Criar marcador" (categoria Google Maps), arraste também o bloco "Criar coordenada" (categoria Google Maps) onde passaremos a longitude e latitude desse ponto.
No bloco "Criar marcador" devemos passar alguns dados, como o Identificador do marcador (nesse exemplo: cronappId), o parâmetro "Título" que exibirá um tooltip quando o ponteiro do mouse passar por cima, em "ícone" devemos informar o endereço da imagem e 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 25.
Figura 25 - Função Criar marcador.
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 circulo.
Criaremos uma nova função chamada "Adiciona circulo" 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: cronappId), 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 26).
Figura 26 - 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 27).
Figura 27 - Chamando as funções Criar marcador e Desenha Círculo.
Resultado final
Ao rodarmos nossa aplicação, visualizaremos o marcador que criamos na etapa 1 e o círculo feito na etapa 2 (Figura 28).
Figura 28 - Marcador com sua janela de informações mais tooltip e o círculo criado em volta do ponto informado.