Add configurable popups on markers (#339)

PartyNell · submarcos · web-flow · commit bc97e15a9628 · 2025-11-13T17:20:12.000+01:00
* fix tests

* create a popup with configurable arguments for markers

* use HTML template for popup API

* add tests

* add documentation about popups

* add changelog entry

* fix quality

* change popup's title with str(obj)

* change traduction

* improve text formatting in popup content api

* adapt tests

* adapt documentation

* add parameter to display popup or not

* add changelog entry

* change LABEL_PER_MODEL setting name

* Update mapentity/templates/mapentity/mapentity_popup_content.html

Co-authored-by: Jean-Etienne Castagnede &lt;j.e.castagnede@gmail.com&gt;

* remove spaces in the popup

* fix tests

* add get_popup_url in the model

* fix quality

* apply suggestions

* modify magin and padding of popup

* add traduction of field name for boolean fields in popup

---------

Co-authored-by: Jean-Etienne Castagnede &lt;j.e.castagnede@gmail.com&gt;
diff --git a/CHANGES.md b/CHANGES.md
@@ -4,12 +4,17 @@ CHANGELOG
 8.14.5+dev (XXXX-XX-XX)
 -----------------------
 
+**Improvements**
+
+- Add popup on marker with configurable information
+
 **Bug fixes**
 
 - Fix filter context restoration
 - Fix layer restoration in screenshot
 
 
+
 8.14.5     (2025-10-30)
 -----------------------
 
diff --git a/docs/customization.rst b/docs/customization.rst
@@ -197,6 +197,38 @@ The second way overrides these templates for all your models.
     you need to create a sub-directory named ``mapentity`` in ``main/templates``.
     Then you can create a file named ``override_detail_pdf.html``(or ``.css``) and it will be used for all your models if a specific template is not provided.
 
+Popups
+------
+
+MapEntity displays a popup when clicking on a map object.
+By default, it shows the object's name and a button linking to its detail page.
+
+Configure popup fields for each model using the ``POPUP_CONTENT`` setting:
+
+.. code-block:: python
+
+    POPUP_CONTENT = {
+        "museum": ["name", "city", "public"],
+    }
+
+The key is the model name in lowercase (e.g., ``"museum"``), and the value is a list of field names to display.
+The popup title shows the object's string representation (using `__str__()`), with the configured fields displayed below.
+
+If there is a display function for a field in the model then it will be used in priority.
+
+.. code-block:: python
+
+    @property
+    def public_display(self):
+        return "Public" if self.public else "Not public"
+
+If no display function exists, the field’s string representation is used by default.
+
+Non-existent fields can be used if a display function exist.
+
+If a model isn't configured in ``POPUP_CONTENT``, the object's string representation is used as the title.
+If a specified field doesn't exist on the model, it won't be displayed. The detail page button is always shown.
+If the option ``displayPopup`` is setup to false, then the popup will not appear when clicking on the feature.
 
 Settings
 -----------
@@ -256,4 +288,4 @@ A help message will be added, and color of TinyMCE status bar and border will be
     MAPENTITY_CONFIG['MAX_CHARACTERS_BY_FIELD'] = { 
         "tourism_touristicevent": [{'field': 'description_teaser_fr', 'value': 50}, {'field': 'accessibility_fr', 'value': 25}],
         "trekking_trek": [{'field': 'description_teaser_fr', 'value': 150}],
-    }
+    }
diff --git a/mapentity/locale/en/LC_MESSAGES/djangojs.po b/mapentity/locale/en/LC_MESSAGES/djangojs.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-09-02 15:19+0000\n"
+"POT-Creation-Date: 2025-10-24 13:31+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -18,5 +18,8 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "Plural-Forms: nplurals=2; plural=(n != 1);\n"
 
+msgid "Data unreachable"
+msgstr ""
+
 msgid "Locate me"
 msgstr ""
diff --git a/mapentity/locale/fr/LC_MESSAGES/djangojs.po b/mapentity/locale/fr/LC_MESSAGES/djangojs.po
@@ -18,5 +18,8 @@ msgstr ""
 "Plural-Forms: nplurals=2; plural=n > 1;\n"
 "X-Generator: Weblate 5.13.3\n"
 
+msgid "Data unreachable"
+msgstr "Données inaccessibles"
+
 msgid "Locate me"
 msgstr "Localisez-moi"
diff --git a/mapentity/models.py b/mapentity/models.py
@@ -282,6 +282,12 @@ def get_generic_detail_url(cls):
     def get_detail_url(self):
         return reverse(self._entity.url_name(ENTITY_DETAIL), args=[str(self.pk)])
 
+    def get_popup_url(self):
+        return reverse(
+            f"{self._meta.app_label.lower()}:{self._meta.model_name.lower()}-drf-popup-content",
+            kwargs={"pk": self.pk},
+        )
+
     @property
     def map_image_url(self):
         return self.get_map_image_url()
diff --git a/mapentity/serializers/__init__.py b/mapentity/serializers/__init__.py
@@ -5,12 +5,13 @@
     MapentityGeojsonModelSerializer,
 )
 from .gpx import GPXSerializer
-from .helpers import json_django_dumps, plain_text, smart_plain_text
+from .helpers import field_as_string, json_django_dumps, plain_text, smart_plain_text
 from .shapefile import ZipShapeSerializer
 
 __all__ = [
     "plain_text",
     "smart_plain_text",
+    "field_as_string",
     "CSVSerializer",
     "GPXSerializer",
     "MapentityDatatableSerializer",
diff --git a/mapentity/serializers/helpers.py b/mapentity/serializers/helpers.py
@@ -27,6 +27,9 @@ def field_as_string(obj, field, ascii=False):
             or isinstance(value, Decimal)
         ):
             value = number_format(value)
+        if hasattr(value, "all"):
+            # convert ManyRelatedManager to QuerySet
+            value = value.all()
         if isinstance(value, list) or isinstance(value, QuerySet):
             value = ", ".join([str(val) for val in value])
     return smart_plain_text(value, ascii)
diff --git a/mapentity/static/mapentity/leaflet-objectslayer.js b/mapentity/static/mapentity/leaflet-objectslayer.js
@@ -3,6 +3,7 @@ L.ObjectsLayer = L.GeoJSON.extend({
         indexing: true,
         highlight: true,
         objectUrl: null,
+        displayPopup: true,
         styles: {
             'default': {'color': 'blue', 'weight': 2, 'opacity': 0.8},
             highlight: {'color': 'red', 'weight': 5, 'opacity': 1},
@@ -69,13 +70,25 @@ L.ObjectsLayer = L.GeoJSON.extend({
             }
         }, this));
 
-
-        // Optionnaly make them clickable
-        if (this.options.objectUrl) {
-            this.on('click', function(e) {
-                window.location = this.options.objectUrl(e.layer.properties, e.layer);
-            }, this);
-        }
+        this.on('click', async function (e) {
+            if(this.options.displayPopup){
+                var popup_content;
+                try{
+                    popup_content =  await this.getPopupContent(e.layer);
+                } catch (error) {
+                    popup_content = gettext('Data unreachable');
+                }
+                if (e.target._popup){
+                    // update popup content if it has been already bind
+                    var popup = e.target._popup;
+                    popup.setContent(popup_content);
+                    popup.update();
+                } else {
+                    // bind a new popup
+                    this.bindPopup(popup_content).openPopup(e.latlng);
+                }
+            }
+        }, this);
 
         var dataurl = null;
         if (typeof(geojson) == 'string') {
@@ -220,8 +233,26 @@ L.ObjectsLayer = L.GeoJSON.extend({
             layer._defaultStyle = this.options.styles['default'];
             layer.setStyle(layer._defaultStyle);
         }
-    }
-});
+    },
 
+    getPopupContent: async function (layer){
+        const popup_url = window.SETTINGS.urls.popup.replace(new RegExp('modelname', 'g'), this.options.modelname)
+                                          .replace('0', layer.properties.id);
+
+        // fetch data
+        var response = await window.fetch(popup_url);
+        if (!response.ok){
+            throw new Error(`HTTP error! Status: ${response.status}`);
+        } else {
+            // parse data
+            try {
+                return response.json();
+            } catch (error) {
+                throw new Error('Cannot parse data');
+            }
+        }
+    },
+
+});
 
 L.ObjectsLayer.include(L.LayerIndexMixin);
diff --git a/mapentity/templates/mapentity/mapentity_popup_content.html b/mapentity/templates/mapentity/mapentity_popup_content.html
@@ -0,0 +1,9 @@
+<div class="d-flex flex-column justify-content-center">
+    <p class="text-center m-0 p-1"><strong>{{ title }}</strong></p>
+    {% if attributes %}
+        <p class="m-0 p-1">
+            {% for field in attributes %}{{ field|truncatechars:100 }}<br>{% endfor %}
+        </p>
+    {% endif %}
+    <button id="detail-btn" class="btn btn-sm btn-info mt-2" onclick="window.location.href='{{ detail_url }}'">{{ button_label }}</button>
+</div>
diff --git a/mapentity/tests/__init__.py b/mapentity/tests/__init__.py
@@ -57,6 +57,9 @@ def get_expected_geojson_attrs(self):
     def get_expected_datatables_attrs(self):
         return {}
 
+    def get_expected_popup_content(self):
+        return ""
+
     def setUp(self):
         if self.user:
             self.client.force_login(user=self.user)
@@ -444,6 +447,17 @@ def test_api_geojson_list_for_model(self):
             },
         )
 
+    def test_api_popup_content(self):
+        if self.model is None:
+            return  # Abstract test should not run
+
+        self.obj = self.modelfactory.create()
+        popup_url = self.obj.get_popup_url()
+        response = self.client.get(popup_url)
+        self.assertEqual(response.status_code, 200, f"{popup_url} not found")
+        content_json = response.json()
+        self.assertEqual(content_json, self.get_expected_popup_content())
+
 
 class MapEntityLiveTest(LiveServerTestCase):
     model = None
diff --git a/mapentity/views/api.py b/mapentity/views/api.py
@@ -1,6 +1,9 @@
 import logging
 
+from django.conf import settings
 from django.contrib.gis.db.models.functions import Transform
+from django.template import loader
+from django.utils.translation import gettext_lazy as _
 from django_filters.rest_framework import DjangoFilterBackend
 from rest_framework import renderers, viewsets
 from rest_framework.decorators import action
@@ -89,9 +92,46 @@ def filter_infos(self, request, *args, **kwargs):
             {
                 "pk_list": qs.values_list("pk", flat=True),
                 "count": self.get_filter_count_infos(qs),
+                "attributes": [],
             }
         )
 
+    @action(
+        detail=True,
+        methods=["get"],
+        url_path="popup-content",
+        renderer_classes=[renderers.JSONRenderer],
+    )
+    def popup_content(self, request, *args, **kwargs):
+        obj = self.get_object()
+        model_name = self.model.__name__.lower()
+        label_config = getattr(settings, "POPUP_CONTENT", {})
+        fields = label_config.get(model_name, []).copy()
+
+        context = {
+            "button_label": _("Detail sheet"),
+            "detail_url": obj.get_detail_url(),
+            "attributes": [],
+            "title": str(obj),
+        }
+
+        for field_name in fields:
+            try:
+                value = mapentity_serializers.field_as_string(obj, field_name)
+            except AttributeError:
+                # ignore fields that are not available without raising an error
+                value = None
+
+            # add field name for boolean field for readability
+            if value in [_("yes"), _("no")]:
+                value = f"{obj._meta.get_field(field_name).verbose_name}: {value}"
+
+            if value:
+                context["attributes"].append(value)
+
+        template = loader.get_template("mapentity/mapentity_popup_content.html")
+        return Response(template.render(context))
+
     @view_cache_latest()
     @view_cache_response_content()
     def list(self, request, *args, **kwargs):
diff --git a/mapentity/views/base.py b/mapentity/views/base.py
@@ -114,6 +114,7 @@ def __str__(self):
         dictsettings["urls"]["static"] = settings.STATIC_URL
         dictsettings["urls"]["layer"] = options.model.get_layer_url()
         dictsettings["urls"]["detail"] = f"{root_url}modelname/0/"
+        dictsettings["urls"]["popup"] = "/api/modelname/drf/modelnames/0/popup-content"
         dictsettings["urls"]["format_list"] = (
             f"{root_url}{options._url_path(mapentity_models.ENTITY_FORMAT_LIST)[1:-1]}"
         )
diff --git a/test_project/settings.py b/test_project/settings.py
@@ -211,3 +211,7 @@
 
 if "test" in sys.argv:
     MEDIA_ROOT = TemporaryDirectory().name
+
+POPUP_CONTENT = {
+    "dummymodel": ["short_description", "public", "tags", "name", "test"],
+}
diff --git a/test_project/test_app/models.py b/test_project/test_app/models.py
@@ -89,6 +89,7 @@ def __str__(self):
     def is_public(self):
         return self.public
 
+    @property
     def name_display(self):
         return f'<a href="{self.get_detail_url()}">{self.name or self.id}</a>'
 
diff --git a/test_project/test_app/tests/factories.py b/test_project/test_app/tests/factories.py
@@ -23,6 +23,7 @@ class Meta:
 
 class DummyModelFactory(factory.django.DjangoModelFactory):
     name = "a dummy model"
+    short_description = "a dummy model with a dummy name, a dummy geom, dummy tags, dummy makinins. It is the perfect object to make tests"
 
     @factory.lazy_attribute
     def geom(self):
diff --git a/test_project/test_app/tests/test_views.py b/test_project/test_app/tests/test_views.py
@@ -66,10 +66,21 @@ def get_expected_datatables_attrs(self):
             "name_fr": "",
             "name_zh_hant": "",
             "public": '<i class="bi bi-x-circle text-danger"></i>',
-            "short_description": "",
+            "short_description": "a dummy model with a dummy name, a dummy geom, dummy tags, dummy makinins. It is the perfect object to make tests",
             "tags": [self.obj.tags.first().pk],
         }
 
+    def get_expected_popup_content(self):
+        return (
+            f'<div class="d-flex flex-column justify-content-center">\n'
+            f'    <p class="text-center m-0 p-1"><strong>a dummy model (1)</strong></p>\n    \n'
+            f'        <p class="m-0 p-1">\n'
+            f"            a dummy model with a dummy name, a dummy geom, dummy tags, dummy makinins. It is the perfect object…<br>public: no<br>{self.obj.tags.first().label}<br>a dummy model<br>\n"
+            f"        </p>\n    \n"
+            f'    <button id="detail-btn" class="btn btn-sm btn-info mt-2" onclick="window.location.href=\'/dummymodel/{self.model.objects.first().pk}/\'">Detail sheet</button>\n'
+            f"</div>"
+        )
+
     def get_good_data(self):
         return {"geom": '{"type": "Point", "coordinates":[0, 0]}'}
 
@@ -293,6 +304,7 @@ def test_js_settings_urls(self):
                 "layer": "/api/modelname/drf/modelnames.geojson",
                 "screenshot": "/map_screenshot/",
                 "detail": "/modelname/0/",
+                "popup": "/api/modelname/drf/modelnames/0/popup-content",
                 "format_list": "/modelname/list/export/",
                 "static": "/static/",
                 "root": "/",
@@ -640,6 +652,9 @@ def test_no_basic_format_fail(self):
     def test_no_html_in_csv(self):
         pass
 
+    def test_api_popup_content(self):
+        pass
+
 
 class LogViewMapentityTestlLiveTest(MapEntityLiveTest):
     userfactory = SuperUserFactory
