Doc/Pleade/GoogleMaps

Module Google Maps - Paramétrage

Pour installer ce projet il faut l'installer de puis le projet DEV et utiliser le projet pleade-entreprise-gmaps, qui contient une partie des choses nécessaires a son utilisation, le reste est a installer, pour cela il nous faut :

• Avoir installer Mysql, la dernière version est recommandée.

sudo apt-get install mysql-server

• Avoir préalablement activé les paramètres nécessaires dans le pleade-plus.properties

######                 ######
# - Affichage Google Maps - #
######                 ######
# Active le module pleade google maps
pleade.gmaps.active=true
# Résolution des noms de lieux en temps réel lors de la publication (gmaps)
pleade.gmaps.publish-resolve=true

• Avoir dé-commenter (ou ajouter) le champs agrégé nécessaires à la création de l'index contenant la géolocalisation dans le fichier ead-aggregated-fields.xml.

<aggregated-field name="geognames" type="field">
        <field name="fgeogname"/>
        <field name="fregion"/>
        <field name="flieudocument"/>
        <field name="fcommune"/>
        <field name="fbatiment"/>
    </aggregated-field>

• Avoir ajouté la table pour l'application dans la base de données pleade80 qui aura été crée.

Notice :

Dans les nouvelles version de pleade, la table se crée toute seule lors de l'initialisation du module Google Maps..

--
-- Structure de la table `module_maps`
--
CREATE TABLE IF NOT EXISTS `module_maps` (
  `id_maps` int(11) NOT NULL AUTO_INCREMENT,
  `base_adress_maps` varchar(1000) DEFAULT NULL,
  `formated_adress_maps` varchar(1000) DEFAULT NULL,
  `type_adress_maps` varchar(250) DEFAULT NULL,
  `location_type_maps` varchar(250) DEFAULT NULL,
  `lat_maps` varchar(250) DEFAULT NULL,
  `lng_maps` varchar(250) DEFAULT NULL,
  PRIMARY KEY (`id_maps`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8 AUTO_INCREMENT=0 ;

• Avoir configuré les données de connexions a MySQL dans tomcat sur le fichier context.xml

Il faut ajouter cette balise dans le context.xml si elle n'existe pas afin de permettre au module google maps de se connecter a la base de donnée, celui ci utilise JNDI pour configurer la connexion.

<Resource name="jdbc/pleade" auth="Container" type="javax.sql.DataSource" maxActive="1000" maxIdle="500" maxWait="10000" url="jdbc:mysql://localhost/pleade80" driverClassName="com.mysql.jdbc.Driver" username="sdxapp" password="sdxapp-pwd"/>

Enfin il faut parametrer le fichier de configuration pleade-plus.properties, celui ci permettra de configurer la carte et améliorer son fonctionnement:

######                 ######
# - Affichage Google Maps - #
######                 ######
# Active le module pleade google maps
pleade.gmaps.active=false

# Résolution des noms de lieux en temps réel lors de la publication (gmaps)
pleade.gmaps.publish-resolve=true

# Mode de carte ( google maps => maps || leaflet => omaps )
pleade.gmaps.map.type=maps

# Latitude (lat) puis longitude (lon) par défaut 
#( si un lieu n'a pas pu être résolu il sera placé a coté de ces coordonnées )
#( elles doivent être séparés par une virgule et être tronquée a deux chiffres après le point )
#( récupérable ici : http://ubuntu:8080/pleade-entreprise-gmaps/functions/gmaps/getgeodata.xml?lieu=NOM-DE-LA-VILLE-PAR-DEFAUT&resolve=true )
pleade.gmaps.map.defaultlatlng=44.83,-0.57

#région par défaut (pour aider au géocodage)
#( Qui aidera google maps a résoudre les noms de lieu dans une zone donnée ) 
pleade.gmaps.map.defaultregion=FR

#langue par défaut
#( qui aidera google maps a récupérer les noms de lieux en français )
pleade.gmaps.map.defaultlangage=fr

#hauteur de la carte en pixel 
#( afin qu'elle soit de la bonne taille dans la page ou elle sera visualisée )
pleade.gmaps.map.height=600

#zoom de la carte google maps 
#( niveau de zoom au chargement de la carte, seulement sur google maps ) 
pleade.gmaps.map.zoom=5

#zoom minimum et maximum de la carte omaps
#( permet de définir une limite quand au zoom afin de ne pas sortir de la carte par exemple )
pleade.gmaps.omap.min.zoom=4
pleade.gmaps.omap.max.zoom=15

Si par connaissances certains noms de lieux sont selons vous difficile a traduite en coordonées GPS, il faut configurer le fichier gmaps-filter.xml afin de faciliter la tache du géocodeur. la syntaxe est en Reg Ex.

<!-- Salles (Les) (Gironde, France) [aujourd'hui : Salles-de-Castillon (Les) (Gironde, France)]--> <!-- Salles-de-Castillon (Les) (Gironde, France) On ne garde que les valeurs --> 
<!-- qui sont dans aujourd'hui-->
<entry key="([^']*)(\[aujourd'hui : )([^']*)(\])">$3</entry>

<!-- on enlève les tirets "--" -->
<entry key="([^.]*)(--)([^.]*)">$1 $3</entry>

<!-- On enlève une valeur après un point virgule comme "bordeaux (gironde; france)" -->
<!-- Cela donnera "Bordeaux (gironde) -->
<entry key="([^.]*)\(([^.]*);([^.]*)\)">$1 ($2)</entry>

<!-- on sort une valeur qui est entre crochets -->
<entry key="(\[)([^.]*)(\])">$2</entry>

<!-- on enlève les apostrophes -->
<!--<entry key="([^.]*)(\')([^.]*)">$1 $3</entry>-->

<!-- on enlève les "le la les" des noms de lieux) -->
<entry key="\(le\)"></entry>
<entry key="\(la\)"></entry>
<entry key="\(les\)"></entry>
	
<!-- Si dijon est présent on le met en fin de phrase -->
<entry key="(Dijon)([^.]*)">$2 $1</entry>

<!-- Si cote d'or est présent, on l'enleve -->
<entry key="(\(Côte\-d\'Or\))([^.]*)">$2</entry> 

<!-- la fonction findAddAfter permet de chercher un mot et de l'ajouter en fin de phrase -->
<!-- si il n'est pas présent findAddBefore reprends le même concept sauf qu'il les place  -->
<!-- en début de phrase -->
<!--<entry key="findAddAfter[Dijon]">Dijon</entry>-->
<!--<entry key="findAddBefore[Dijon]">Dijon</entry>-->
<entry key="findAddAfter[France]">France</entry>

Les instructions de nettoyages sont exécutées dans l'ordre et sont enchaînées, il faut donc faire attention a bien les organiser

Module Google Maps - Développement

Qu'est ce que ce module ?

Ce module apporte une nouvelle fonctionnalité a Pleade qui est l'affichage des résultats de recherche sur une carte de type google maps, le but de cet affichage est de voir où est localisé géographiquement les séries, les documents publiés sur Pleade en fonction de leur nom de lieu.

Comment s'en sert t'on ?

l'utilisation de ce module est assez simple, cela dépends quand quel contexte on se positionne:

• Utilisateur
  1. Faire une recherche
  2. cliquer sur la petite icône en forme de marqueur en faut a droite pour changer le mode d'affichage des résultats

• Administrateur
  1. Activer le module
  2. Se connecter
  3. Publier un document
  4. Faire une recherche
  5. Cliquer sur un lieu qui ne semble pas être au bon endroit
  6. Cliquer sur "Repositionner" pour déplacer le marqueur, puis sur valider si le changement de place est correct. ( le bouton Supprimer place le marqueur sur des coordonnées nulles, le marqueur ne sera plus affiché sur la carte sauf si une nouvelle résolution est lancée via la commande resolve all )

• Développeur
  1. Activer le module
  2. Avoir fait une publication pour remplir la base de données
  3. Appeler un service cocoon pour utiliser le module google maps

URL	Paramètres	Action
http://localhost:8080/pleade-entreprise-gmaps/functions/gmaps/getgeodata.xml?lieu=VILLE&resolve=true	@place (obligatoire) @resolve (optionnel)	Ce service sert a récupérer des données géographiques afin de localiser un lieu en fonction de son nom de lieu. on spécifie le nom de lieu dans le paramètre @lieu il est obligatoire car ce service ne devinera pas quelque lieu vous souhaitez géocoder enfin le paramètre @resolve lui est optionnel, il permet de spécifier au service si vous souhaitez résoudre en temps réel les noms de lieux que vous donnez, par défaut il est a false.
http://localhost:8080/pleade-entreprise-gmaps/functions/gmaps/getgeodata.xml?lieu=resolve-all&resolve=resolve-all	@lieu=resolve-all (obligatoire) @resolve=resolve-all (obligatoire)	tout comme le précédent service, ce service permet de géocoder des lieux, en effet ce service vas chercher dans toute la base de données en dehors d'un processus de publication, les lieux qui n’ont pu être décodé(limite google) ou qui on des erreurs au niveau de leur syntaxe (que google n'as su résoudre)
http://localhost:8080/pleade-entreprise-gmaps/functions/gmaps/altergeodata.xml?place=VILLE&lat=LATITUDE&lng=LONGITUDE	@place (obligatoire) @LAT (obligatoire) @lng (obligatoire)	ce service permet de modifier la position d'un lieu a partir de coordonnées latitude et longitude

Important :

L'API de google maps qui sert a géocoder a une limite qui est de 2500 lieux par tranche de 24 heures a hauteur de 10 lieux géocodés par seconde MAXIMUM !.

Comment fonctionne t'il ?

Diagramme

Voici un diagramme présentant le fonctionnement du module Google Maps de manière globale.

Numéro Action	Descriptif
1	Envoi des noms de lieux dans le module Google Maps de Pleade
2	Nettoyage des noms de lieux dans le module a partir d'un fichier de configuration spécifique
3	Requête vers le service Google Maps pour résoudre un nom de lieu (on lui envoie un nom de lieu)
4	Récupération de la réponse du service Google Maps ( Cette réponse peut ou non renvoyer des coordonnées GPS cela dépends de la syntaxe du nom de lieu car le Service Google Maps peut ne pas comprendre tout ce qu'on lui envoie)
5	Stockage des résultats GPS en base de données afin de ne plus avoir a refaire le processus précédent pour un nom de lieu déjà résolu
6	Lors de l'affichage des résultats de recherche sous forme cartographiée, Pleade va chercher dans la base de données les coordonnées GPS correspondant aux résultats de recherche pour les placer sur la carte.

Description

Le module GoogleMaps permet d'avoir une autre approche dans la recherche documentaire, en mettant en avant l'aspect géographique.

L'application Pleade, embarque le module google maps. Il peut être activé ou désactivé. Afin d'afficher des résultats sur une carte, il faut effectuer certaines actions comme activer le module et lancer une publication.

Collecte

Lors de la publication le module google maps va aller récupérer des noms de lieux pour ensuite les stocker dans une base de données. C'est la seule action faite lors de la publication d'un document.

Géocodage

Une fois les lieux étant stockés, on récupére leur position GPS en utilisant le service de traduction de noms de lieux en coordonnées GPS de google (géocodage). Cette étape est dissociée du processus de publication et est lancée depuis une URL.

Google impose une limite de traduction à hauteur de 2500 lieux par jour. Si la base de donnée contient plus de 2500 lieux, seuls les 2500 premiers lieux sont traduits et le processus s'arrête. Il devra être relancé autant de fois que nécessaire. Le processus reprendra à l'endroit où il s'est arrêté.

Lors du géocodage, les noms de lieux sont récupéré puis nettoyés a l'aide d'un fichier de configuration basé sur la syntaxe Reg Ex, celui ci peut enlever, modifier ou rajouter des termes afin de faciliter le travail du géocodage pour ensuite avoir de meilleurs résultats en terme de localisation.

Visualisation sur une carte

Le module GoogleMaps va vérifier si les lieux contenus dans les résultats de recherche ont des coordonnées GPS.

• Si oui, ils sont récupérés pour afficher les résultats de recherche sur une carte.

Une icône (marker) permet de visualiser le lieu sur la carte. Un clic affiche les informations suivantes : un titre (obligatoire), une date (optionnel), un lieu (obligatoire) et une image (optionnel).

si plusieurs documents ont un même point de localisation, ils seront tous affichées lors de l'ouverture de la bulle d'information.

• Sinon :

1. Le module tente de les résoudre "à la volée" (paramètre à activer), puis les affiche si il les trouve. Attention, ne pas utiliser sur un grand nombre de résultats non géocodés en Production.
2. Si le module GoogleMaps ne trouve pas de lieu ou que l'option de résolution ci-dessus n'est pas activé, aucun point ne sera affiché sur la carte.

Ou sont localisés les fichiers afin de l'utiliser ?

Les fichiers concernant pleade-entreprise-gmaps sont localisés dans pleade entreprise.

Les fichiers JAVA:

• org.pleade.beans
  • GoogleBean.java
• org.pleade.database.utils
  • DAOConfigurationException.java
  • DAOException.java
  • DBConnexion.java
• org.pleade.database.dao
  • DAO.java
  • GoogleDAO.java
• org.pleade.gmapservice
  • GmapsService.java
• org.pleade.google
  • GeodataType.java
  • GoogleWebService.java
  • GoogleWebServiceData.java
  • GoogleWebServiceOneData.java
  • IGoogleWebService.java
  • TypeData.java
• com.ajlsm.cocoon.generation
  • GmapsGenerator.java

Les Fichiers XSL :

• /pleade-entreprise/src/webapp/module-eadeac/xsl/maps-results.xsl
• /pleade-entreprise/src/webapp/module-eadeac/xsl/omaps-results.xsl

Les fichiers javascript:

• /pleade-entreprise/src/webapp/theme/js/gmaps/gmaps.js
• /pleade-entreprise/src/webapp/theme/js/omaps/omaps.js

Les fichiers de style:

• /pleade-entreprise/src/webapp/theme/css/gmaps.css
• /pleade-entreprise/src/webapp/theme/css/leaflet.css

Les Fichiers de propritété :

• /pleade-entreprise/src/webapp/WEB-INF/properties/pleade-plus.properties
• /pleade-entreprise/src/webapp/module-eadeac/conf/gmaps-filter.xml

Design de l'application

A Propos des autres API

Google maps Geocode est une API qui permet de récupérer des données géographiques telles que des coordonées GPS ou des adresses a partir d'un nom de lieu, cependant, il existe d'autres API pour faire ce travail:

• OpenStreetMap Nominatim API:
  • http://wiki.openstreetmap.org/wiki/Nominatim
• Yahoo Geo API:
  • http://developer.yahoo.com/boss/geo/
• MapQuest API:
  • http://www.mapquestapi.com/geocoding/
• DataScienceToolkit:
  • http://www.datasciencetoolkit.org/
• Microsoft Bing API:
  • http://msdn.microsoft.com/en-us/library/ff701715.aspx
• Cloudmade API:
  • http://cloudmade.com/documentation/geocoding/
• Openaddresses API:
  • http://code.google.com/p/openaddresses/wiki/RESTService
• Gisgraphy API:
  • http://www.gisgraphy.com/

Voici une liste de 74 API de Géocodage: http://www.programmableweb.com/apitag/geocoding

Update(25/02/2014)

Important

Notice :

Pour facilement retrouver modifier le design de la carte, on peut aller sur ce site http://googlemapbuilder.mynameisdonald.com/
Pour LeafLet la selection se fait directement sur la carte en haut a droite.

La documentation concernant Google se trouve ici: https://developers.google.com/maps/documentation/geocoding/

Explications sur l'api google maps (Affinage des requêtes, réponses, ...): http://www.touraineverte.com/google-geocoding-api/index.html