=== Advanced OSM for Toolset Maps ===
Contributors: umbaumba
Donate link: https://wp-customtypes.com/
Tags: toolset, maps, openstreetmap, satellite view, kml
Requires at least: 6.5
Tested up to: 6.9
Stable tag: 2.0.0
Requires PHP: 7.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Extends Toolset Maps with professional OpenStreetMap features: Satellite view, Custom Clustering, and KML/GPX tracks integration.

== Description ==

**Supercharge Toolset Maps with professional OpenStreetMap features that go beyond the basic core implementation.**

While Toolset Maps provides a foundation for OSM, this plugin enhances the experience with advanced visualization and data tools:

🛰️ **Satellite View** - High-resolution Esri satellite imagery not available in native Toolset.

🔵 **Pro Clustering** - While Toolset now offers basic clustering, AOTM gives you more control. Customize the cluster color to match your brand and set precise zoom thresholds for declustering.

📍 **KML & GPX Support** - Visualize tracks, routes, or shapes. You can now load files in two ways:
1. **Directly via URL:** Use the new `track-url` attribute.
2. **Dynamic Fields:** Use a Toolset File Field slug with `track-field`.

🎨 **Custom Styling** - Apply Grayscale (silver style) effects with precise intensity control.

🛣️ **Layer Management** - Toggle roads and labels independently, allowing for a cleaner map design.

Check [DEMOS](https://wp-customtypes.com/advanced-osm-for-toolset-maps/)

Check author page [wp-customtypes.com](https://wp-customtypes.com/)

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/advanced-osm-for-toolset-maps/`
2. Activate the plugin through WordPress admin
3. Use the [aotm-advanced-osm-map] shortcode to configure the map settings.
4. (Optional) Use [aotm-advanced-osm-marker] inside a View loop or Single Post to display KML/GPX files.

== Frequently Asked Questions ==

= How is this different from native Toolset Maps? =
Toolset provides basic OSM functionality. Our plugin adds the "Pro" layer:
- Satellite imagery with interactive toggle button.
- Customizable cluster markers (change colors and behavior).
- KML/GPX file support for displaying tracks and shapes (via URL or Custom Fields).
- Precise grayscale styling.
- Independent layer controls (roads/labels).

= Does this replace Toolset Maps? =
No, it enhances it. You still need Toolset Maps installed and active.

== Screenshots ==
1. Default OpenStreetMap view with Satellite button
2. Satellite + Roads + Labels overlay
3. Grayscale effect with colored clustered markers
4. GPX and KML track displayed on a Toolset Map via URL.
5. GPX and KML track displayed on a Toolset Map via Custom Fields.

== Changelog ==

= 2.0.0 =
* Added support for KML and GPX tracks via Toolset File Fields.
* Added support for loading tracks directly via URL using the `track-url` attribute.
* New shortcode [aotm-advanced-osm-marker] for dynamic track loading.
* Fixed Marker Clustering: You can now set a custom brand color for clusters.

= 1.2.1 =
* Minor fixes and prefix updates.

== Changelog ==

= 2.0.0 =
* Added support for KML and GPX tracks via Toolset File Fields.
* New shortcode [aotm-advanced-osm-marker] for dynamic track loading.
* Fixed Marker Clustering: You can now set a custom brand color for clusters.

= 1.2.1 =
* Minor fixes

= 1.2 =
* Initial release with complete feature set
* Updated all function prefixes to 'aotm' for better compatibility
* Changed shortcode to [aotm-advanced-osm-map]

== Upgrade Notice ==

= 2.0.0 =
MAJOR UPDATE: This version introduces support for KML and GPX tracks (via Custom Fields or direct URL), custom brand colors for Marker Clusters, and significant performance improvements for map re-initialization.

= 1.2.1 =
* Minor fixes

= 1.2 =
* Initial release - requires Toolset Maps to be installed

== Shortcode Examples ==

**Basic OpenStreetMap**
[aotm-advanced-osm-map map-id="map-1"]
[wpv-map-render map_id="map-1"][/wpv-map-render]

**Satellite View with Layers**
[aotm-advanced-osm-map map-id="map-2" satellite="on" labels="on" roads="on"]
[wpv-map-render map_id="map-2"][/wpv-map-render]

**Professional Styling**
[aotm-advanced-osm-map map-id="map-3" grayscale="0.9" cluster="on" cluster-color="#f05a28"]
[wpv-map-render map_id="map-3"][/wpv-map-render]

**Dynamic Tracks in a View or Single Post via URL **
Inside any Post or Page:
[aotm-advanced-osm-map map-id="map-4" track-field="https://my-domain.com/wp-content/uploads/my-track.gpx,https://my-domain.com/wp-content/uploads/my-shape.kml"]
[wpv-map-render map_id="map-4"][/wpv-map-render]

**Dynamic Tracks in a View or Single Post via Custom field**
Inside your Toolset View loop or Content Template:
[aotm-advanced-osm-map map-id="map-5"]
[wpv-map-render map_id="map-5"][/wpv-map-render]

[aotm-advanced-osm-marker map-id="map-4" track-field="track-file-slug"]

== Feature Comparison ==

**Satellite View**        
Toolset Maps ❌ No
Advanced OSM ✅ 1-click

**Marker Clustering** 
Toolset Maps ⚠️ Basic only
Advanced OSM ✅ Customizable

**Grayscale Effects**
Toolset Maps ❌ No
Advanced OSM ✅ 0-100% control

**Layer Toggles**
Toolset Maps ❌ All or none
Advanced OSM ✅ Roads/Labels separate

**Zoom Control**
Toolset Maps ❌ Basic
Advanced OSM ✅ Precise levels

**KML/GPX Support**
Toolset Maps ❌ No
Advanced OSM ✅ Yes (Shapes & Tracks)

== Full Shortcode Reference ==

= [aotm-advanced-osm-map] =
* map-id: (Required) Must match your Toolset map ID.
* satellite: "on" – Set satellite as default base layer.
* satellite-button: "off" – Hide Satellite toggle button (default on).
* cluster: "on" – Enable custom marker clustering.
* cluster-color: Hex color (e.g., #ff5500) - Change the cluster icon color.
* zoom-cluster: 0-18 - Zoom level where clustering turns off (default 12).
* track-url: Direct URL to a .kml or .gpx file. Supports multiple URLs separated by commas.
* track-field: Slug of the Toolset custom field containing KML/GPX URLs (for global tracks).
* grayscale: 0.1-1 – Grayscale intensity (default 0).
* labels/roads: "on" – Show extra overlays.

= [aotm-advanced-osm-marker] =
* map-id: (Required) Must match your Toolset map ID.
* track-field: (Required) Slug of the Toolset File Field (KML or GPX).