README

Create and manage simple interactive maps with markers for Contao CMS. Maps can be embedded via content elements or front end modules. Based on OpenStreetMap (OSM) tile data, optional Mapbox layer API, and Leaflet JavaScript library.

Requirements

PHP ^8.3
Contao ^5.3

Installation

composer require srhinow/simple-map-bundle

After installation run php bin/console contao:migrate to set up the database tables.

Architecture

Database tables

Table	Purpose
`tl_simple_map`	Map definition — title, address, center coordinates, zoom level, optional Mapbox config
`tl_simple_map_pin`	Markers (pins) attached to a map — each has its own address, coordinates, popup text, and category
`tl_simple_map_category`	Optional categories for grouping markers in category-list views

Back end module

Located under OSM Maps in the Contao back end.

Maps (tl_simple_map) — create a map, enter the center address, and set the zoom level. The bundle resolves coordinates automatically via OpenStreetMap Nominatim.
Categories (tl_simple_map_category) — optional; assign categories to markers for filtered display.

Within a map record, individual markers (tl_simple_map_pin) are managed as child records.

Map settings

Field	Description
`setNewGeo`	Resolve center lat/lon from the address fields via OSM Nominatim
`setNewPin`	Auto-create a marker from the map's own address data
`mapLat` / `mapLon`	Map center coordinates (stored as `DECIMAL(10,8)`)
`mapZoom`	Initial zoom level (1–18)
`do_mapbox`	Enable Mapbox tile layer instead of OSM
`mapboxApiKey`	Mapbox API key (required if Mapbox is enabled)
`mapboxStyle`	Classic Mapbox style identifier (e.g. `mapbox/streets-v12`)
`leafletCustomScript`	Optional Leaflet JS commands (without `<script>` tags)

Marker settings

Field	Description
`setNewGeo`	Re-resolve coordinates from the marker's address
`mapLat` / `mapLon`	Marker position
`popupText`	HTML text shown in the Leaflet popup
`popupOpen`	Open the popup immediately on map load
`category`	Optional category assignment
`published`	Controls front end visibility

CSV import

Markers can be bulk-imported via CSV file. Located in the back end under the marker list's CSV import operation.

The import form allows:

Selecting an uploaded CSV file
Mapping CSV columns to marker fields
Running a dry-run test before importing
Optionally triggering geocoding for all imported markers

Upload directory: files/csv_imports/ (created automatically on first access).

Content elements and front end modules

Type	Description
`simple_map_view`	Renders the Leaflet map with all published markers
`simple_map_category_list`	Lists marker data grouped by category (compatible with accordion JS)

Geo resolution

The bundle uses the Nominatim OpenStreetMap API to resolve addresses to coordinates. Geocoding is triggered when:

The setNewGeo checkbox is saved in a map or marker record.
A new marker is created and has no coordinates yet.
The CSV import runs with geocoding enabled.

Running tests

Tests must be run from the main Contao installation:

vendor/bin/phpunit -c vendor/srhinow/simple-map-bundle/phpunit.xml.dist

Or from the bundle root (if vendor/ is present):

vendor/bin/phpunit

srhinow/simple-map-bundle

包简介

关键字：

README 文档