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 );
- 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, Directions API, Places API.
Abaixo (Figura 1), mostra como deve ficar após ativar corretamente as API'S.
Figura 1 - API's ativadas corretamente
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.
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, e siga os passos passado pelo tutorial do Google para conseguir gerar sua API.
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.
- Clique em Plugin;
- em seguida, em Adicionar novo plugin;
- Escreva "maps" no campo de pesquisa, aperte "Enter" no seu teclado para pesquisar, em seguida selecione a Api do Google Maps;
- 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 abrir uma das views onde irá aparecer o mapa, no nosso exemplo iremos usar a home.view.html de um 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 Token no componente
Após inserirmos anteriormente o componente na view, agora é necessário colocarmos o token para que o componente funcione corretamente, siga os passos referente à Figura 4.1.
Figura 4.1 - Adicionando o token gerado no site do Google ao componente
- Clique no componente Google Maps para selecioná-lo;
- Clique na aba de configuração;
- Clique em PROPRIEDADES;
- Em seguida, no campo token, cole a Chave de API que você gerou.
Bloco de programação
Agora iremos Criar 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 Bloco de programação Mobile (localizado em src/main/mobileapp/www/js/blockly/Imagem.blockly), 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.2)
Figura 4.2 - 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.3. 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 (mobile)) 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 4.3 - 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 4.4 - 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 4.5.
Figura 4.5 - Sequência para chamar um evento na inicialização do componente.
- Selecionar o componente do mapa;
- Selecionar a aba de configurações;
- Selecionar a aba Eventos;
- Clique nos "..." no evento Ao Iniciar;
- Clique nos "..." para selecionarmos o bloco que será chamado;
- Selecione o a função Executar do bloco APIGoogleMaps;
- 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 alterados e execute a aplicação (F9) ou Debug (F11). 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.6.
Figura 4.6 - 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 (Figura 5).
Figura 5 - Arrastando componentes
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, no parâmetro Id do mapa, o id do componente Google Maps que inserimos na view. em seguida, no parâmetro Id do input, o id do componente texto de saída. (Figura 5.1)
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 5.1.
Figura 5.1 - 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 ( 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
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 5.2.
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.
Figura 5.3 - 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 e colaremos na nova função AutoCompletarDestino, todos os blocos que estão ligados ao bloco Criar o autocompletar da função AutoCompletarSaida devem ir junto para a nova função. Por fim, alteraremos os parâmetros Id do mapa do bloco Criar o autocompletar para o id do componente Google Maps e o parâmetro Id do Input o id do componente de texto referente ao destino e o parâmetro Nome do bloco Criar variável de escopo para "destino", por fim, colocaremos a variável item no parâmetro Valor. (Figura 5.4)
Figura 5.4 - Aparência final da função AutoCompletarDestino.
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ávei, 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 precisar dos blocos: Direção da rota (categoria Google Maps), que calculará o melhor caminho, em seguida, ele irá receber o bloco Criar rota (categoria Google Maps), para gerar a requisição e receber o bloco Criar coordenada (categoria Google Maps), que gera a coordenada baseada nos pontos de latitude e longitude que irá receber os dados por meio do 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.
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:
Opções avançadas do bloco Desenha rota
|
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 5.7.
Figura 5.7 - 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 5.8.
Figura 5.8 - Resultado final da nossa aplicação.
Após o preenchimentos 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 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, começaremos selecionando no parâmetro Id do mapa o id do componente Google Maps que usamos na view, no parâmetro Id do marcador escreveremos o Identificador do marcador (nesse exemplo: cronappId), o parâmetro Título que exibirá um tooltip quando o ponteiro do mouse passar por cima, receberá o texto "Sede CronApp", 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 6.
Observação
Para funcionar, todos os blocos devem ser chamados para a função principal como feito em "Chamar as funções autocompletar"
Figura 6 - 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 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
| Índice |
|---|