Documentation

MapUx est un composant dédié au framework Symfony. Il permet d'ajouter simplement des cartes, des markers et toutes sortes d'objets cartographiques dans un projet Symfony.
Il propose plusieurs possibilités pour rendre vos cartes interactives.

Version 1.1
Attention, MapUx est encore en cours d'écriture et des remodelages réguliers sont effectués. Malgré tout le soin apporté à son développement et les différents tests effectués, il est possible qu'il reste des bugs.
Si tel était le cas, merci de nnous le signaler https://github.com/frvaillant/mapux/issues Merci de votre compréhension.

Installation

Pré-requis
- Symfony > 4.4
- PHP > 7.2
- Composer
- Webpack Encore

L'installation de MapUx se fait en 3 étapes

    
composer require frvaillant/mapux
    
   

        
yarn install --force
// ou npm install --force
    
    

            
php bin/console mapux:install
    

                    
require ('leaflet/dist/leaflet')

export class MapuxEvents {
    //******************************************************
    // PLEASE DO NOT CHANGE CONSTRUCTOR ********************
    //******************************************************

    /**
     *
     * @param target : the target of the event
     * @param map : the instance of your map
     * @param icons : the available icons provided by mapux (default, red, ....)
     */
    constructor(target, map, icons) {
        this.target = target // Should be the map or a marker
        this.map = map
        this.icons = icons
    }

    /* *******************************************************
    WRITE YOUR METHODS BELOW

    addIcon(event) {
        L.marker([event.latlng.lat, event.latlng.lng], {
            icon:this.icons.red
        }).addTo(this.map)
    }
     */


}
                    
                

    
yarn encore dev
    

Exemple simple et rapide

Pour effectuer un premier essai, voici un exemple qui vous permettra de comprendre le principe de base du fonctionnement de MapUx.

Pour cet exemple, dans un controlleur, nous allons créer une carte, lui ajouter un marker, ajouter une popup et un événement à ce marker :

    
use MapUx\Builder\MapBuilder;
use MapUx\Model\Marker;
use MapUx\Model\Popup;

  // [...]

// Instanciation du MapBuilder
$mapBuilder = new MapBuilder();

// Création de la carte avec ses coordonnées de centrage et niveau de zoom par défaut
$map = $mapBuilder->createMap();

// Création d'un marker positionné par défaut
$marker = new Marker();

// Création et ajout d'une popup pour le marker
$popup = new Popup('My popup text');
$marker->addPopup($popup);

// Ajout d'un événement au clic sur le marker
$markerClickFunction = 'alert("your click event has been triggered");';
$marker->addEvent('click', $markerClickFunction);

// Ajout du marker à la carte
$map->addMarker($marker);

// Rendu de la carte dans le template Twig
return $this->render('home/index.html.twig', [
    'map' => $map,
]);
    

Dans votre fichier twig, il vous suffit d'ajouter

    
// mymap est l'id de la div qui contiendra la carte
{{ render_map('mymap', map) }}
    

Les cartes

Leaflet : Documentation sur les cartes

Pour créer une carte, vous n'avez pour ainsi dire besoin de rien

    
use MapUx\Builder\MapBuilder;
$mapBuilder = new MapBuilder();
$map = $mapBuilder->createMap();
    

Par défaut la carte est centrée sur Bordeaux avec un niveau de zoom de 10.

La méthode createMap peut aussi prendre des paramètres pour :
- centrer la carte sur un point choisi - Ajuster le niveau de zoom de départ - ajouter un fond de carte sous forme de lien (voir plus bas)

    
$map = $mapBuilder->createMap(44.00, -0.57, 10);
    

Une carte sera alors créée avec un fond de carte par défaut, centrée sur le point de latitude 44 et de longitude -0.57 avec un niveau de zoom de 10.

Tous ces paramètres (latitude, longitude, zoom, fond de carte) peuvent être passés dans le constructeur avec la méthode createMap du Builder ou spécifiés à l'aide des setters adéquats :

    
$map->setZoomLevel(10);
$map->setCenterLatitude(44.00);
$map->setCenterLongitude(-0.57);
    

Vous pouvez également ajouter des options à votre carte (toutes les options de Leaflet sont disponibles) en utilisant la méthode setOptions :

        
$map->setOptions([
    'zoomControl' => false
]);
        
    

Vous pouvez ajouter une légende automatique à votre carte : voir le chapitre Légende

Fond de carte OpenStreetMap

Pour choisir un fond de carte, il suffit d'utiliser la méthode setBackground() :

    
$map->setBackground('http://{s}.tile.stamen.com/toner-lite/{z}/{x}/{y}.png');
    

Vous trouverez une liste des fonds de carte disponibles ici : https://www.creazo.fr/listing-des-fonds-de-cartes-dopen-street-map/

Fonds de cartes Geoportail & IGN

Doc GeoServices : https://geoservices.ign.fr/index.html

Pour utiliser les ressources de l'IGN (France), vous devez vous procurer une clé d'API auprès de l'IGN. Le formulaire de demande est disponible ici : https://www.sphinxonline.com/SurveyServer/s/etudesmk/Geoservices/questionnaire.htm
J'ai obtenu une réponse en moins de 24h :-)

MapUx ne propose pour l'instant que les ressources Géoportail accessibles gratuitement. Une évolution future permettra d'accéder à toutes les ressources.

Les ressources disponibles sont les suivantes :

Pour utiliser une ressource IGN, il faut ajouter une couche (voir plus bas l'utilisation détaillée des couches) à votre carte. MapUx fournit une classe spéciale à cet effet.

Elle a besoin de 2 paramètres :
- votre clé d'API
- l'identifiant de la ressource

Même si vous pouvez spécifier votre clé IGN dans le controlleur, nous vous conseillons de la placer dans un endroit secret
Par exemple en la définissant dans votre fichier .env.local

    
$ignLayer = new IgnLayer('votreCleApi', 'ORTHOIMAGERY.ORTHOPHOTOS');
$map->addLayer($ignLayer);
    

Bien sur pour des raisons de performances, si vous utilisez les vues aériennes ou les cartes IGN, il peut être recommandé de désactiver le fond de carte par défaut avant d'ajouter la couche IGN.

    
$map->removeBackground();
$map->addLayer($ignLayer);
    

Quelques exemples

Les markers

Doc Leaflet : https://leafletjs.com/reference-1.7.1.html#marker

Il peut être très utile d'ajouter des markers à une carte pour matérialiser des points particuliers.
MapUx fournit une classe spécifique pour cela.

Pour créer un marker, il suffit de spécifier les coordonnées de son emplacement.

    
use MapUx\Model\Marker;
$marker = new Marker(44.00, -0.57);
$map->addMarker($marker);
    

Toutes les options de Leaflet peuvent être ajoutées avec la méthode setOptions().

    
$marker->setOptions([
    'draggable' => true
]);
    

Vous pouvez ajouter plusieurs markers à votre carte en une seule fois :

    
$mark1 = new Marker(44, 1);
$mark2 = new Marker(45, 2);
$map->setMarkers([$mark1, $mark2]);
    

Icones personnalisés

Doc Leaflet : https://leafletjs.com/reference-1.7.1.html#icon

MapUx intègre le marker par défaut de leaflet (bleu) et met 7 autres markers à votre disposition.

    
$icon = new Icon('yellow');
$icon = new Icon('orange');
$icon = new Icon('red');
$icon = new Icon('pink');
$icon = new Icon('purple');
$icon = new Icon(); // Marker par défaut
$icon = new Icon('green');
$icon = new Icon('brown');
$icon = new Icon('black');
    

Vous pouvez également créer votre propre icone :

    
$icon = new Icon();
$icon->setIconPicture('url-de-votre-image');
$marker->setIcon($icon);
    

Vous pouvez ajouter une classe personnalisée à un icone :

    
$icon->setClassName('mon-joli-icone');
    

Vous pouvez aussi spécifier l'icone dans les options du marker :

    
$marker->setOptions([
    'icon' => $icon
]);
    

Et bien sur, vous pouvez changer la taille de l'icone, son ombre ... en accord avec les spécifications de leaflet.

Popups

Doc leaflet : https://leafletjs.com/reference-1.7.1.html#popup

Leaflet propose la possibilité d'ajouter des fenêtres popup qui s'affichent au clic sur un marker et dans lesquelles il est possible d'ajouter du contenu html. Avec MapUx, vous pouvez ajouter une popup à un marker en utilisant la classe Popup et la méthode addPopup() du marker :

    
use MapUx\Model\Popup;
$popup = new Popup();
    

Pour ajouter du contenu dans votre popup, vous pouvez passer le code html en paramètre du constructeur ou utiliser la méthode setContent() de l'objet Popup.

    
// Par le constructeur
$popup = new Popup('<p>All the html you want in your popup</p>');
// Ou avec la méthode setContent()
$popup = new Popup();
$popup->setContent('<span>All the html you need in your popup</span>');
    

Les options de leaflet sont disponibles avec la méthode setOptions.

    
$popup->setOptions([
    'minWidth' => 500
]);
    

Pour ajouter la popup à votre marker :

    
$marker->addPopup($popup);
    

Les layers

Doc Leaflet : https://leafletjs.com/reference-1.7.1.html#layer

Vous pouvez ajouter autant de couches que vous le souhaitez à votre carte et ainsi afficher des cartes enrichies.
La classe Layer est prévue pour cela.

Le principe est le suivant :

    
$layer = new Layer();
$map->addLayer($layer);
    

Exemple avec des couches IGN sur un fond OSM

    
$mapBuilder = new MapBuilder();
$map = $mapBuilder->createMap();
$map->setBackground('http://{s}.tile.stamen.com/toner-lite/{z}/{x}/{y}.png');
$levels = new IgnLayer('votre-cle-api', 'ELEVATION.SLOPES');
$levels->setOptions([
    'opacity' => 0.5,
    'attribution' => "IGN-F/Geoportail",
]);
$map->addLayer($levels);

$adminLimits = new IgnLayer('votre-cle-api', 'LIMITES_ADMINISTRATIVES_EXPRESS.LATEST');
$adminLimits->setOptions([
    'opacity' => 1,
    'attribution' => "IGN-F/Geoportail",
]);
    $map->addLayer($adminLimits);
    

Ajouter un polygone, un cercle ou une ligne

Doc GeoJson : https://leafletjs.com/reference-1.7.1.html#geojson
Doc Circle : https://leafletjs.com/reference-1.7.1.html#circle
Doc Polyline : https://leafletjs.com/reference-1.7.1.html#polyline

Avec MapUx, vous pouvez très facilement ajouter des formes sur votre carte.
Pour un cercle, vous aurez besoin des coordonnées de son centre et la taille en mètres de son rayon.
Pour un polygone ou une ligne, vous aurez besoin d'un tableau de points comme ci-dessous :

        
$points = [
    [lat, lng],
    [lat, lng],
    // ...
];
        
    

Ajouter un polygone

                
$polygon = new Polygon($points);
$map->addLayer($polygon);
                
            

Ajouter une ligne

                
$line = new Polyline($points);
$map->addLayer($line);
                
            

Ajouter un cercle

                
$circle = new Circle(44.54, -0.65, 2000); // lat, lng, radius
$map->addLayer($circle);
                
            

Ajouter un rectangle

            
$rectangle = new Rectangle([44, 0], [45, 1]);
$map->addLayer($rectangle);
            
        

Relier des markers

Si vous souhaitez relier vos markers, vous pouvez récupérer tous les points avec la méthode getPointsFromMarkers().

                
$points = $map->getPointsFromMarkers();
$pl = new Polyline($points);
$map->addLayer($pl);
                
            

Ajouter une grille

Il y a deux sortes de grilles utilisables : une grille fixe, placée entre deux points avec une maille métrique, et une grille dont la maille s'ajuste en fonction de l'échelle de zoom.
- Pour ajouter une grille fixe, spécifiez les coordonnées des deux extrémités S-O et N-E de la grille, ainsi que la largeur de chaque case (en m)
- Une grille ajustable ne prend aucun paramètres : new AdjustableGrid().

            
$grid = new Grid([42, -3], [50, 7], 50000);
$map->addLayer($grid);
            
        

Il est bien sur possible de changer l'apparence de vos formes. Les méthodes suivantes sont là pour cela :

        
            $layer->setFillColor('#ff0000'); // remplissage
            $layer->setColor('#000000'); // bordure
            $layer->setOpacity(0.9); // bordure
            $layer->setFillOpacity(0.5); // remplissage
            $layer->setWeight(3); // épaisseur de la bordure
        
    

Regrouper des markers au sein d'une grille

Vous pouvez facilement créer des regroupements de markers à l'aide d'un maillage du territoire que vous analysez. Ainsi, au lieu d'afficher tous vos markers, vous pouvez présenter une synthèse de leur répartition.

Commencez par stocker tous vos markers dans un tableau. Ajoutez une grille à votre carte. Affichez les clusters.

    
// On définit une grille avec les coordonnées de son coin S-O et de son coin N-E et la largeur d'une maille en mètres.
$grid = new Grid([43, -2], [45, 2], 20000);
$grid->setFillOpacity(0); // Pour ne pas remplir les cases de la grille
$map->addLayer($grid);
    

Vous devriez alors avoir ceci :

    
$grid->addMarkersClusters($map, $markers);
    

            
$grid->addMarkersClusters($map, $markers, false);
            
        

        
$grid->createEmptyRectangles($map);
        
    

Si vous avez laissé l'affichage de la légende à true dans la méthode addMarkersClusters, alors, en ajoutant la légende à la carte, la légende de vos clusters s'affichera automatiquement

            
$map->addLegend();
            
        

Voir la rubrique légende pour plus d'informations

        
$options = [
    0 => [
        'fillColor' => '#000000',
        'fillOpacity' => 0.5,
        'color' => '#000000',
        'opacity' => 1,
        'weight' => 2
    ],
    5 => [
        'fillColor' => '#00FF00',
        'fillOpacity' => 0.5,
        'color' => '#00FF00',
        'opacity' => 1,
        'weight' => 2
    ], ....
        
    

            
$grid->getGridPoints()
            
        

            
$grid->getMarkerBoxes()
            
        

            
$grid->getEmptyBoxes()
            
        

Exemple complet

Le code ci-dessous génèrera le rendu ci-après

            
$number = 0;
while ($number < 3000) {
    $number++;
    $marker = new Marker(rand(43000000,46000000)/1000000, rand(-2000000, 2000000)/1000000);
    $markers[] = $marker;
}

$grid = new Grid([43, -2], [45, 2], 20000);
$grid->setFillOpacity(0);
$map->addLayer($grid);

$loptions = [
    0 => ['fillColor' => '#fdd835', 'fillOpacity' => 0.8, 'color' => '#000', 'opacity' => 1, 'weight' => 1],
    7 => ['fillColor' => '#f44336', 'fillOpacity' => 0.8, 'color' => '#000', 'opacity' => 1, 'weight' => 1],
    14 => ['fillColor' => '#7b1fa2', 'fillOpacity' => 0.8, 'color' => '#000', 'opacity' => 1, 'weight' => 1],
    21 => ['fillColor' => '#1a237e', 'fillOpacity' => 0.8, 'color' => '#000', 'opacity' => 1, 'weight' => 1],
];
$grid->addMarkersClusters($map, $markers, true, $loptions);
$map->setZoomLevel(8);
$map->setCenterLatitude(44);
$grid->createEmptyRectangles($map);

// Légende pour les cases vides
$map->addLegendItem(
    [
        'type' => 'square',
        'title' => 'cases vides',
        'fillColor' => '#ff0000'
    ]
);

$map->addLegend();
            
        

Evénements

Doc leaflet : https://leafletjs.com/reference-1.7.1.html#map-event

Un des intérêts de Leaflet est de pouvoir rendre les cartes interactives. Chaque objet leaflet est à l'écoute d'événements. Lorsqu'un de ceux-ci se produit, une fonction javascript peut être executée.
Par exemple, il est possible d'ajouter un marker au clic sur la carte, ou déclencher une alerte lorsque l'on déplace un marker.
Pour créer un événement, le plus simple est d'utiliser la méthode addEvent sur une carte ou un marker.

Vous pouvez ajouter des événements sur tous vos objets : carte, markers, layers

Méthode 1 : Ajouter des fonctions sous forme de texte

    
$maFonction = 'alert("evenement déclenché");';
$marker->addEvent('click', $maFonction);
    

Quelque soit la fonction javascript que vous ajoutez, la variable "event" est toujours disponible afin de vous permettre d'accéder à certains éléments.
Par exemple, pour masquer un marker lorsqu'il est cliqué :

    
$maFonction = 'event.target.remove();';
$marker->addEvent('click', $maFonction);
    

Attention, lors de l'ajout de fonctions javascript avec cette méthode, n'oubliez pas d'ajouter un ";" à la fin de chaque instruction.

Toutefois, cette méthode, bien que pratique, peut s'avérer compliquée et illisible si de nombreuses fonctions javascript ou si des fonctions complexes sont nécessaires.
Pour cela, MapUx vous fournit une classe javascript qui est installée dans assets/js/mapux/MapuxEvents. Il suffit d'y ajouter les méthodes dont vous avez besoin.
Cette classe vous permet également d'accéder facilement à l'instance de la carte et de disposer de l'icone par défaut.

Méthode 2 : utiliser la classe javascript MapuxEvents

Cette classe a été installée dans votre dossier assets/js/mapux et contient le code suivant :

    
export class MapuxEvents {
    constructor(target, map, icons) {
        this.target = target // Target est l'objet sur lequel vous ajoutez un evenement (map ou marker)
        this.map = map
        this.icons = icons // Vous donne accès à tous les icones fournis avec mapUx. Ex : this.icons.default ou this.icon.red
    }
}
    

Si vous souhaitez ajouter un marker au clic sur la carte, créez une méthode addIcon dans cette classe :

    
export class MapuxEvents {
    constructor(target, map, icons) {
        this.target = target // Should be the map or a marker
        this.map = map
        this.icons = icons
    }

    addIcon(event) {
        L.marker([event.latlng.lat, event.latlng.lng], {
           icon : this.icons.default // N'oubliez pas de spécifier l'icone
       }).addTo(this.map)
    }
}
    

Dans votre controlleur, ajoutez ensuite :

    
$map->addEvent('click', 'addIcon');
    

Si vous le souhaitez, vous pouvez également passer des paramètres sous forme d'un tableau dans votre fonction.

Côté javascript :

    
addIcon(event, params) {

    const marker = L.marker([event.latlng.lat, event.latlng.lng], {
       icon : this.defaultIcon // N'oubliez pas de spécifier l'icone
    }).addTo(this.map)

    marker.on('click', (e) => {
        console.log(params['word'])
    })
}
    

Côté PHP

    
$map->addEvent('click', 'addIcon', [
    'word' => 'the word to show in alert window'
]);
    

Ajouter plusieurs événements

Si vous souhaitez ajouter plusieurs événements en une seule fois, vous pouvez utilliser la méthode setEvents() :

    
// Si vous n'utilisez pas la classe MapuxEvents
$marker->setEvents([
    'click' => ['alert("marker is clicked");', null],
    'dragend' => ['console.log("drag marker is ended");', null],
]);
    
    ou
    
// Si vous utilisez la classe MapUxEvents
$map->setEvents([
    'eventName' => [
        'methodName',
        [
            'param1' => 'param1Value',
            'param2' => 'param2Value'
        ]
    ],
    'eventName2' => [
        'methodName',
        null
    ]
]);
    

Ajouter une légende sur la carte

Vous pouvez ajouter une légende automatique à votre carte. Pour cela vous devez spécifier un nom pour chaque élément que vous ajoutez à la carte et que vous souhaitez voir figurer en légende.

    
$marker->setLegendName('Arbre remarquables');
$marker2->setLegendName('Arbres morts');
$rectangle->setLegendName('Zone d\'étude');
$circle->setLegendName('Zone interdite');
    

Vous pouvez également donner un titre à votre carte. Il apparaîtra en tête de la légende.

    
$map->setTitle('Etude des arbres remarquables');
    

Vous pouvez ajouter ensuite la légende à votre carte en précisant si vous le souhaitez la position de celle-ci.
Par défaut, la légende se place en haut à droite. Les classes disponibles sont :
top-right (défaut), top-left, bottom-right et bottom-left

    
$map->addLegend(); // ou bien $map->addLegend('bottom-right');
    

MapUx génèrera alors la légende et l'ajoutera à votre carte.

MapUx ajoute automatiquement une échelle en bas à gauche de votre carte. Pour la supprimer, il faut utiliser la méthode removeScale().

                
$map->removeScale();
                
            

        
$map->addLegendItems([
[
    // Paramètre obligatoires
    'type' => 'square', // square, circle, line, picture or text sont possibles
    'title' => 'Le titre de votre choix',
    // Paramètres optionnels
    'fillColor' => '#000', // defaut #000
    'fillOpacity => 0.8, // defaut 0.5
    'color => '#FF0000', // defaut #000
    'opacity' => 0.8, // defaut 1
    'weight' => 3, // defaut 1
],
[
// Ajoutera un texte rouge à votre légende
    'type' => 'text',
    'title' => 'another élément',
    'color' => '#FF0000'
]
        
    

        
$map->addLegendItem(
[
    // Paramètre obligatoires
    'type' => 'square', // square, circle, line, picture or text sont possibles
    'title' => 'Le titre de votre choix',
    // Paramètres optionnels
    'fillColor' => '#000', // defaut #000
    'fillOpacity => 0.8, // defaut 0.5
    'color => '#FF0000', // defaut #000
    'opacity' => 0.8, // defaut 1
    'weight' => 3, // defaut 1
]);
        
    

Côté vues avec Twig

    
{{ render_map('your-map-id', map) }}
    

Et c'est tout :-)

La fonction twig render_map crée une div container contenant votre carte avec pour id "your-map-id" et par défaut la classe "ux-map". Le minimum de CSS nécessaire est fourni avec MapUx.

Vous pouvez ajouter vos propres classes css

    
{{ render_map('your-map-id', map, 'my-class-1 my-class-2') }}
    

La structure générée est la suivante :

    
<div class="mapux-container" id="your-map-id-container">
    <div class="mapux-map vos-propres-classes" id="your-map-id"></div>
    // Si vous ajoutez la légende
    <div class="mapux-legend vos-propres-classes position"></div>
</div>