Le champ Google Map d’ACF

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.

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

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.

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

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.

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

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

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 !

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é :

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.

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.

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.

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.

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.

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.

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.

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.

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().

Dedans on aura un tableau PHP contenant plusieurs informations :

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.

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.

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 :

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 :

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 niveau du code JS, c’est cette partie qui fait le nécessaire :

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.

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.

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.

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

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 :

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.

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 :

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 :

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é :

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

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 :

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

À 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 !