Add a custom container to the realtime plugin (#1869)

* Add cluster override

* Add tests

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add container argument to documentation

* Fix incorrect import

* Update realtime.py

No idea why this was gone in this branch.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

docs/user_guide/plugins/realtime.md

@@ -108,3 +108,27 @@ Realtime(
 
 m
 ```
+
+## Using a MarkerCluster as a container
+
+The subway stations in the previous example are not easy to distinguish at lower zoom levels.
+It is possible to use a custom container for the GeoJson. In this example we use a MarkerCluster.
+```{code-cell} ipython3
+import folium
+from folium import JsCode
+from folium.plugins import Realtime, MarkerCluster
+
+m = folium.Map(location=[40.73, -73.94], zoom_start=12)
+source = "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/subway_stations.geojson"
+
+container = MarkerCluster().add_to(m)
+Realtime(
+    source,
+    get_feature_id=JsCode("(f) => { return f.properties.objectid }"),
+    point_to_layer=JsCode("(f, latlng) => { return L.circleMarker(latlng, {radius: 8, fillOpacity: 0.2})}"),
+    container=container,
+    interval=10000,
+).add_to(m)
+
+m
+```

folium/plugins/realtime.py

@@ -1,9 +1,10 @@
-from typing import Union
+from typing import Optional, Union
 
 from branca.element import MacroElement
 from jinja2 import Template
 
 from folium.elements import JSCSSMixin
+from folium.map import Layer
 from folium.utilities import JsCode, camelize, parse_options
 
 
@@ -41,7 +42,11 @@ class Realtime(JSCSSMixin, MacroElement):
     remove_missing: bool, default False
         Should missing features between updates been automatically
         removed from the layer
-
+    container: Layer, default GeoJson
+        The container will typically be a `FeatureGroup`, `MarkerCluster` or
+        `GeoJson`, but it can be anything that generates a javascript
+        L.LayerGroup object, i.e. something that has the methods
+        `addLayer` and `removeLayer`.
 
     Other keyword arguments are passed to the GeoJson layer, so you can pass
     `style`, `point_to_layer` and/or `on_each_feature`. Make sure to wrap
@@ -70,6 +75,11 @@ class Realtime(JSCSSMixin, MacroElement):
             {{ this.get_name() }}_options["{{key}}"] = {{ value }};
             {% endfor %}
 
+            {% if this.container -%}
+                {{ this.get_name() }}_options["container"]
+                    = {{ this.container.get_name() }};
+            {% endif -%}
+
             var {{ this.get_name() }} = new L.realtime(
             {% if this.src is string or this.src is mapping -%}
                 {{ this.src|tojson }},
@@ -99,11 +109,13 @@ def __init__(
         get_feature_id: Union[JsCode, str, None] = None,
         update_feature: Union[JsCode, str, None] = None,
         remove_missing: bool = False,
+        container: Optional[Layer] = None,
         **kwargs
     ):
         super().__init__()
         self._name = "Realtime"
         self.src = source
+        self.container = container
 
         kwargs["start"] = start
         kwargs["interval"] = interval

tests/plugins/test_realtime.py

@@ -0,0 +1,66 @@
+"""
+Test Realtime
+------------------
+"""
+
+from jinja2 import Template
+
+import folium
+from folium.plugins import MarkerCluster, Realtime
+from folium.utilities import JsCode, normalize
+
+
+def test_realtime():
+    m = folium.Map(location=[40.73, -73.94], zoom_start=12)
+    source = "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/subway_stations.geojson"
+
+    container = MarkerCluster().add_to(m)
+
+    rt = Realtime(
+        source,
+        get_feature_id=JsCode("(f) => { return f.properties.objectid }"),
+        point_to_layer=JsCode(
+            "(f, latlng) => { return L.circleMarker(latlng, {radius: 8, fillOpacity: 0.2})}"
+        ),
+        container=container,
+        interval=10000,
+    )
+    rt.add_to(m)
+
+    tmpl_for_expected = Template(
+        """
+          {% macro script(this, kwargs) %}
+              var {{ this.get_name() }}_options = {{ this.options|tojson }};
+              {% for key, value in this.functions.items() %}
+              {{ this.get_name() }}_options["{{key}}"] = {{ value }};
+              {% endfor %}
+
+              {% if this.container -%}
+                  {{ this.get_name() }}_options["container"]
+                      = {{ this.container.get_name() }};
+              {% endif -%}
+
+              var {{ this.get_name() }} = new L.realtime(
+              {% if this.src is string or this.src is mapping -%}
+                  {{ this.src|tojson }},
+              {% else -%}
+                  {{ this.src.js_code }},
+              {% endif -%}
+                  {{ this.get_name() }}_options
+              );
+              {{ this._parent.get_name() }}.addLayer(
+                  {{ this.get_name() }}._container);
+          {% endmacro %}
+    """
+    )
+    expected = normalize(tmpl_for_expected.render(this=rt))
+
+    out = normalize(m._parent.render())
+
+    # We verify that imports
+    assert (
+        '<script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet-realtime/2.2.0/leaflet-realtime.js"></script>'  # noqa
+        in out
+    )  # noqa
+
+    assert expected in out