Description
This filter changes the marker cluster options that are sent to the map. The options are different for each map provider: Google Maps, Mapbox, and OpenStreetMap and Stadia Maps, which both use Leaflet.
The filter only runs when marker clusters are on. Turn them on with Enable marker clusters? on Store Locator > Settings > Markers, or with marker_clusters="true" on the [wpsl] or [wpsl_map] shortcode. The same options are used for every map on the page.
Check the settings first. Max zoom level and Cluster size work for every provider. With Google Maps you also set the cluster style, the colors and the Cluster marker shape there. If you don’t see these options, switch to Advanced mode at the top of the Store Locator admin pages. See Change the Marker Cluster Style for what you can change per provider.
wpsl_get_active_map_service(), which returns gmaps, mapbox, osm or stadia.Parameters
$props (array) The cluster options for the active map provider. Values from the settings are strings, for example '60'.
Google Maps
| Key | Default | Description |
|---|---|---|
style | default | default or interpolation, from the "Default style" and "Interpolation style" options. |
excludeStartMarker | 0 | Keep the start marker out of the clusters. From "Exclude the start marker from the marker cluster?". |
zoom | 16 | The highest zoom level at which markers are still clustered. From "Max zoom level". |
size | 40 | How close markers need to be, in pixels, to end up in the same cluster. From "Cluster size". |
lowDensityColor, highDensityColor, labelColor | #0000ff, #ff0000, #ffffff | The cluster and label colors. From the color settings, after the wpsl_cluster_marker_colors filter. |
templates | The circles | The SVG code and size of the cluster marker, with a default and an interpolation key. Each has an svg and a size in pixels. From "Cluster marker shape", see wpsl_cluster_marker_shapes. |
labelSize | '50' | The font size of the number, on the 240 x 240 grid of the SVG. It is worked out from the template size, so the number looks the same with every shape. |
Mapbox
| Key | Default | Description |
|---|---|---|
excludeStartMarker | 0 | Keep the start marker out of the clusters. From "Exclude the start marker from the marker cluster?". |
maxZoom | 14 | The highest zoom level at which markers are still clustered. From "Max zoom level". |
radius | 20 | How close markers need to be, in pixels, to end up in the same cluster. From "Cluster size". |
circle | See below | The look of the clusters, with a color and a radius key. |
circle holds two arrays with five values each. The first value is used for clusters below the first threshold, the third from the first threshold, and the fifth from the second threshold.
color:[ '#51bbd6', 100, '#f1f075', 750, '#f28cb1' ]. Blue below 100 locations, yellow from 100, and pink from 750.radius:[ 20, 100, 30, 750, 40 ]. The radius of the circle in pixels, with the same thresholds.
Keep five values in both arrays. The map only reads the first five, so extra steps are ignored.
OpenStreetMap and Stadia Maps
These keys are passed to Leaflet.markercluster as its options.
| Key | Default | Description |
|---|---|---|
spiderfyOnMaxZoom | true | At the highest zoom level, clicking a cluster spreads out its markers. |
showCoverageOnHover | false | Show the area that a cluster covers when you hover over it. |
zoomToBoundsOnClick | true | Clicking a cluster zooms in on its markers. |
excludeStartMarker | 0 | Keep the start marker out of the clusters. From "Exclude the start marker from the marker cluster?". |
maxClusterRadius | Not set, Leaflet uses 80 | How close markers need to be, in pixels, to end up in the same cluster. Only included when "Cluster size" is filled in. |
disableClusteringAtZoom | Not set | From this zoom level on, the markers are no longer clustered. Only included when "Max zoom level" is filled in. |
You can add other Leaflet.markercluster options, as long as the value is a string, number, boolean or array.
Usage
This example changes the colors of the Mapbox clusters. It only changes the options when the circle key exists, so it does nothing with the other providers.
| add_filter( 'wpsl_cluster_marker_props', 'my_mapbox_cluster_colors' ); | |
| function my_mapbox_cluster_colors( $props ) { | |
| if ( isset( $props['circle'] ) ) { | |
| // Color below 100, threshold, colour 100 - 750, threshold, colour above 750. | |
| $props['circle']['color'] = [ '#2b83ba', 100, '#fdae61', 750, '#d7191c' ]; | |
| } | |
| return $props; | |
| } |
$props['circle']['radius'] uses the same format, for example [ 20, 100, 30, 750, 40 ]. You can also change the thresholds 100 and 750.
This example is for OpenStreetMap and Stadia Maps. It shows the area that a cluster covers when you hover over it, in a blue outline, and places the markers further apart when a cluster opens at the highest zoom level. The spiderfyOnMaxZoom key only exists for these providers.
| add_filter( 'wpsl_cluster_marker_props', 'my_leaflet_cluster_options' ); | |
| function my_leaflet_cluster_options( $props ) { | |
| // Only OpenStreetMap and Stadia Maps use this key. | |
| if ( isset( $props['spiderfyOnMaxZoom'] ) ) { | |
| // Show the area that a cluster covers when you hover over it. | |
| $props['showCoverageOnHover'] = true; | |
| $props['polygonOptions'] = [ 'color' => '#2b83ba', 'weight' => 2 ]; | |
| // Place the markers further apart when a cluster opens at the highest zoom level. | |
| $props['spiderfyDistanceMultiplier'] = 2; | |
| } | |
| return $props; | |
| } |
Options that need a JavaScript function, like iconCreateFunction, can’t be set from PHP. For those, use the wpslMarkerClusterGroup JavaScript hook. It receives the same options before they are passed to Leaflet, and must return them. The colors of these clusters come from CSS, see Change the Marker Cluster Style.
With Google Maps, change the style, colors and shape on the Markers tab first. Use this filter when you need to change them in code, for example $props['size'] or $props['highDensityColor'] after checking that isset( $props['templates'] ).
Changelog
| Version | Description |
|---|---|
| 3.0 | Introduced. |
Source File
This filter is located in /includes/frontend/maps/class-markers.php.
Placement
The code needs to be placed in the functions.php file inside your active theme folder.