Metadata-Version: 2.4
Name: djangocms-mapycz-markers
Version: 3.0.0
Summary: DjangoCMS Mapy.cz Markers
Home-page: https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers.git
Author: Zdeněk Böhm
Author-email: zdenek.bohm@nic.cz
License: GPLv3+
Classifier: Typing :: Typed
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Django CMS :: 4.1
Classifier: Framework :: Django CMS :: 5.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: django-cms<6,>=4.1
Requires-Dist: djangocms-text~=0.9
Provides-Extra: forms
Requires-Dist: djangocms-aldryn-forms~=8.3; extra == "forms"
Requires-Dist: lxml; extra == "forms"
Provides-Extra: quality
Requires-Dist: doc8; extra == "quality"
Requires-Dist: flake8; extra == "quality"
Requires-Dist: isort; extra == "quality"
Requires-Dist: mypy; extra == "quality"
Requires-Dist: pydocstyle; extra == "quality"
Provides-Extra: test
Requires-Dist: djangocms-aldryn-forms~=8.3; extra == "test"
Requires-Dist: lxml; extra == "test"
Provides-Extra: example
Requires-Dist: djangocms-versioning; extra == "example"
Requires-Dist: djangocms-alias; extra == "example"
Requires-Dist: djangocms-frontend>=2.0.0a1; extra == "example"
Requires-Dist: django-filer; extra == "example"
Requires-Dist: djangocms-text; extra == "example"
Requires-Dist: django-fsm<3; extra == "example"
Requires-Dist: djangocms-simple-admin-style; extra == "example"
Requires-Dist: python-environ; extra == "example"
Requires-Dist: djangocms-aldryn-forms~=8.3; extra == "example"
Requires-Dist: lxml; extra == "example"

# DjangoCMS Mapy.cz Markers

The *DjangoCMS Project Mapy.cz Markers* is a plugin for the [DjangoCMS](https://www.django-cms.org/) framework,
which allows you to use maps in this content management system.
The plugin displays a map in which you can place your own markers.
The display is handled by the [Leaflet](https://leafletjs.com/) map library.

In addition, it is possible to display a panorama of the selected location.
Furthermore, when entering a position on the map, you can use the address prompt, which sets the relevant geographical coordinates for the marker.
However, for these two functions, it is necessary to create a [REST API key](https://developer.mapy.com/cs/rest-api/api-klic/).
Instructions can be found on the [Mapy.com REST API](https://developer.mapy.com/cs/rest-api/).

The plugin can be run on python >= `3.10` with DjangoCMS versions `>=4.1,<6` and with Leaflet version `1.9.4` and leaflet.markercluster `1.3.0`.
See [Sample example](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers#sample-example) below.


## Usage

### Plugin "Mapy.cz Markers"

The **Mapy.cz Markers** plugin displays the map according to the set latitude and longitude. You can set the map size, location, and zoom level. You can also disable zooming with the mouse wheel. By default, markers that are close to each other are automatically grouped together. This feature can be disabled in the plugin.

![Plugin Mapy.cz](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/raw/main/screenshots/plugin-mapycz.png)

A cluster of two markers in Brno:

![Plugin s clusterem](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/raw/main/screenshots/map-with-cluster.png)

### Plugin "Marker"

The **Marker** plugin displays a marker on the map. Each marker contains the address of a point on the map and its exact location, given by latitude and longitude. When entering an address, a prompt with a list of known addresses is displayed. When selecting from the list, its latitude and longitude are automatically added to the marker. However, both of these functions are only available with an API key.
It is also possible to set the marker's tooltip and whether it should be permanently displayed for the marker.
It is possible to enter a business card into the marker - the content of a pop-up window that appears when you click on the marker icon.

Example of whispering an address:

![Plugin Marker na Mapy.cz](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/raw/main/screenshots/choose-marker-address.png)

Pop-up window example:

![Marker Popup](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/raw/main/screenshots/marker-popup.png)

### Panorama

The Panorama function is activated after defining the API key. A Panorama link appears at the bottom of the business cards. Links can be disabled in the map plugin, and individually enabled or disabled in individual business cards. Clicking on the link displays a panorama below the map, if available for the location. The panorama element can be styled so that it completely covers the map. Below it is a "Close" link to exit the preview.

![Mapa with panorama](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/raw/main/screenshots/map-with-panorama.png)

### Plugin "Connect address with the map"

The **Connect address with the map** plugin can only be used with an API key. It is intended for two purposes:

The first purpose is a prompt. In the *Address* field, enter the name of the text field where the prompt will display a list of known addresses. As the user begins to type an address, a list of addresses matching the one typed is displayed. By clicking on the list, the address is inserted into the address field.

The second purpose is to link to a map. This sets the insertion of the geographical coordinates of the selected address into the appropriate form fields. It is also possible to define which form fields represent the content of the pop-up visit.

Attention! The plugin must be placed under the **Form** plugin. It only uses the text fields of its *parent* form.

Example of whispering an address:

![Address prompt form](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/raw/main/screenshots/address-whisperer.png)

Example of specifying a link plugin:

![Linking an address to a map](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/raw/main/screenshots/connect-address-with-map.png)


### Command "Add Mark into Mapy.cz"

With this connection to the map, saved user responses can then be inserted into the map as markers. The website administrator selects user responses in the *Submitted forms* list and sets the action *Add Markers into Mapy.cz* in the action list. By clicking the *Go* button, markers are created on the map from the user data.

![Command](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/raw/main/screenshots/run-action-markers-into-map.png)


## Installation

Can only be installed for Python >= `3.10`.

```
pip install djangocms-mapycz-markers
```

If you want to use the form functionality, install:

```
pip install djangocms-mapycz-markers[forms]
```

In `settings.py` enter:

```python
INSTALLED_APPS = [
    ...
    "djangocms_mapycz_markers",
    ...
    "aldryn_forms",  # with form
]

# Mapy.cz - Required for panorama and whisperer. For more go to https://developer.mapy.com/cs/rest-api/
MAPYCZ_MARKERS_API_KEY = "eyJp**********2MjN9"
```

Other settings in `settings.py`:

#### MAPYCZ_ADD_MARKER_TO_MAP

In this constant, you can set the path to a custom function that inserts a marker into the map.
See the sample function [add_marker_into_map](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/blob/main/example/mapsite/plugins/mapycz.py?ref_type=heads#L32) in the example, which inserts an additional sentence into the pop-up window content: "Example of extra custom content. See function add_marker_into_map.".

#### MAPYCZ_FIELD_FORMATTER

This constant can be used to set the path to a custom function that modifies the value the user submitted in the form when writing a tag to the map. This is because the value may contain HTML code. By default, all disallowed tags are removed from the HTML code. See [ALLOWED_TAGS](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/blob/main/djangocms_mapycz_markers/utils.py?ref_type=heads#L47).
The sample then includes the [prepend_field_label](https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/blob/main/example/mapsite/plugins/mapycz.py?ref_type=heads#L20). function for exploration.

```python
# Custom Action of plugin "Mapy.cz Markers":
MAPYCZ_ADD_MARKER_TO_MAP = "mysite.plugins.mapycz.add_marker_into_map"

# Prepend labels of fields defined in MAPYCZ_MARKER_FIELD_LABELS:
MAPYCZ_FIELD_FORMATTER = "mysite.plugins.mapycz.prepend_field_label"

# Display Mapy.cz Markers in the Aldryn forms list.
ALDRYN_FORMS_SUBMISSION_LIST_DISPLAY_FIELD = "djangocms_mapycz_markers.utils_admin.form_submission_field"
ALDRYN_FORMS_SUBMISSION_EXTRA_FIELDS = "djangocms_mapycz_markers.utils_admin.form_extra_data"
```

In `urls.py` add a link to the compiled translations for javascript:

```python
from django.conf.urls.i18n import i18n_patterns
from django.urls import path
from django.views.i18n import JavaScriptCatalog

urlpatterns = i18n_patterns(
    path("jsi18n/", JavaScriptCatalog.as_view(packages=["yoursite", "djangocms_mapycz_markers"]), name="javascript-catalog"),
    ...
)
```

or also like this:

```python
from djangocms_mapycz_markers.urls import urlpatterns as plugin_urlpatterns

urlpatterns += plugin_urlpatterns
```

To enable the map marker feature, enter the following in your `admin.py` file/folder:

```python
from django.contrib.admin import site
from djangocms_mapycz_markers.actions import mapycz_add_marker

site.add_action(mapycz_add_marker)
```


## Sample example

You can try the project on a sample example:

1. Download the archive with the example:
   ```
   wget -O example.tar.gz 'https://gitlab.nic.cz/djangocms-apps/djangocms-mapycz-markers/-/archive/main/djangocms-mapycz-markers-main.tar.gz?path=example'
   ```
2. Unzip the archive to a folder and go to it:
   ```
   tar -xf example.tar.gz
   cd djangocms-mapycz-markers-main-example/example/
   ```
3. Create a virtual environment and activate it:
   ```
   python3 -m venv .venv
   source .venv/bin/activate
   ```
4. Install the project with the example:
   ```
   pip install djangocms-mapycz-markers[example]
   ```
5. Start a test server with your API key:
   ```
   APIKEY=eyJp**********2MjN9 ./manage.py runserver
   ```
   If you start it without a key or with an invalid key, [Openstreet](https://www.openstreetmap.org/) maps will be displayed. Panoramas with the whisperer will not be available.
6. Logging into the website administration at http://localhost:8000/admin/ is the username: `admin` and the password `admin`.

## Author

Zdeněk Böhm zdenek.bohm@nic.cz
CZ.NIC, z. s. p. o.

## License

[GPLv3+](https://www.gnu.org/licenses/gpl-3.0.html)
