Metadata-Version: 2.4
Name: wagtail_maps
Version: 0.4.0
Summary: Create and display maps with points in Wagtail
Project-URL: Repository, https://framagit.org/cliss21/wagtail-maps
Project-URL: Issues, https://framagit.org/cliss21/wagtail-maps/-/issues
Author-email: Cliss XXI <contact@cliss21.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: leaflet,map,wagtail
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Wagtail
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: django>=5.2
Requires-Dist: wagtail>=7.0
Provides-Extra: factories
Requires-Dist: wagtail-factories>=4.0.0; extra == 'factories'
Description-Content-Type: text/markdown

# wagtail-maps

Create and display maps with points in Wagtail.

**Warning!** This project is still early on in its development lifecycle. It is
possible for breaking changes to occur between versions until reaching a stable
1.0. Feedback and pull requests are welcome.

This package extend Wagtail to add a new Map model, which is composed by one or
more points. Each point may have a title, some content and link to an internal
or external URL. Once you have configured your map from the Wagtail admin, you
will be able to display it in a page - e.g. as a StreamField block.

## Requirements

This package requires the following:
- **Wagtail** (7.4 LTS)
- **Django** (5.2 LTS)
- **Python 3** (3.10, 3.11, 3.12, 3.13, 3.14)

## Installation

1. Install using ``pip``:
   ```shell
   pip install wagtail-maps
   ```
2. Add ``wagtail_maps`` to your ``INSTALLED_APPS`` setting:
   ```python
   INSTALLED_APPS = [
       # ...
       'wagtail_maps',
       # ...
   ]
   ```
3. Include the URL of *wagtail-maps* to your ``urls.py`` file:
   ```python
   from wagtail_maps import urls as wagtailmaps_urls

   urlpatterns = [
       # ...
       path('maps/', include(wagtailmaps_urls)),
       # ...
   ]
   ```
4. Run ``python manage.py migrate`` to create the models

## Usage

A StreamField block `wagtail_maps.blocks.MapBlock` can be used to display a
given `Map` object with its points in your page. To render this block in your
frontend, you will have to include the following assets in the templates which
can contain it - or in your base template:

* the JavaScript code that renders the map with [Leaflet] thanks to a
  [Stimulus] controller:
  ```django
  <script src="{% static "wagtail_maps/js/map-block.js" %}"></script>
  ```
* the default Leaflet stylesheet if you don't provide your own:
  ```django
  <link rel="stylesheet" href="{% static "wagtail_maps/vendor/leaflet.css" %}">
  ```

[Leaflet]: https://leafletjs.com/
[Stimulus]: https://stimulus.hotwired.dev/

## Development
### Quick start

To set up a development environment, ensure that Python 3 is installed on your
system. Then:

1. Clone this repository
2. Create a virtual environment and activate it:
   ```shell
   python3 -m venv venv
   source venv/bin/activate
   ```
3. Install this package and its requirements:
   ```shell
   (venv)$ pip install --editable ".[factories]" --group dev
   ```

To run the test app interactively, use ``tox -e interactive``, visit http://127.0.0.1:8020/admin and log in with ``admin`` / ``changeme``.

### Contributing

The tests are written with [pytest] and code coverage is measured with [coverage].
You can use the following commands while developing:
- ``make test``: run the tests and output a quick report of code coverage
- ``make test-wip``: only run the tests marked as 'wip'
- ``make test-all``: run the tests on all supported versions of Django and
  Wagtail with [tox]

The Python code is formatted and linted thanks to [ruff]. You can check the code with ``make lint`` and try to fix the reported issues with ``make format``.

When submitting a pull-request, please ensure that the code is well formatted
and covered, and that all the tests pass.

[pytest]: https://docs.pytest.org/
[coverage]: https://coverage.readthedocs.io/
[tox]: https://tox.wiki/
[ruff]: https://docs.astral.sh/ruff/

## License

This extension is mainly developed by [Cliss XXI](https://www.cliss21.com) and
licensed under the [AGPLv3+](LICENSE). Any contribution is welcome!
