GMap a été conçu pour être personnalisable, il offre donc de nombreuses possibilités pour redéfinir les cartes.

La personnalisation est basée sur un mécanisme très proche de celui qu'utilise SPIP au niveau des squelettes : les requêtes sur les points, les icones et le contenu des info-bulles sont définis par des squelettes que l'on peut surcharger pour l'ensemble du site, pour une rubrique ou pour une branche. De plus, les icones et le contenu des info-bulles peuvent être définis selon le type d'objet et le type de point qu'ils représentent.

Requêtes sur les points

La combinaison des paramètres markers et query des balises #GEOMAP et #GEOMARKER permet de récupérer les points à afficher en exécutant une requête sur le serveur. Cette requête est définie dans par squelette qui renvoie un fichier au formats KML ou GeoJSON. Il est assez facile de redéfinir des fichier de requête et de les intégrer dans le fonctionnement de GMap.

GMap contient plusieurs fichiers de requêtes qui peuvent servir d'exemple : gmap-kml-default.html, gmap-kml-articles.html, gmap-kml-documents.html, etc.

Syntaxe

Les noms de fichier de requête respectent la syntaxe suivante :
prefix-(<nom d’objet>|default)[(-|=)<identifiant de rubrique>].
Le préfixe par défaut est gmap-<format>. Si une requête spécifique est définie (par markers=<ma requête> ou markers=query, query=<ma requête>), GMap testera deux préfixes :

• gmap-<format>-<ma requête>
• <ma requête>.

GMap contient des requêtes spécifiques pour les rubriques, les articles, les documents, les brèves, les auteurs, les mot-clefs, les rubriques racine et la recherche, cette dernière est par exemple formalisée dans deux fichiers gmap-kml-recherche.html et gmap-json-recherche.html

Stratégie de recherche

Lors de la compilation du squelette SPIP qui contient la carte (qu'elle soit dans un squelette ou dans un texte), GMap va tester l'existence de plusieurs noms de fichier et utiliser celui qui est le plus spécifique.

Par exemple, si la carte a été créée avec les paramètres id_article=un article de la rubrique 23,markers=query (sans paramètre query et soit avec format=kml soit sans paramètre format), GMap va tester l'existence des fichiers suivant et utiliser le premier trouvé :

1. gmap-kml-article=23.html : fichier spécifique aux articles et à la rubrique 23.
2. gmap-kml-article-23.html : fichier spécifique aux articles et à la branche sous la rubrique 23.
3. gmap-kml-article-2.html : fichier spécifique aux articles et à aux branches des ancêtres.
4. gmap-kml-article.html : fichier spécifique aux articles, pour tout le site.
5. gmap-kml-default=23.html : fichier spécifique à la rubrique, pour tous les objets.
6. gmap-kml-default-23.html : fichier spécifique à la branche, pour tous les objets.
7. gmap-kml-default-2.html : fichier spécifique à aux branches des ancêtres, pour tous les objets.
8. gmap-kml-default.html : fichier générique inclu dans le plugin et valable pour tous les objets de tout le site.

Ces fichiers sont recherchés dans le path de SPIP, c’est-à-dire le dossier squelettes et les racines des plugins. Le dernier fichier est forcément trouvé puisqu’il est inclu dans GMap.

Comment définir une requête ?

Avant de redéfinir une requête, il faut d'abord que vous vous posiez les question suivantes :

1. Est-ce que je veux modifier le comportement par défaut de GMap pour tout mon site ? Si oui, vous pouvez directement surcharger les fichiers de GMap correspondant aux requêtes que vous utilisez dans le dossier squelettes/.
2. Est-ce que je défini une requête qui sera utilisable dans tout le site et que j'appelerai par markers=<ma requête> (ou markers=query, query=<ma requête>) ? Si c'est le cas, vous n'avez qu'à définir un fichier gmap-kml-<ma requête>.html dans votre dossier squelette/ (l'écriture <ma requête>.html est également supportée, mais elle présente l'inconvénient de ne pas porter d'indication du format).
3. Est-ce que cette requête remplacera la requête par défaut pour une rubrique ou une branche, pour un type d'objet ? Dans ce dernier cas, vous avez intérêt à seulement redéfinir un fichier comme gmap-kml-article-2.html dans l'exemple ci-dessus.

 

Dans le dernier cas, vous devrez encore choisir quel fichier vous souhaitez surcharger. Dans la plupart des cas, il est conseillé de surcharger le fichier de requête par défaut : les autres sont déjà des requêtes spécifiques.

Vous pouvez alors recopier le fichier gmap-kml-default.html (ou gmap-json-default.html si vous préférez le format GeoJSON, voir à ce sujet la documentation de la balise #GEOMAP) dans votre dossier squelettes/, le renommer en fonction de l'objet, de la rubrique ou de la branche que vous voulez surcharger (cf. ci-dessus), et commencer à le modifier.

 

Ces fichiers sont des squelettes qui renvoient un fichier KML ou GeoJSON, ils peuvent donc contenir des boucles. Il faut également savoir que les balise #GEOMAP et #GEOMARKER transmettent au fichier de requête tous les paramètres qu'elles reçoivent, vous pouvez donc utiliser dans ces squelettes des paramètres spécifiques (une date par exemple). Attention : ceci n'est pas vrai pour les modèles dont les paramètres sont figés.

Représentation des points

GMap permet également de définir des icones spécifiques pour chauqe type d'objet, chaque type de point et par rubrique ou branche.

Il ne permet par contre pas, dans la version actuelle, de choisir une représentation spécifique depuis la partie privée du site, il faut forcément ajouter des fichiers sur le serveur.

Définition des icones

Les icones utilisées sur les cartes ne sont pas de simples images :

• Comme elle représentent un point géographique précis, elles doivent être dotée d'un point d'ancrage qui permet de les positionner au pixel près (c'est d'ailleurs pour cela que le terme "icone" est adapté).
• Selon les fournisseurs l'image peut être séparée de l'ombrage, ce qui clarifie les cas où plusieurs marqueurs se chevauches et permet de jolis effets sur le déplacement (dans Google Maps l'ombre s'écarte comme si on soulevait le marqueur).
• Selon les fournisseurs aussi, on peut définir un point d'ancrage des info-bulles.
• GMap introduit la possibilité de sélectionner les marqueurs, il faut donc définir des images pour l'état sélectionné.

Pour cette raison, il ne suffit pas de fournir une image pour changer l'apparence des marqueurs. GMap utilise donc un fichier XML de définition des icones qui porte l'extension .gmd.

Comme les fichiers de requêtes (voir ci-dessus), les fichiers de définition des icones peuvent être surchargés selon les objets, les types de points ou les rubriques auxquelles appartiennent les objets représentés.

La syntaxe de nommage des fichiers gmd est la suivante :

gmap-marker-(<nom d’objet>|default)[-<type de point>][(-|=)<identifiant de rubrique>].gmd

 

GMap contient des définitions d'icones par type d'objet et une définition générique (dans le dossier themes/gmap du plugin). Vous pouvez copier ces fichiers dans votre dossier squelettes/ et désigner de nouvelles images (avec de nouveaux points d'ancrage, etc.).

Par exemple, si vous voulez redéfinir l'apparence des points des articles dans la branche de la rubrique 23, vous devrez créer un fichier squelettes/gmap-marker-article-23.gmd.

 

Vous n'êtes pas obligés de reproduire toutes les images incluses dans les fichiers par défaut de GMap : par exemple les images en état sélectionné de vous seront pas utiles si vous n'utilisez pas cette fonction. De même, les images complètes ou les ombres peuvent être inutiles selon le fournisseurs de carte que vous avez choisi.

 

Pour faire plus simple, et si vous souhaitez redéfinir les images pour tout le site, vous pouvez vous contenter de redéfinir les images du dossier themes/gmap/images du plugin dans votre dossier squelettes/.

Styles pour les fichiers XML exportés

Il y a moins de possibilités de paramétrage en ce qui concerne l'interprétation des fichiers KML, par exemple par Google Earth.

En effet, la grammaire KML définit les icones soit dans des fichiers de styles isolés, soit pour chaque placemark directement dans le KML. Dans l'un comme l'autre cas, le report de toutes les possibilités ci-dessus aurait conduit soit à une profusion de requêtes sur le serveur, soit à une profusion de styles à gérer côté client.

Les styles KML sont donc simplifiés : on peut seulement définir une icone par type d'objet, ou, en surchargeant le fichier de requête gmap-kml-default.html, définir des icones spécifiques.

 

Les styles sont définis dans le fichier gmap-styles-default.html situé dans le dossier requetes du plugin. On peut le surcharger dans le dossier squelettes/.

Ce fichier défini les styles GMapDefault, GMapRubrique, GMapArticle et GMapDocument utilisés par gmap-styles-default.html.

 

La redéfinition du fichier gmap-kml-default.html, qui produit le fichier KML, offre évidemment plus de posibilités de personnalisation.

Comme on peut définir un autre fichier de style, on peut ajouter autant de styles que nécessaire, en étant seulement limité par la logique des boucles.

Contenu des bulles d'information

Selon le même principe, le contenu des bulles d’information est défini dans des fichiers squelettes nommés :
gmap-info-(<nom d’objet>|default)[-<type de point>][(-|=)<identifiant de rubrique>].html.

Ce sont des fichiers squelettes dans lesquels on peut utiliser des boucles SPIP.

 

Le stylage des info-bulles est contenu dans un fichier style/gmap-balloon.css, il permet de redéfinir le look des bulles sans toucher à leur contenu.

Attention : en redéfinissant les fichiers gmap-info-*.html, on pourrait penser s’affranchir de gmap-balloon.css, mais ce n’est vrai que pour les fichiers KML lus dans Google Earth. En effet, en interne, seul le contenu de la balise <body></body> est conservé et le style des info-bulles se fait en intégrant gmap-balloon.css dans la page HTML qui contient la carte.

 

Lorsque la fonction de regroupement des info-bulles est activée, l’apparence de la barre de navigation est figée, on ne peut la modifier qu’en redéfinissant le fichier style/gmap-balloon.css.