Room

Room-Leaflet

Room-Leaflet est un composant basé sur Room permettant d’afficher des cartes interactives en utilisant la librairie JavaScript open source Leaflet.

Room-Leaflet est disponible sous la forme d’un module ECMAScript 6 (une version non ECMAScript est également disponible) qui comme Room, ne nécessite pas de système de construction (build tools). Room-Leaflet est donc utilisable directement dans un navigateur Web.

Installation

Room-Leaflet est disponible sur :

• GitHub : https://github.com/GreenerSoft/Room-Leaflet
• NPM : https://www.npmjs.com/package/room-leaflet
• jsDelivr : https://www.jsdelivr.com/package/npm/room-leaflet

Vous pouvez aussi auto-héberger Room-Suspense en téléchargeant l’un des fichiers suivants :

Le référencement du fichier dans vos pages dépend de la version que vous voulez utiliser.

Pour utiliser Room-Leaflet il faut importer la librairie Leaflet.

Pour rappel, la librairie Leaflet utilise un fichier CSS qui doit impérativement être chargé avant la librairie et il est indispensable de donner une dimension par CSS à l’élément <div> qui contient la carte (classe leaflet-container par défaut mais qui peut être changée via la propriété className du composant).

Version ESM

En version ESM, vous pouvez utiliser un élément <script> avec un attribut type à la valeur module, mais vous avez en plus la possibilité de laisser Room-Leaflet importer dynamiquement la librairie Leaflet en tant que module ECMAScript à la condition d’ajouter dans votre carte d’importation une entrée nommée Leaflet (en plus des entrées Room et RomLeaflet).

Pour que cette possibilité fonction vous devez passez par un CDN capable de convertir Leaflet en module ECMAScript 6, c’est très simple comme indiqué dans cette article de GreenerSoft.

Une carte d’importation est obligatoire en version ESM à minima pour indiquer où est le module Room.

Vous trouverez un exemple de carte d’importation dans le fichier index.html de notre dépôt Room-Test. Il contient par ailleurs plusieurs exemples d’utilisation de Room-Leaflet.

Version non ESM

En version non ESM, vous devez avoir un élément <script> dans votre page HTML avant ceux pour Room et Room-Leaflet.

Vous avez alors un objet RoomLeafet attaché à l’objet principal window qui permet d’appeler les fonctions (RoomLeaflet.MapContainer() par exemple).

Une autre solution plus simple consiste à utiliser l’affection par décomposition comme par exemple ici :

const {OpenStreetMapProvider, L, addTileLayer, MapContainer} = RoomLeaflet;

Vous pouvez alors par exemple appeler directement la fonction MapContainer() sans préfixer avec RoomLeaflet..

Fournisseur de tuiles

Pour afficher un fond de carte ou des couches à superposer sur une carte, un fournisseur de tuiles (tiles) doit être utilisé.

Un fournisseur de tuiles est décrit par un objet provider qui est constitué de 3 propriétés :

1. wms : Un booléen qui indique si le fournisseur de tuiles est de type WMS ou pas.
2. url : Une chaîne de caractères contenant l’URL donnant les tuiles.
3. options: Un objet avec les propriétés décrites comme options de la méthode L.tileLayer.wms() si la propriété wms est à true et les options de la méthode L.tileLayer() de Leaflet si la propriété wms est à false.

L’objet provider est utilisable avec les fonctions createTileLayer(), addTileLayer() et MapContainer() de Room-Leaflet.

La fonction OpenStreetMapProvider() de Room-Leaflet retourne un objet de cette forme.

Variable L

Classiquement avec Leaflet, la variable L contient l’objet qui permet d’appeler les méthodes de Leaflet (elle est attachée à l’objet principal window).

Cette variable est exportée par le module Room-Leaflet et il faut l’utiliser en version ESM surtout si vous laissez importer dynamiquement Leaflet par Room-Leaflet comme indiqué plus haut.

En version non ESM, la variable L est également disponible (c’est juste un alias de la variable L de window).

Fonctions

Room-Leaflet est minimaliste en exportant uniquement 7 fonctions.

Fonction EUCenter()

Cette fonction retrourne les coordonnées du centre de l’Europe sous la forme d’un tableau contenant la latitude et la longitude.

Fonction FranceCenter()

Cette fonction retourne les coordonnées du centre de la France.

Fonction USACenter()

Cette fonction retourne les coordonnées du centre des USA.

Fonction OpenStreetMapProvider()

Cette fonction retourne un objet décrivant OpenStreetMap comme fournisseur de tuiles de fond de carte.

Elle est utilisable avec les fonctions createTileLayer(), addTileLayer() et MapContainer() de Room-Leaflet.

Fonction createTileLayer()

Cette fonction retourne un objet TileLayer de la librairie Leaflet à partir d’un fournisseur de tuiles.

La signature de la fonction est :

createTileLayer(provider)

Le paramètre requis provider est un objet décrivant un fournisseur de tuiles.

Si la propriété wms de l’objet provider est à true, la fonction utilise la méthode L.tileLayer.wms() de Leaflet.

Si la propriété est à false, la fonction utilise la méthode L.tileLayer() de Leaflet.

La fonction createTileLayer() ne doit être appelée que via votre fonction mount() passée à la fonction MapContainer() car elle a besoin que la librairie Leaflet soit chargée.

Fonction addTileLayer()

Cette fonction créé et ajoute un objet TileLayer de la librairie Leaflet à une carte donnée et à partir d’un fournisseur de tuiles. Elle retourne l’objet créé.

La signature de la fonction est :

addTileLayer(map, provider)

Le paramètre requis map est un objet Map de Leaflet qui représente la carte dans laquelle le layer doit être ajouté.

Le paramètre requis provider est un objet décrivant un fournisseur de tuiles.

La fonction addTileLayer() utilise en interne la fonction createTileLayer() pour créer le layer.

La fonction addTileLayer() ne doit être appelée que via votre fonction mount() passée à la fonction MapContainer() car elle a besoin que la librairie Leaflet soit chargée.

Fonction MapContainer()

Cette fonction asynchrone retourne une promesse JavaScript qui après résolution donne le composant Room-Leaflet. Le composant est un élément <div> contenant une carte gérée par Leaflet ou un élément <p> si la librairie Leaflet n’est pas disponible (pas pu être chargée ou pas chargée).

En version ESM, c’est l’appel à cette fonction qui s’occupe de charger dynamiquement la librairie Leaflet en tant que module ECMAScript si la variable L n’est pas déjà renseignée.

La signature de la fonction est :

async MapContainer({id, className, provider, mount, unmount})

L’unique paramètre attendu est un objet pouvant contenir des propriétés toutes optionnelles :

• id : Une chaîne de caractères contenant l’identifiant CSS à utiliser pour l’élément <div>.
• className : Une chaîne de caractères contenant la ou les classes CSS à utiliser pour l’élément <div>.
• provider : Un objet décrivant le fournisseur de tuiles (fond de carte) à utiliser.
• mount : Une fonction appelée au montage de l’élément <div> dans le DOM.
• unmount : Une fonction appelée à la suppression de l’élément <div> du DOM.

Ces 5 propriétés sont spécifiques à Room-Leaflet mais vous pouvez en plus ajouter comme propriétés, toutes les options supportées par la méthode L.map() de Leaflet, par exemple center, zoom, maxZoom, scrollWellZoom, etc.

Les fonctions mount() et unmount() reçoivent un unique paramètre map qui est est un objet Map de Leaflet et qui représente la carte associée à l’élément <div>.

La fonction mount() permet par exemple d’ajouter d’autres éléments dans la carte comme des couches supplémentaires (fonction addTileLayer()), des marqueurs, des popups, etc. C’est aussi là qu’il est possible de créer des effets avec la fonction createEffect() de Room ou de démarrer des timers.

La fonction unmount() permet par exemple d’arrêter des timers démarrés dans la fonction mount() ou de supprimer des éléments mémorisés pour éviter des fuites de mémoire.

Exemple

Dans l’exemple suivant, une carte est affichée centrée sur les USA avec par dessus les intempéries en cours (pluie, grêle, neige) obtenues par les radars météorologiques du réseau NEXRAD.

Ceci est réalisé par le code suivant :

function MapNexrad() {
	return elements().div(
		Suspense({fallback: BounceLoader()},
			MapContainer({
				className: "mapContainer",
				provider: OpenStreetMapProvider(),
				mount: map => addTileLayer(map, NexradProvider()),
				center: USACenter(),
				scrollWheelZoom: false,
				zoom: 4
			})
		)
	);
}

Le composant retourné par la fonction MapContainer() étant asynchrone, il est passé comme enfant au composant Room-Suspense (il était possible de faire sans en déclarant la fonction MapNexrad() asynchrone et en utilisant le mot clé await devant l’appel de MapContainer()).

Le fond de carte est donné par la fonction OpenStreetMapProvider() via la propriété provider.

Une fonction est associée à la propriété mount qui se charge d’ajouter les tuiles des données météorologiques sur la carte quand elle est montée dans le DOM en utilisant la fonction addTileLayer() avec un fournisseur de tuiles donné par la fonction NexradProvider().

Les propriétés center, scrollWhellZoom et zoom (des options de la méthode L.map() de Leaflet) sont utilisées pour gérer le centrage et le zoom par défaut de la carte.

Vous retrouverez cet exemple et une version animée de cette carte dans notre dépôt Room-Test.