Formation « Des champs administrables avec ACF »

Le champ Google Map d’ACF

Lecture : 9 minutes • 0

Le champ Google Map permet de générer une carte Google interactive et d’y placer des marqueurs. On va voir comment en tirer parti au maximum et en toute simplicité.

Présentation du champ Google Maps

Le champ Google Maps d’ACF est puissant dans le sens où il permet de rendre administrable une carte Google. On va pouvoir y insérer un ou plusieurs marqueurs et définir leur position à partir d’une adresse ou en sélectionnant un point sur la carte.

Une carte Google Maps affiché sur le site, pilotée par ACF
Voici à quoi ressemblera notre Google Map

Et côté administration, on aura un champ ACF qui ressemblera à ceci : une carte et un champ de recherche par adresse :

Le champ Google Maps dans ACF
Plutôt sympa non ?

Mais avant cela on va avoir besoin d’obtenir une clé d’API gratuite sur Google Cloud Platform.

Obtenir une clé d’API

La toute première chose à faire, c’est nous rendre sur Google Cloud Platform afin de demander une clé d’API Google Maps.

On pourra l’obtenir bien sûr gratuitement, mais attention car on sera soumis à des quota : si trop d’internautes consultent nos pages, et donc notre Google Maps, elle pourrait être bloquée et le service deviendrait payant.

Voici l’adresse du tableau de bord :

Google Cloud Platform

Il se peut que vous ayez d’abord besoin d’initialiser votre compte, indiquer des informations et accepter des conditions générales.

Créez ensuite un nouveau projet en cliquant sur Select a project, puis New project.

Créer un nouveau projet depuis l'interface de Google Cloud Platform
Créez un nouveau projet Google Cloud

Indiquez ensuite le nom de ce projet, vous pouvez indiquer le nom de votre site.

Le formulaire d'ajout d'un projet Google Cloud Platform
Indiquez un nom à votre projet

Maintenant que votre projet est créé, il va falloir ajouter les API Google Maps. Cliquez sur API à gauche afin d’obtenir la liste des API disponibles.

La liste des API disponibles
Les API disponibles

Descendez sur Maps Javascript API et activez-la en cliquant sur Enable.

L'API Maps Javascript qu'on active en cliquant sur le bouton Enable
Activez la Maps Javascript API

Cela va activer les autres API Google Maps en même temps, et de retour sur votre tableau de bord vous aurez ça :

La liste des API activées sur notre projet Google Cloud Platform
Les API actives

Parfois, toutes les API relatives à Google Maps seront activées d’un coup, mais si ce n’est pas le cas, il va falloir activer les API nécessaires en cliquant sur leur nom dans la liste Additional APIs, puis les activer.

On aura besoin a minima de ces 3 API :

  • Maps Javascript API ;
  • Geocoding API ;
  • Places API.

La Geocoding API et Places API permettent de transformer une adresse en coordonnées géographiques, et on en aura besoin dans le cadre de notre champ ACF.

Maintenant qu’on a activé les API, il nous faut une clé, et pour la générer il faut accéder à cette page :

Générer une clé d’API

Vous trouverez un bouton Create Credentials en haut, cliquez dessus puis sur Create API Key. Votre clé est ainsi générée. Copiez-la !

La clé d'API est affichée dans une modale
Votre clé d’API Google Maps

On nous conseille de restreindre la clé d’API afin qu’elle ne soit utilisée que par la Gmap API et seulement sur notre URL. Comme on travaille en local, je ne rajoute pas de restrictions pour le moment, mais il faudra penser à le faire lors de la mise en production du site.

Il faudra pour cela restreindre sur HTTP Referrers (web sites) et indiquer l’URL de votre site.

Maintenant, on va retourner dans notre code et plus précisément dans functions.php pour y coller ce petit Hook ACF qui permet d’indiquer notre clé :

PHP
functions.php

Comme on va avoir besoin de la clé d’API à nouveau plus tard (pour le front end cette fois), alors je la stocke dans une constante, au tout début du fichier.

Attention

Placez la constante pour la clé d’API au début du functions.php afin d’y avoir accès dans tout le reste du document par la suite.

Tout est prêt, on va donc pouvoir aller configurer notre champ.

Configurer le groupe de champs

Allez dans ACF > Groupes de champs et on va créer un nouveau groupe que je vais appeler Google Maps.

Les réglages du champ Google Maps dans ACF
Les paramètres du champ Google Maps

Dans les options, on peut définir le point de départ de la carte, j’indique lat 48.8566 et lng 2.3522 afin de centrer sur Paris.

Vous pouvez indiquer un niveau de zoom allant de 0 (monde) à 21 (la rue). 14 est pas mal pour avoir une vision au niveau de la ville.

Enfin j’indique une hauteur de carte à 400px. Mais ce paramètre servira seulement dans l’interface d’administration de WordPress car on aura notre propre CSS pour le front.

Je vais également ajouter 2 autres champs afin de pouvoir administrer le contenu de l’infobulle qui apparait au survol d’un marqueur. J’ai donc besoin d’un titre au travers d’un champ texte et d’une description via un champ textarea.

Le groupe de champs ACF Google maps et sa configuration
On ajoute 2 champs textes supplémentaires

Assignez enfin ce groupe de champs au Modèle de page Champ google Maps, puis enregistrez.

Allez ensuite dans Pages > Ajouter et créez une nouvelle page « Google Maps ». Assignez le modèle de page Champ Google Maps et votre champ carte devrait apparaitre sous le contenu.

La carte Google dans l'interface d'édition de la page
Notre carte Google apparaît !

Tapez une adresse dans la barre de recherche, et des suggestions devraient apparaître. Cliquez sur le résultat de votre choix afin de faire apparaitre un marqueur.

Attention

Si vous avez une erreur, vérifiez que vous avez bien activé les API, et attendez quelques minutes. La prise en compte de votre clé peut prendre un peu de temps.


Pour en savoir plus sur la configuration du champ Google Maps d’ACF. Je vous invite à consulter sa documentation officielle :

Documentation du champ Google Maps

Afficher la carte avec un marqueur

Il nous reste un peu de chemin pour que ça fonctionne sur le site ! On va devoir préparer le terrain avec du JS, du CSS et du PHP.

Tout d’abord, on va devoir charger la librairie Google Maps, ainsi que notre script qui va piloter l’affichage de la carte et de ses marqueurs.

On va aller charger ces ressources dans notre Hook wp_enqueue_scripts dans functions.php.

Mais attention ! On ne va pas charger ces scripts sur tout le site. Ce serait un gros défaut de performances. On lancerait des requêtes HTTP en plus sur toutes les pages, pour rien.

Quand a-t-on besoin de cette carte ? Si on regarde notre groupe de champs, il est assigné au modèle de page « Google Map ». Voilà notre condition !

Il faut charger nos scripts seulement lorsque le Template Hierarchy affiche notre modèle de page.

PHP
functions.php

C’est donc le conditional tag is_page_template() qui va nous permettre de faire ce contrôle. N’hésitez pas à revoir le cours sur le template hierarchy en cas de besoin.

Ensuite, je charge un fichier JS que l’on va créer juste après, et qui aura 2 dépendances : l’API Google Maps, et jQuery. Il sera donc forcément chargé après les deux.

À éviter

Ne chargez pas inutilement des ressources sur votre site. À la place, utilisez les conditional tags pour tester les situations.

Le CSS

On va commencer avec le plus simple, le CSS. Il n’y a en effet pas besoin de beaucoup de styles pour faire marcher notre carte, car la plupart seront apportés par la Google Maps API elle-même. On ajoute ce CSS dans notre feuille de style du thème, c’est inutile d’en créer une spécialement pour l’occasion.

CSS
style.css

Nous, on va juste définir les dimensions de notre carte. Et pour qu’elle soit responsive on indique 100% de largeur. On définit une taille en pixels pour la hauteur par mesure de simplicité, mais je vous renvoie à l’article de CSS Tricks si vous voulez maintenir un certain ratio.

Ensuite, on corrige un souci potentiel sur les images : dans nos thèmes on a tendance à les rendre responsive avec max-width: auto, mais ça crée un souci sur la Google Maps : le petit bonhomme de StreetView s’en retrouve tout déformé. Du coup on « annule » cet effet dans le bloc de la carte.

Le PHP

Le code à placer dans le modèle reste assez simple. On va récupérer la valeur de notre champ avec get_field().

PHP
templates/google-maps.php

Dedans on aura un tableau PHP contenant plusieurs informations :

Données renvoyées par ACF affichées à l'aide d'un var_dump()
Les informations retournées par ACF

On retrouve la latitude, la longitude, le niveau de zoom, le nom du lieu, sa ville et son pays. On va fournir ces informations à Javascript en les écrivant dans des attributs data- dans le HTML.

C’est ensuite notre script map.js qui va interpréter tout ça. J’indique le zoom au niveau de la <div> de la carte, et la latitude et longitude dans celle du marqueur. La carte sera automatiquement centrée sur celui-ci.

Conseil

Rien ne vous oblige à utiliser le même niveau de zoom que dans l’administration, vous auriez pu mettre une valeur fixe comme 16 par exemple.

Le Javascript

Passons enfin au JS. On a chargé la Gmap API tout à l’heure ainsi qu’un fichier js/map.js qu’on n’a pas encore créé !

On le crée et on va y coller le contenu indiqué dans la documentation ACF. Vous pouvez tout simplement récupérer mon fichier dans mon thème.

JS
js/map.js

Il y a plusieurs fonctions qui vont permettre d’initialiser la carte, les marqueurs, centrer sur un point géographique. À la fin, on recherche tous les éléments .acf-map de la page pour initialiser notre carte Google.

Vous pourriez très bien d’ailleurs changer ce sélecteur pour le nom de votre choix.

Tout est prêt, alors allons voir notre page, pour voir si notre carte s’affiche bien :

La carte Google Maps s'affiche sur la page du site
Voici notre carte et son marqueur

Si vous n’avez pas ce résultat, commencez par vérifier dans la console pour voir s’il n’y a pas d’erreur JS qui s’afficherait en rouge. Vous pouvez l’afficher en faisant un Clic droit > Inspecter > Console. Vérifiez également le nom des classes CSS et des champs ACF.

Afficher une infobulle sur le marqueur

Pour afficher l’infobulle au-dessus d’un marqueur lorsque l’on clique dessus, c’est facile. Le script fourni par ACF possède déjà le nécessaire pour le faire fonctionner, du coup on a juste à ajouter un peu de code dans notre élément .marker :

PHP
templates/google-maps.php

J’ai ajouté un titre de niveau 3 (arbitraire) avec le contenu de mon champ title, et en-dessous le contenu du textarea description.

Voici le résultat :

Au clic sur le marqueur de position, une infobulle apparait
L’infobulle au-dessus du marqueur

Au niveau du code JS, c’est cette partie qui fait le nécessaire :

JS
js/map.js

Le script map.js utilise en fait simplement les fonctions de l’API Google Maps, comme décrites dans documentation Google Maps officielle.

Gérer plusieurs marqueurs

Bien souvent, on veut pouvoir afficher plusieurs marqueurs sur une même carte. J’ai eu le cas pour un foodtruck à burgers qui indique où le trouver dans la semaine.

Capture d'écran d'un site affichant une carte Google avec plusieurs marqueurs gérés par ACF
La carte google avec plusieurs marqueurs

Le champ Google Map d’ACF ne nous permet d’indiquer qu’un seul marqueur à la fois. On va donc voir d’autres solutions et, selon le besoin, l’une sera plus adaptée que l’autre.

Technique n°1 : Le custom Post Type et la WP Query

Ma première technique, c’est de créer un Custom Post Type « Lieux » : un emplacement correspondra donc à une publication.

On va créer le Type de publication comme on je vous l’ai appris dans le développement de thèmes.

PHP
functions.php

Dans ACF > Groupes de champs, on va aller assigner notre groupe de champs aux publications de ce CPT. On ajoute donc la règle : Type de publication • est égal à • Lieux.

L'interface de gestion des champs d'ACF
Afficher notre groupe de champs dans le CPT Lieux

Maintenant, quand vais dans Lieux > Ajouter, je devrais voir mon champ Google Maps apparaître.

Capture d'écran de WordPress et son interface de rédaction
Nos champs apparaissent bien dans le CPT Lieux

Donc là on va avoir 1 lieu = 1 publication dans mon CPT. Et pour récupérer plusieurs publications d’un coup, on peut le faire grâce à une requête personnalisée via la WP Query.

Imaginons maintenant que je veux afficher ces emplacements sur une carte sur la page d’accueil de mon site. Je vais donc dans mon template front-page.php et je créé ma WP Query :

PHP
front-page.php

Dans la WP Query, on met presque le même code que celui vu précédemment, sauf que cette fois, on met la <div> de la carte à l’extérieur de la boucle car il n’y aura qu’une carte, contenant plusieurs marqueurs. La boucle ne va donc créer que des marqueurs.

Conseil

Pensez à créer une page Accueil et à l’assigner en page d’accueil dans Réglages > Lecture.

On va tester ! Ça marche ? Eh bien non, ça marche pas ! On a oublié un détail crucial : notre script Gmap n’est chargé que sur les modèles de pages « Google Map ». Il faut qu’on ajoute un conditional tag pour les charger aussi sur la page d’accueil :

PHP
functions.php

C’est is_front_page() qui me permet de tester si le Template Hierarchy va bien afficher la page d’accueil du site.

On retente :

Une carte Google Map affichant plusieurs marqueurs en même temps.
La carte et ses marqueurs s’affichent !

Vous avez remarqué ? La carte est automatiquement centrée pour montrer tous les points ! C’est grâce à la fonction google.maps.LatLngBounds(), qui fait le calcul toute seule. Pratique non ? Si bien qu’on n’a même plus besoin d’indiquer le niveau de zoom que l’on souhaite.

Quand utiliser cette méthode ?

L’avantage d’un Custom Post Type, c’est de créer une page par publication (et donc une URL dédiée). Vous pourriez donc avoir des pages détaillées pour chaque lieu. Mais si vous avez juste besoin de lister des points, sans page dédiée, alors on va voir la technique n°2.

Technique n°2 : Le champ répéteur

L’autre solution c’est d’utiliser simplement le champ répéteur. De cette manière vous pourrez gérer tous les marqueurs dans la même publication. Par contre dans l’administration il va y avoir une carte par marqueur ajouté :

Avec le répéteur, ajoutez autant d’emplacements que vous le souhaitez

Par contre, en front, on n’aura bien qu’une seule carte réunissant tous les marqueurs.

Attention

Faites attention tout de même aux performances de votre administration en répétant trop de fois le champ carte !

Pour cet exemple, j’ai créé un template google-map-repeater.php et un groupe de champs Google Maps + Répéteur. Le répéteur a pour slug places au pluriel, et chaque champ Google place au singulier.

Au niveau code, on va associer le code du répéteur en utilisant notamment get_sub_field(), et le code du champ Google qu’on a déjà vu précédemment :

PHP
templates/google-maps-repeater.php

Et le résultant sur le site sera le même qu’avec la technique n°1 :

Une carte Google Maps avec plusieurs marqueurs gérés par ACF
1 carte et plusieurs marqueurs, grâce aux répéteurs

À vous de choisir pour la solution qui vous convient le mieux, en fonction de votre besoin !


Vous êtes maintenant rodés pour ajouter des cartes Google administrables grâce à des champs ACF ! Mine de rien, c’est un champ très puissant qui pourrait vous emmener très loin !

0

Questions, réponses et commentaires

Laisser un commentaire