🗺️ Colored Legend - GEO Map Hub Plugin

This guide help you to render interactive, zoomable, and data-driven SVG maps with categorized regions and markers. With support for custom tooltips, click actions, and a colored legend system, this plugin is ideal for building rich geographical visualizations for any regional use case.

❓ What is a Colored Legend?

The Colored Legend is a visual categorization system used to:

• Highlight regions or markers using specific colors.

• Group items under category labels (e.g., "Wines", "Cheese").

• Enable visual filtering and interaction on the map.

• Provide tooltips and content previews.

Each legend category has its own color scheme (default, hover, active, etc.), allowing users to quickly interpret and interact with the map data visually.

✅ Use Cases

• Interactive Country or Regional Maps: Visualize states, provinces, or districts.

• Tourism Maps: Showcase landmarks, attractions, and facilities.

• Sales & Marketing Maps: Highlight sales territories, client zones, or demographics.

• Resource Distribution Maps: Display categorized markers for resources, products, or services.

📁 Folder Structure

Make sure the following files are correctly placed:

your-project/
├── gmh-plugin/
│    ├── assets/
│    │    ├── css/
│    │    │    └── style.css
│    │    ├── js/
│    │    │    └── script/
│    │    │    │    ├── geomaphub.js
│    │    │    │    └── lib/
│    │    │    │    │   ├── colored-legend-gmh.js       ← Required
│    │    │    │    │   ├── advanced-zoom-gmh.js        ← Required
│    │    │    │    │   └── interactive-tooltip-gmh.js  ← Required for interactive (tooltips and links.)
│    ├── data/
│    │    ├── us/
│    │    │    ├── map-content.js
│    │    │    └── us.svg
│ index.html

🛠 Configuration Breakdown

🔷 map-content.js

The map_config array holds region definitions:

/**
 * Map Configuration File
 *
 * This file contains data used to render a map. Each object in the `map_config` array
 * represents a region on the map, defined by a unique identifier (`id`) and other
 * metadata (e.g., name, population, color).
 *
 * Structure:
 * - id: Unique identifier for the region (e.g., "US-WA").
 * - name: Display name for the region (e.g., "Washington").
 * - Additional fields can be added as required to provide more details for each region.
*/
export const map_config = [
  {
    "targetClass": "US-CA",  // Unique identifier for region.
    "name": "California",  // Display name for the region.

    /*
      Configuration for Colored Legend.

      Keys:
        - tooltip (string): Tooltip text displayed when interacting with the defined area.
        - color (object): Styling options for the background color of the interactive area:
          - default (string): Default background color.
          - on_hover (string): Background color when hovered.
    */
    "colored_legend": {
      "tooltip": "Washington",  // Tooltip text displayed when hovering over the interactive area.

      // Color settings for the interactive area.
      "color": {
        "default": "#afcde3", // Default background color.
        "on_hover": "#005999", // Background color when hovered.
      },

      // Optional: URL and target for when clicking on the interactive area.
      "on_click": {
        "url": "https://en.wikipedia.org/wiki/Washington",
        "target": "_blank",
        "cursor": "pointer"
      },
    },
  }
];

🔑 Keys

• targetClass A unique identifier used to match the SVG class for that region (e.g., "US-CA" for California).

• name Human-readable name for the region.

• colored_legend Object that customizes visual behavior and interaction.

Inside colored_legend:

✅ This structure supports interactive maps with clickable, styled areas and tooltips.

🎨 colored_legend

/*
 * Colored Legend Configuration
 * This section defines the settings for colored regions, categories, and markers.
*/
export const colored_legend = {
  "color": {
    "default": "#f3faff",  /** Default color of the region or marker. */
    "on_hover": "#005999"   /** Color when hovered over. */
  },

  "stroke": {
    "color": "#6b8b9e",  /** Border color of the region or marker. */
    "width": "0.8px"     /** Border width of the region or marker. */
  },

  /*
   * Category Types Configuration for filtering the markers
   * Defines categories (e.g., "Wines", "Cheese") and their colors.
  */
  "category_type": [
    {
      "id": "CL-TYPE-01",  /** Unique identifier for the category. */
      "text": "Wines",     /** Text description of the category. */
      "color": {
        "default": "#ec962a",    /** Default color for the category. */
        "active": "#ec962a",     /** Color when the category is active. */
        "in_active": "#005999",  /** Color when the category is inactive. */
        "on_hover": "#005999"    /** Color when the category is hovered over. */
      },
    },
    {
      "id": "CL-TYPE-02",  /** Unique identifier for the second category. */
      "text": "Cheese",    /** Text description of the category. */
      "color": {
        "default": "#81dacb",    /** Default color for the category. */
        "active": "#81dacb",     /** Color when the category is active. */
        "in_active": "#005999",  /** Color when the category is inactive. */
        "on_hover": "#005999"    /** Color when the category is hovered over. */
      },
    }
  ],

  /*
   * Markers Configuration
   * This section defines the markers that will be displayed on the map
   * along with their specific properties, such as shape, size, position, and tooltip content.
  */
  "markers": [
    {
      "category_id": "CL-TYPE-01", /** Reference to the category this marker belongs to. */
      "targetClass": "CL-MARKER-01", /** Shape of the marker (e.g., rounded, cubic). */
      "shape": "rounded", /** Shape of the marker (e.g., rounded, cubic). */
      "tooltip": "Washington", /** Tooltip text displayed on hover for the marker. */
      "content": `
          <img src="/gmh-plugin/assets/images/flags/us/us-wa.svg" style="width: 100%;" />
          <h5 class="mt-2 mb-2">Washington</h5>
          <p>Some Text</p>
      `,

      /*
       * Marker size configuration
       * Defines the size properties such as radius, width, and height of the marker.
      */
      "size": {
        "radius": 7, /** Radius of the marker. */
        "width": 8, /** Width of the marker. */
        "height": 8 /** Height of the marker. */
      },

      "stroke": {
        "color": "white", /** Border color of the marker. */
        "width": "1px" /** Border width of the marker. */
      },

      "position": {
        "x": 120, /** X-position of the marker on the map. */
        "y": 66 /** Y-position of the marker on the map. */
      }
    },
    {
      "category_id": "CL-TYPE-02", /** Reference to the category this marker belongs to. */
      "targetClass": "CL-MARKER-04", /** Unique identifier for the marker. */
      "shape": "rounded", /** Shape of the marker (e.g., rounded, cubic). */
      "tooltip": "Alaska", /** Tooltip text displayed on hover for the marker. */
      "content": `
          <img src="/gmh-plugin/assets/images/flags/us/us-ak.svg" style="width: 100%;" />
          <h5>Alaska</h5>
          <p>Some Text</p>
      `,

      /*
       * Marker size configuration
       * Defines the size properties such as radius, width, and height of the marker.
      */
      "size": {
        "radius": 6,   /** Radius of the marker. */
        "width": 8,    /** Width of the marker. */
        "height": 8    /** Height of the marker. */
      },

      "stroke": {
        "color": "white",  /** Border color of the marker. */
        "width": "1px"     /** Border width of the marker. */
      },

      "position": {
        "x": 110, /** X-position of the marker on the map. */
        "y": 456 /** Y-position of the marker on the map. */
      }
    },
  ]
}

🔷 color

Sets default and hover fill color globally for regions or markers:

🖍️ stroke

Controls border appearance:

🏷️ category_type

Defines legend categories (like filters for markers):

✅ Helps toggle/filter marker sets visually by category (e.g., Wine, Cheese).

📍 markers

Custom icons placed on the map, often representing cities, points of interest, or statistics.

Each marker includes:

✅ Provides rich interactive markers with visuals, hover effects, and click info.

⚙️ general_config

Holds global settings:

/*
 * General Configuration
 * This section contains global settings for the map, including
 * IDs for various elements like markers, lines, and tooltips.
*/
export const general_config = {
  "id": {
    /*
     * SVG and Element IDs
     * These IDs are used to reference specific SVG elements or HTML
     * elements in your configuration. If you want to change any of
     * these IDs, ensure you update them in the corresponding svg.js file.
    */
    "svg_id": "US-MAP-GMH",  /** ID for the main SVG map element. */
    "tooltip_id": "tooltip-gmh",  /** ID for the tooltip element. */
    "custom_tooltip_id": "custom-tooltip-gmh",  /** ID for the tooltip element. */

    /*
     * Colored Legend Configuration
     * This section defines the IDs for elements related to the colored legend
     * that displays color-coded regions or markers on the map.
    */
    "colored_legend": {
      "content_id": "content-gmh",  /** ID for the legend content container. */
      "html_id": "html-content-gmh"  /** ID for the HTML structure of the legend. */
    },
  },

  /*
   * Colored Legend Configuration
   * This section defines the controls for the colored legend's zoom functionality.
  */
  "colored_legend": {
    /*
     * Control IDs for Colored Legend Zoom Options
     * These are the identifiers for the zoom buttons associated with the colored legend.
    */
    "control_id": {
      "reset_zoom": "COLORED-LEGEND-RESET-GMH",    /** Button ID for resetting zoom. */
      "zoom_in": "COLORED-LEGEND-ZOOM-IN-GMH",      /** Button ID for zooming in on the legend. */
      "zoom_out": "COLORED-LEGEND-ZOOM-OUT-GMH"     /** Button ID for zooming out on the legend. */
    }
  },
}

🆔 id

Defines critical element IDs (used in DOM & JS):

🔍 Zoom Controls

Controls for zooming in and out on the legend area:

🔌 Script Block Setup

Include the module script like so:

<script type="module">
  const currentCountry = "us";

  async function initMap() {
    const {map_config, colored_legend, general_config} = await import(`/gmh-plugin/data/${currentCountry}/map-content.js`);
    const {GEOMapHub} = await import('/gmh-plugin/assets/js/script/geomaphub.js');
    const {geoMapHubAdvancedZoom} = await import('/gmh-plugin/assets/js/script/lib/advanced-zoom-gmh.js');
    const {geoMapHubColorLegend} = await import('/gmh-plugin/assets/js/script/lib/colored-legend-gmh.js');
    const {geoMapHubInteractiveTooltip} = await import('/gmh-plugin/assets/js/script/lib/interactive-tooltip-gmh.js');

    const map = new GEOMapHub("#svg-wrapper-gmh", {
      svgUrl: `/gmh-plugin/data/${currentCountry}/${currentCountry}.svg`,
      mapConfig: map_config,
      coloredLegend: colored_legend,
      generalConfig: general_config,
      zoomOptions: {
        zoomControls: true,
        zoomToLocation: { onClick: true, animation: true },
        handleDrag: true,
        wheelZoom: false,
        fingerPinch: false,
        toggleFullScreen: false
      },
    });

    map.registerPlugin(geoMapHubColorLegend);
    map.registerPlugin(geoMapHubAdvancedZoom);
    map.registerPlugin(geoMapHubInteractiveTooltip);
    map.init();
  }

  initMap();
</script>

Here's a working example to display the map

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>GEO Map Hub – Colored Legend</title>
  <link rel="stylesheet" href="/gmh-plugin/assets/css/style.css" />
</head>
<body>
  <div id="tooltip-gmh"></div>
  <div id="custom-tooltip-gmh"></div>

  <div class="svg-container-gmh">
    <div id="html-content-gmh">
      <div class="zoom-element">
        <button class="home-gmh" id="ADVANCED-ZOOM-RESET-GMH">Reset</button>
        <button class="plus-gmh" id="ADVANCED-ZOOM-IN-GMH">+</button>
        <button class="minus-gmh" id="ADVANCED-ZOOM-OUT-GMH">-</button>
      </div>
    </div>

    <div id="svg-wrapper-gmh"></div>
  </div>

  <div id="content-gmh" class="content"></div>

  <!-- Colored Legend -->
  <script type="module">
    const currentCountry = "us";

    async function initMap() {
      try {
        // Dynamically import map-specific data
        const {map_config, colored_legend, general_config} = await import(`/gmh-plugin/data/${currentCountry}/map-content.js`);
        const {GEOMapHub} = await import('/gmh-plugin/assets/js/script/geomaphub.js');
        const {geoMapHubAdvancedZoom} = await import('/gmh-plugin/assets/js/script/lib/advanced-zoom-gmh.js');
        const {geoMapHubColorLegend} = await import('/gmh-plugin/assets/js/script/lib/colored-legend-gmh.js');
        const {geoMapHubInteractiveTooltip} = await import('/gmh-plugin/assets/js/script/lib/interactive-tooltip-gmh.js');

        const map = new GEOMapHub("#svg-wrapper-gmh", {
          svgUrl: `/gmh-plugin/data/${currentCountry}/${currentCountry}.svg`,
          mapConfig: map_config,
          coloredLegend: colored_legend,
          generalConfig: general_config,
          zoomOptions: {
            zoomControls: true,
            zoomToLocation: {
              onClick: true,
              animation: true,
            },
            handleDrag: true,
            wheelZoom: false,
            fingerPinch: false,
            toggleFullScreen: false
          },
        });

        map.registerPlugin(geoMapHubColorLegend);
        map.registerPlugin(geoMapHubAdvancedZoom);
        map.registerPlugin(geoMapHubInteractiveTooltip);

        map.init();
      } catch (error) {
        console.error("Error initializing map:", error);
      }
    }

    initMap();
  </script>
  <!-- Colored Legend -->
</body>
</html>

⚠️ Local CORS Warning

If you're testing with a .html file locally and see this error:

Access to script at 'file:///...' from origin 'null' has been blocked by CORS policy...

It means you're loading the file using the file:// protocol.

✅ How to Fix

Option 1: Use a Local Server (Recommended for HTML)

• Live Server (VS Code Extension)

  Install Live Server, right-click your HTML, and choose “Open with Live Server”.

• Or use any other local server:

  # Python 3
  python -m http.server
  
  # Node.js
  npx http-server
  
  # PHP
  php -S localhost:8080
  

• Or use a local web server (e.g., XAMPP or Laragon)

Option 2: Deploy to a Real Server

You can upload your files to:

• Your cPanel or shared hosting

• A staging VPS or domain

Once the files are accessible via http:// or https://, the plugin works without issues.

✅ Final Checklist

• map_config set with proper targetClass values matching the SVG.

• Each region configured with tooltip, hover color, and optional click URL.

• colored_legend defined with marker positions, shapes, and category types.

• general_config matches SVG and tooltip HTML IDs.

• Script block uses async import with fallback error handling.

• Plugins registered: Tooltip, Zoom, Legend.

🎯 Result

With this setup:

• You get a fully interactive, zoomable map.

• Each region is customizable with tooltips and clickable URLs.

• Markers can display categorized data overlays.

• The user experience is rich, accessible, and highly visual.