Metadata-Version: 2.4
Name: django-mapengine
Version: 6.0.0
Summary: Map engine for maplibre in django
License-File: LICENSE
Author: Hendrik Huyskens
Author-email: hendrik.huyskens@rl-institut.de
Requires-Python: >=3.9
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Dist: django-appconf (>=1.0.5)
Requires-Dist: django-distill (>=3.1.3)
Requires-Dist: django-environ (>=0.10.0)
Requires-Dist: django-geojson (>=4.2.0)
Requires-Dist: djangorestframework (>=3.14.0)
Requires-Dist: djangorestframework-gis (>=1.2.1)
Requires-Dist: range-key-dict (>=1.1.0)
Project-URL: Homepage, https://github.com/rl-institut/django-mapengine
Project-URL: Issues, https://github.com/rl-institut/django-mapengine/issues
Description-Content-Type: text/markdown

# Django-Mapengine

`django-mapengine` is a Django app to provide library for maplibre in backend.
This includes
- html templates and JS files for maplibre
- creation of maplibre sources and layers including choropleths,
- provision of multi-vector-tiles from django models,
- distilling of map source views
- basic popups

## Requirements

Maplibre must be installed (i.e. via npm) and provided as JS framework

## Quick start

1. Add "django_mapengine" to your INSTALLED_APPS setting like this:
   ```python
   INSTALLED_APPS = [
        "...",
        'django_mapengine',
   ]
   ```
2. Install maplibre-gl and pubsub-js dependencies by:
   ```shell
   npm install maplibre-gl pubsub-js
   ```
   and copy JS and CSS to your static folder.

3. Include URLs from django_mapengine to your project:
   ```python
   urlpatterns = [
       "...",
       path("map/", include("django_mapengine.urls")),
   ]
   ```

4. Configure map engine by setting zoom levels, regions and styles folder in project settings.py.
   You can see all possible settings by looking into `django_mapengine.settings.py`.
   Example settings:

   ```python
   from django_mapengine import setup

   MAP_ENGINE_CENTER_AT_STARTUP = [12.537917858911896, 51.80812518969171]
   MAP_ENGINE_ZOOM_AT_STARTUP = 9
   MAP_ENGINE_MAX_BOUNDS = [[11.280733017118229, 51.22918643452503], [13.616574868700604, 52.35515806663738]]

   MAP_ENGINE_IMAGES = [setup.MapImage("wind", "images/icons/i_wind.png")]

   MAP_ENGINE_API_MVTS = {
       "municipality":
           [
               setup.MVTAPI("municipality", "map", "Municipality"),
               setup.MVTAPI("municipalitylabel", "map", "Municipality", "label_tiles"),
           ],
       "results": [setup.MVTAPI("results", "map", "Municipality")]
   }

   MAP_ENGINE_API_CLUSTERS = [
       setup.ClusterAPI("wind", "map", "WindTurbine"),
       setup.ClusterAPI("pvroof", "map", "PVroof"),
       setup.ClusterAPI("pvground", "map", "PVground"),
       setup.ClusterAPI("hydro", "map", "Hydro"),
       setup.ClusterAPI("biomass", "map", "Biomass"),
       setup.ClusterAPI("combustion", "map", "Combustion"),
   ]

   MAP_ENGINE_STYLES_FOLDER = "digiplan/static/config/"
   MAP_ENGINE_POPUPS = ["results"]
   ```

5. Add middleware to your middleware setup before Whitenoise middleware (or other static server middleware):
   ```python
   MIDDLEWARE = [
       "django.middleware.security.SecurityMiddleware",
       "django_mapengine.middleware.MapEngineMiddleware",
       "whitenoise.middleware.WhiteNoiseMiddleware",
       ...
   ]
   ```

6. Create a plain `TemplateView` in views.py (no mixin needed - map data is built per map by the
   template tag below, at render time):
   ```python
   from django.views.generic import TemplateView


   class MapView(TemplateView):
       """View to show a map generated by django-mapengine."""

       template_name = "map.html"
   ```

7. Add maplibre-gl, pubsub-js and the map itself to your template with the `mapengine_map` tag.
   Each call renders one map's container, setup/source JSON and store; the shared JS library
   files are included automatically, once per page, by the first call:
   ```html
   {% load mapengine_tags %}

   {% block javascript %}
     {{ block.super }}
     {% compress js %}
       <script src="{% static 'vendors/maplibre/js/maplibre-gl.js' %}"></script>
       <script src="{% static 'vendors/pubsub/js/pubsub.js' %}"></script>
     {% endcompress %}
   {% endblock javascript %}

   {% block css %}
     {% compress css %}
       <link href="{% static 'vendors/maplibre/css/maplibre-gl.css' %}" rel='stylesheet'/>
     {% endcompress %}
   {% endblock css %}

   {% block content %}
     {% mapengine_map "default" %}
   {% endblock %}
   ```

   To show more than one map side by side, define `MAP_ENGINE_MAPS` in settings (a dict of
   name -> `setup.MapConfig`, see `django_mapengine/setup.py`) and call the tag once per name,
   e.g. `{% mapengine_map "overview" %}{% mapengine_map "detail" %}`. Without `MAP_ENGINE_MAPS`,
   `{% mapengine_map %}` (or `{% mapengine_map "default" %}`) renders a single map built from the
   flat `MAP_ENGINE_*` settings above.

# User Guides

- [How to define layers](docs/LAYERS.md)
- [How to enable popups](docs/POPUPS.md)
- [How to set up clusters](docs/CLUSTERS.md)

