Add Evented base class (#1959)

* Add EventHandler to layer object

In combination with JsCode this makes it easier for users to
add `on` method calls for event handling without extending
Folium itself.

The functionality was inspired by PR #1866 by @yschopfer19.
The PR was not accepted yet, because of concerns with code
duplication. In the approach taken in the current PR, #1866 would
not be necessary anymore, as the requested changes could be added
completely in client code space.

* Make realtime inherit from Layer

* Changes after review comments by conengmo

* Updates after review comments

* Add extra docstring line

* Add Evented class

In Leaflet Evented is the parent class of both `L.Map` and `L.Layer`.
It adds the `on` method which can be used to add event handlers
to a leaflet object.

* Update folium/map.py

Co-authored-by: Frank Anema <33519926+Conengmo@users.noreply.github.com>

* Update folium/map.py

Co-authored-by: Frank Anema <33519926+Conengmo@users.noreply.github.com>

* As requested in review comment

---------

Co-authored-by: Frank Anema <33519926+Conengmo@users.noreply.github.com>

docs/reference.rst

@@ -35,6 +35,7 @@ Utilities
 ---------------------
 
 .. autoclass:: folium.utilities.JsCode
+.. autoclass:: folium.elements.EventHandler
 
 
 Plugins

folium/elements.py

@@ -3,6 +3,8 @@
 from branca.element import CssLink, Element, Figure, JavascriptLink, MacroElement
 from jinja2 import Template
 
+from folium.utilities import JsCode
+
 
 class JSCSSMixin(Element):
  """Render links to external Javascript and CSS resources."""
@@ -46,6 +48,80 @@ def _add_link(self, name: str, url: str, default_list: List[Tuple[str, str]]):
  default_list.append((name, url))
 
 
+class EventHandler(MacroElement):
+ '''
+ Add javascript event handlers.
+
+ Examples
+ --------
+ >>> import folium
+ >>> from folium.utilities import JsCode
+ >>>
+ >>> m = folium.Map()
+ >>>
+ >>> geo_json_data = {
+ ... "type": "FeatureCollection",
+ ... "features": [
+ ... {
+ ... "type": "Feature",
+ ... "geometry": {
+ ... "type": "Polygon",
+ ... "coordinates": [
+ ... [
+ ... [100.0, 0.0],
+ ... [101.0, 0.0],
+ ... [101.0, 1.0],
+ ... [100.0, 1.0],
+ ... [100.0, 0.0],
+ ... ]
+ ... ],
+ ... },
+ ... "properties": {"prop1": {"title": "Somewhere on Sumatra"}},
+ ... }
+ ... ],
+ ... }
+ >>>
+ >>> g = folium.GeoJson(geo_json_data).add_to(m)
+ >>>
+ >>> highlight = JsCode(
+ ... """
+ ... function highlight(e) {
+ ... e.target.original_color = e.layer.options.color;
+ ... e.target.setStyle({ color: "green" });
+ ... }
+ ... """
+ ... )
+ >>>
+ >>> reset = JsCode(
+ ... """
+ ... function reset(e) {
+ ... e.target.setStyle({ color: e.target.original_color });
+ ... }
+ ... """
+ ... )
+ >>>
+ >>> g.add_child(EventHandler("mouseover", highlight))
+ >>> g.add_child(EventHandler("mouseout", reset))
+ '''
+
+ _template = Template(
+ """
+ {% macro script(this, kwargs) %}
+ {{ this._parent.get_name()}}.on(
+ {{ this.event|tojson}},
+ {{ this.handler.js_code }}
+ );
+ {% endmacro %}
+ """
+ )
+
+ def __init__(self, event: str, handler: JsCode):
+ super().__init__()
+ self._name = "EventHandler"
+ self.event = event
+ self.handler = handler
+
+
 class ElementAddToElement(MacroElement):
  """Abstract class to add an element to another element."""
 

folium/folium.py

@@ -7,11 +7,11 @@
 import webbrowser
 from typing import Any, List, Optional, Sequence, Union
 
-from branca.element import Element, Figure, MacroElement
+from branca.element import Element, Figure
 from jinja2 import Template
 
 from folium.elements import JSCSSMixin
-from folium.map import FitBounds, Layer
+from folium.map import Evented, FitBounds, Layer
 from folium.raster_layers import TileLayer
 from folium.utilities import (
  TypeBounds,
@@ -79,7 +79,7 @@ def __init__(self, no_touch=False, disable_3d=False):
  self.disable_3d = disable_3d
 
 
-class Map(JSCSSMixin, MacroElement):
+class Map(JSCSSMixin, Evented):
  """Create a Map with Folium and Leaflet.js
 
  Generate a base map of given width and height with either default

folium/map.py

@@ -10,8 +10,9 @@
 from branca.element import Element, Figure, Html, MacroElement
 from jinja2 import Template
 
-from folium.elements import ElementAddToElement
+from folium.elements import ElementAddToElement, EventHandler
 from folium.utilities import (
+ JsCode,
  TypeBounds,
  TypeJsonValue,
  camelize,
@@ -21,7 +22,23 @@
 )
 
 
-class Layer(MacroElement):
+class Evented(MacroElement):
+ """The base class for Layer and Map
+
+ Adds the `on` method for event handling capabilities.
+
+ See https://leafletjs.com/reference.html#evented for
+ more in depth documentation. Please note that we have
+ only added the `on(<Object> eventMap)` variant of this
+ method using python keyword arguments.
+ """
+
+ def on(self, **event_map: JsCode):
+ for event_type, handler in event_map.items():
+ self.add_child(EventHandler(event_type, handler))
+
+
+class Layer(Evented):
  """An abstract class for everything that is a Layer on the map.
  It will be used to define whether an object will be included in
  LayerControls.

tests/test_features.py

@@ -13,6 +13,8 @@
 
 import folium
 from folium import Choropleth, ClickForMarker, GeoJson, Map, Popup
+from folium.elements import EventHandler
+from folium.utilities import JsCode
 
 
 @pytest.fixture
@@ -283,6 +285,23 @@ def test_geojson_empty_features_with_styling():
  m.get_root().render()
 
 
+def test_geojson_event_handler():
+ """Test that event handlers are properly generated"""
+ m = Map()
+ data = {"type": "FeatureCollection", "features": []}
+ geojson = GeoJson(data, style_function=lambda x: {}).add_to(m)
+ fn = JsCode(
+ """
+ function f(e) {
+ console.log("only for testing")
+ }
+ """
+ )
+ geojson.add_child(EventHandler("mouseover", fn))
+ rendered = m.get_root().render()
+ assert fn.js_code in rendered
+
+
 def test_geometry_collection_get_bounds():
  """Assert #1599 is fixed"""
  geojson_data = {