feat: useLMarkerCluster returns created layers + add popup as prop

Author: Gugustinette

docs/guide/marker-cluster.md

@@ -3,8 +3,6 @@
 The guide explains how to use the [Leaflet.markercluster](https://github.com/Leaflet/Leaflet.markercluster) plugin.
 A dedicated composable is available to help you use this plugin.
 
-Options for the markers are the same as the ones available in the [Leaflet documentation](https://leafletjs.com/reference.html#marker).
-
 ::: warning
 This is only possible in a client-side environment. You should either :
 - Use a [Client-Only Page](https://nuxt.com/docs/guide/directory-structure/pages#client-only-pages).
@@ -37,7 +35,7 @@ export default defineNuxtConfig({
 It is very important to keep the manual import of Leaflet and the `:use-global-leaflet="true"` as leaflet.markercluster requires Leaflet to be loaded globally.
 :::
 
-```vue{9,23,28-61,65-68}
+```vue{9,23,28-50,54-57}
 <template>
   <div style="height:100vh; width:100vw">
     <h1>Marker Cluster</h1>
@@ -67,19 +65,8 @@ const map = ref(null) as any;
 
 // Create locations data (20 locations around Nantes)
 const locations = [
-  { name: 'Nantes', lat: 47.218371, lng: -1.553621, options: {
-    // Standard Leaflet Marker options
-    draggable: true,
-    icon: L.icon({
-      iconUrl: '/my-icon.png',
-      iconSize: [30, 30],
-    })
-  } },
-  {
-    // name is optional (no tooltip will be displayed if not provided)
-    /* name: 'Saint-Nazaire', */
-    lat: 47.273018, lng: -2.213733 
-  },
+  { name: 'Nantes', lat: 47.218371, lng: -1.553621 },
+  { name: 'Saint-Nazaire', lat: 47.273018, lng: -2.213733 },
   { name: 'La Baule', lat: 47.286835, lng: -2.393108 },
   { name: 'Pornic', lat: 47.112, lng: -2.102 },
   { name: 'Guérande', lat: 47.328, lng: -2.429 },
@@ -109,3 +96,98 @@ const onMapReady = () => {
 }
 </script>
 ```
+
+## Options
+
+Here are the options available for each marker in the `markers` prop.
+
+| Event name | Type   | Description                                                                                                        |
+| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
+| name       | string | **(optional)** Name of the location, will be displayed in a tooltip. If not provided, no tooltip will be displayed |
+| lat        | number | Latitude of the location                                                                                           |
+| lng        | number | Longitude of the location                                                                                          |
+| options    | object | **(optional)** Standard [Leaflet Marker options](https://leafletjs.com/reference.html#marker)                      |
+| popup      | string | **(optional)** If provided, it is considered as an HTML string and will be displayed as a popup on the marker      |
+
+## Recipes
+
+### Accessing the cluster group
+
+You can access the cluster group created by `useLMarkerCluster` to call any method from the [leaflet.markercluster API](https://github.com/Leaflet/Leaflet.markercluster?tab=readme-ov-file#events).
+
+```ts
+const locations = [{
+  name: 'Nantes',
+  lat: 47.218371,
+  lng: -1.553621
+}];
+const { markerCluster } = useLMarkerCluster({
+  leafletObject: map.value.leafletObject,
+  markers: locations
+});
+markerCluster.on('clusterclick', (event) => {
+  console.log('Cluster clicked');
+});
+```
+
+### Customizing the markers
+
+You can use a customize the markers by providing the `icon` option in the location object.
+
+```ts
+const locations = [{
+  name: 'Nantes',
+  lat: 47.218371,
+  lng: -1.553621,
+  options: {
+    draggable: true,
+    icon: L.icon({
+      iconUrl: '/my-icon.png',
+      iconSize: [30, 30],
+    })
+  } 
+}];
+
+useLMarkerCluster({
+  leafletObject: map.value.leafletObject,
+  markers: locations
+});
+```
+
+### Displaying a popup on a marker
+
+You can add a popup to a marker by providing the `popup` option in the location object.
+
+```ts
+const locations = [{
+  name: 'Nantes',
+  lat: 47.218371,
+  lng: -1.553621,
+  popup: '<h1>This is Nantes</h1>'
+}];
+
+useLMarkerCluster({
+  leafletObject: map.value.leafletObject,
+  markers: locations
+});
+```
+
+### Calling legacy methods from Leaflet
+
+You can access the markers created by `useLMarkerCluster`, and call any method from the [Leaflet Marker API](https://leafletjs.com/reference.html#marker).
+
+```ts
+const locations = [{
+  name: 'Nantes',
+  lat: 47.218371,
+  lng: -1.553621
+}];
+
+const { markers } = useLMarkerCluster({
+  leafletObject: map.value.leafletObject,
+  markers: locations
+});
+markers.forEach(marker => {
+  marker.bindPopup(L.popup().setContent('</h1>Hello marker</h1>'));
+});
+```

playground/pages/map/markercluster.client.vue

@@ -27,20 +27,32 @@ const map = ref(null) as any;
 
 // Create locations data (20 locations around Nantes)
 const locations = [
-  { name: 'Nantes', lat: 47.218371, lng: -1.553621, options: {
+  {
+    name: 'Nantes',
+    lat: 47.218371,
+    lng: -1.553621,
     // Standard Leaflet Marker options
-    draggable: true,
-    icon: L.icon({
-      iconUrl: '/nuxt-leaflet-logo.png',
-      iconSize: [30, 30],
-    })
-  } },
+    options: {
+      draggable: true,
+      icon: L.icon({
+        iconUrl: '/nuxt-leaflet-logo.png',
+        iconSize: [30, 30],
+      })
+    } 
+  },
   {
     // name is optional (no tooltip will be displayed if not provided)
     /* name: 'Saint-Nazaire', */
-    lat: 47.273018, lng: -2.213733 
+    lat: 47.273018, lng: -2.213733
+  },
+  {
+    name: 'La Baule',
+    lat: 47.286835,
+    lng: -2.393108,
+    // A popup can be displayed when clicking on the marker
+    // It should be a string formatted as HTML
+    popup: 'La Baule'
   },
-  { name: 'La Baule', lat: 47.286835, lng: -2.393108 },
   { name: 'Pornic', lat: 47.112, lng: -2.102 },
   { name: 'Guérande', lat: 47.328, lng: -2.429 },
   { name: 'Clisson', lat: 47.087, lng: -1.276 },
@@ -61,10 +73,16 @@ const locations = [
 ];
 
 // When the map is ready
-const onMapReady = () => {
-  useLMarkerCluster({
+const onMapReady = async () => {
+  const { markers, markerCluster } = await useLMarkerCluster({
     leafletObject: map.value.leafletObject,
     markers: locations
   });
+  // Access the markers
+  markers[3].bindPopup('Hello Pornic');
+  // Access the markerCluster
+  markerCluster.on('clusterclick', (event: any) => {
+    console.log('Cluster clicked', event);
+  });
 }
 </script>

src/runtime/composables/useLMarkerCluster.ts

@@ -1,10 +1,14 @@
-import type { MarkerOptions, Map } from 'leaflet'
+import type { MarkerOptions, Map, Marker } from 'leaflet'
 
 interface MarkerProps {
   name?: string
   lat: number
   lng: number
   options?: MarkerOptions
+  /**
+   * Should be a string formatted as HTML
+   */
+  popup?: string
 }
 
 interface Props {
@@ -23,6 +27,9 @@ export const useLMarkerCluster = async (props: Props) => {
   // Initialize marker cluster
   const markerCluster = new MarkerClusterGroup()
 
+  // Create an array to store the markers
+  const markers = [] as Marker[]
+
   // For each marker in props
   props.markers.forEach((location: any) => {
     // Create a Leaflet marker
@@ -31,10 +38,24 @@ export const useLMarkerCluster = async (props: Props) => {
       ...location.options,
     })
 
+    // If a popup is provided, bind it to the marker
+    if (location.popup) {
+      marker.bindPopup(L.popup().setContent(location.popup))
+    }
+
     // Add the marker to the cluster
     markerCluster.addLayer(marker)
+
+    // Add the marker to the markers array
+    markers.push(marker)
   })
 
   // Add the marker cluster to the map
   props.leafletObject.addLayer(markerCluster)
+
+  // Return the markerCluster and markers
+  return {
+    markerCluster,
+    markers,
+  }
 }

test/fixtures/markercluster/app.vue

@@ -27,20 +27,32 @@ const map = ref(null) as any
 
 // Create locations data (20 locations around Nantes)
 const locations = [
-  { name: 'Nantes', lat: 47.218371, lng: -1.553621, options: {
+  {
+    name: 'Nantes',
+    lat: 47.218371,
+    lng: -1.553621,
     // Standard Leaflet Marker options
-    draggable: true,
-    icon: L.icon({
-      iconUrl: '/nuxt-leaflet-logo.png',
-      iconSize: [30, 30],
-    }),
-  } },
+    options: {
+      draggable: true,
+      icon: L.icon({
+        iconUrl: '/nuxt-leaflet-logo.png',
+        iconSize: [30, 30],
+      }),
+    },
+  },
   {
     // name is optional (no tooltip will be displayed if not provided)
     /* name: 'Saint-Nazaire', */
     lat: 47.273018, lng: -2.213733,
   },
-  { name: 'La Baule', lat: 47.286835, lng: -2.393108 },
+  {
+    name: 'La Baule',
+    lat: 47.286835,
+    lng: -2.393108,
+    // A popup can be displayed when clicking on the marker
+    // It should be a string formatted as HTML
+    popup: 'La Baule',
+  },
   { name: 'Pornic', lat: 47.112, lng: -2.102 },
   { name: 'Guérande', lat: 47.328, lng: -2.429 },
   { name: 'Clisson', lat: 47.087, lng: -1.276 },
@@ -61,10 +73,16 @@ const locations = [
 ]
 
 // When the map is ready
-const onMapReady = () => {
-  useLMarkerCluster({
+const onMapReady = async () => {
+  const { markers, markerCluster } = await useLMarkerCluster({
     leafletObject: map.value.leafletObject,
     markers: locations,
   })
+  // Access the markers
+  markers[3].bindPopup('Hello Pornic')
+  // Access the markerCluster
+  markerCluster.on('clusterclick', (event: any) => {
+    console.log('Cluster clicked', event)
+  })
 }
 </script>