## Installation

### From the QGIS plugin repository

1. Open QGIS
2. Menu `Plugins` → `Manage and Install Plugins`
3. Search for "Universal Map2web"
4. Click Install

### From GitHub

1. Download the ZIP from GitHub
2. QGIS → `Plugins` → `Install from ZIP`
3. Select the downloaded ZIP file
4. Restart QGIS if prompted

Requires QGIS 3.40 or higher (compatible up to QGIS 4.x). The plugin interface automatically follows the language of your QGIS installation (French / English).

## Usage

### 1. Launch the plugin

Click on the Universal Map2web icon in the QGIS toolbar, or open it from the `Web` menu.

### General tab

- Choose the web library used to render the map (Leaflet)
- Select the basemap: OpenStreetMap, Google Satellite, or a custom tile URL (e.g. `https://{s}.tile.example.com/{z}/{x}/{y}.png`)
- Enable the tools you want embedded in the exported map (see Tools & Options)

### Customization tab

- Set the map title shown in the browser tab and header
- Add an optional logo displayed in the header
- Pick the header color
- Choose one of the four UI themes (see Themes)

### Layers tab

1. Check the layers to export (use "Select all" / "Deselect all" / "Invert" to speed this up)
2. For each layer, configure which attribute fields appear in the popup when a feature is clicked

### Advanced tab

- Simplify geometries — reduces vertex count for faster loading
- Compress JSON data — smaller GeoJSON output files
- Round coordinates — trims decimal precision
- Export as ZIP — packages the whole export in a single archive
- Open automatically in browser — starts a local server and opens the map once export finishes

### Wiki tab

Built-in quick-reference documentation, available in French or English depending on your QGIS language.

### Exporting

1. Once everything is configured, click "OK"
2. Choose the destination folder
3. The map opens automatically in your default browser (if enabled)

## Tools & Options

Each tool below can be enabled or disabled independently in the General tab before export.

Option | Effect on the exported map
--- | ---
Address search | Adds a search bar to locate an address on the map
GPS geolocation | Adds a button to center the map on the visitor's current position
Measure (distance/area) | Adds interactive distance and area measurement tools
Print button | Adds a button that triggers the browser's print dialog for the map
Fullscreen mode | Adds a control to expand the map to fullscreen
Overview (MiniMap) | Displays a small overview map in a corner of the main map
Scale bar | Displays a graphic distance scale (enabled by default)
Cursor position | Displays live latitude/longitude under the mouse pointer
Attribution | Displays the map/library credits (enabled by default)
Advanced filter | Adds the attribute filtering panel — see Advanced Filtering

### Layer management on the exported map

- Show / hide a layer: toggle its checkbox in the legend panel
- Point clustering: enable "Cluster points" per layer (point layers only)
- Legend: colors and categories are generated automatically from your QGIS symbology (Simple, Categorized, Graduated, and Rule-based renderers are all supported)
- Expand / Collapse all: quickly fold or unfold every layer group in the legend

## Themes & Customization

### Light

Clean, bright interface — best for printed screenshots and daytime presentations.

### Dark

Low-glare dark interface, well suited for satellite basemaps and long viewing sessions.

### Professional

Neutral, corporate look for official reports and institutional web maps.

### Colorful

Vibrant accent colors, ideal for public-facing or promotional map dashboards.

Tip: the header color, title, and logo are independent from the theme, so you can mix your organization's branding with any of the four base themes.

## Advanced Filtering

When enabled, a filter panel appears in the exported map's sidebar, letting visitors query features without touching QGIS.

### How to use it

1. Select a layer
2. Select a field
3. Select an operator
4. Type or click a value
5. Click "Apply" — matching features are highlighted on the map

### Available operators

Operator | Meaning
--- | ---
`=` | equal to
`≠` | different from
`⊃` | contains
starts with | text starts with the given value
`>` | greater than
`<` | less than
`≥` | greater than or equal to
`≤` | less than or equal to

Reset: click "Reset" at any time to clear the filter and show all features again.

## Tips and Best Practices

### Keep it light

Limit exports to around 10 active layers for the best browser performance.

### File size

Keep individual layers under roughly 50 MB; enable "Simplify geometries" and "Compress JSON data" for large datasets.

### Coordinate system

Use WGS84 (EPSG:4326) for your project — Leaflet basemaps expect geographic coordinates.

### Preview first

Check symbology and labels in QGIS before exporting — the web map mirrors your current project styling.

### Popups

Only select the fields visitors actually need in the popup configuration — fewer fields means a lighter, cleaner popup.

### Sharing the export

Use "Export as ZIP" to get a single archive you can upload to a web server or send to a colleague.

## Troubleshooting

### The map doesn't open automatically after export

Symptom: export finishes without error, but no browser window appears.
Solutions:

- Make sure "Open automatically in browser" is checked in the Advanced tab
- Check that your firewall or antivirus isn't blocking the local port used to preview the map
- Open `index.html` manually from the export folder in your browser

### The legend or some labels stay in the wrong language

Solutions:

- Make sure QGIS's interface language is set the way you want under `Settings` → `Options` → `General`
- Restart QGIS after changing the language so the plugin reloads its translations

### A layer doesn't appear in the exported map

Solutions:

- Confirm the layer is checked in the Layers tab of the export dialog
- Make sure the layer's visibility is turned on in the QGIS Layers panel
- Vector layers only — raster layers are not exported to Leaflet by this plugin

### Colors or categories in the web map don't match QGIS

Solutions:

- Re-check your renderer type (Simple, Categorized, Graduated, Rule-based) is fully applied in QGIS before exporting
- Refresh the layer's symbology panel in QGIS, then re-export

Good to know: most issues come down to browser/firewall permissions for the local preview server, or a layer's visibility/selection state in QGIS at export time.

## Requirements

Component | Requirement
--- | ---
QGIS | 3.40 or higher (up to 4.x)
Browser | Chrome 90+, Firefox 88+, Edge 90+
Memory | 4 GB RAM minimum
Internet | Required for basemaps and web libraries (Leaflet, plugins)

## Support and Contact

### Email

jeanbaptiste.kibora@tic.gov.bf

### GitHub

github.com/geomatic-web/universal_map2web

### Report a bug

Open an issue

### Phone

+226 64 41 25 14