🧩 External Interactive List - GEO Map Hub Plugin

This guide explains how to display custom content outside your SVG map. The External Interactive List lets you link regions to external HTML, showing details like text or images when a region is clicked.

📘 What is External Interactive List?

The External Interactive List is a feature of GEO Map Hub that allows HTML-based region lists to interact with the map. When you hover over a region in the list, the corresponding area on the map is highlighted and on click displays relevant content outside the map.

It connects map behavior with HTML-based UI perfect for dashboards, region-based directories, or side panels.

💡 Use Case

✅ You can use this feature to:

• 🧾 Build a clickable list of regions or states

• 🖱️ Sync click events with the map

• 📦 Show detailed info like images, population, services, etc.

• 🗃️ Filter or navigate maps through external controls

• 🛍️ Create region-wise product or service catalogs

Example: A list of US states next to the map that updates the content pane with flag, name, and brief info when clicked.

📁 Folder Structure

Ensure your project follows this structure:

your-project/
├── gmh-plugin/
│    ├── assets/
│    │    ├── css/
│    │    │    └── style.css
│    │    ├── js/
│    │    │    └── script/
│    │    │    │    ├── geomaphub.js
│    │    │    │    └── lib/
│    │    │    │    │   ├── external-interactive-list-gmh.js  ← Required
│    │    │    │    │   └── interactive-tooltip-gmh.js        ← Required for interactive (tooltips and links.)
│    ├── data/
│    │    ├── us/
│    │    │    ├── map-content.js                      ← Add marker config here
│    │    │    └── us.svg
│ index.html

✅ Configuration Breakdown

🔹 map_config

Only needs the targetClass and name:

export const map_config = [
  {
    "targetClass": "US-WA",  // Unique identifier for region.
    "name": "Washington",  // Display name for the region.
  },
]

🧠 Note: The actual visual and interactive behavior for this region is now handled in external_interactive_list.

🔹 external_interactive_list

/*
 * External Interactive List Configuration
 * This configuration defines interactive settings for regions on the map,
 * including their colors, border styles, and associated content.
*/
export const external_interactive_list = {
  /*
   * Map Background Color Configuration
   * Specifies the background color of the map and its behavior during interactions.
  */
  "color": {
    "default": "#f3faff", // Default background color of the map
    "on_hover": "#005999", // background color on mouse hover
  },

  /*
   * Map Border Styling
   * Defines the border color and width for regions on the map.
  */
  "stroke": {
    "color": "#6B8B9E", // Color of the border
    "width": "0.8px"    // Width of the border
  },

  /*
   * Map Categories
   * Each category corresponds to a region on the map and includes
   * settings for its appearance and interactive behavior.
  */
  "map_category_list": [
    {
      "map_ref_id": "US-WA", // Unique identifier for region.
      "name": "Washington",  // Name displayed for the region

      /*
       * Content Configuration
       * Defines the content displayed when the region is clicked,
       * such as text or images.
      */
      "content": {
        "text": `<img src="assets/images/flags/us/us-wa.svg" style="width: 100%;" />
                <p>Some text</p>
            `,
      },

      /*
       * Region Background Color Configuration
       * Specifies the default, hover, and active colors for the region's background.
      */
      "color": {
        "default": "#afcde3", // Default background color of the region
        "on_hover": "#005999", // Background color when hovered over
        "active": "#005999" // background color on clicked
      },
    },
  ],
};

🔹 color

Controls the background color of all regions in normal and hover states:

🖍️ stroke

Defines the border style of the map regions:

📂 map_category_list

This array defines all interactive regions that sync with the external list:

✅ Used to build an external sidebar/list UI that is visually and functionally tied to regions on the map.

🔹 general_config

/*
 * 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. */
    "marker_id": "US-MARKER-GMH",  /** ID for the marker element. */
    "map_group_id": "US-MAP-GROUP",  /** ID for the group element. */
    "tooltip_id": "tooltip-gmh",  /** ID for the tooltip element. */
    "custom_tooltip_id": "custom-tooltip-gmh",  /** ID for the tooltip element. */

    /*
     * External Interactive List
     * This section defines the IDs for elements that will be used for external
     * interactive content such as lists or external controls.
    */
    "external_interactive_list": {
      "content_id": "content-gmh",  /** ID for the content container. */
      "html_list_id": "html-content-gmh"  /** ID for the HTML content list. */
    },
  },
}

🔹 Base IDs

📋 external_interactive_list IDs

🔄 These allow the external list to dynamically highlight, trigger region interactions, and display content based on clicks or hovers.

⚙️ Script Setup

<!-- External Interactive List -->
<script type="module">
  const currentCountry = "us";

  async function initMap() {
    try {
      const {
        map_config,
        external_interactive_list,
        general_config
      } = await import(`/gmh-plugin/data/${currentCountry}/map-content.js`);
      const {GEOMapHub} = await import('/gmh-plugin/assets/js/script/geomaphub.js');
      const {geoMapHubexternalInteractive} = await import('/gmh-plugin/assets/js/script/lib/external-interactive-list-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,
        externalInteractiveList: external_interactive_list,
        generalConfig: general_config,
      });

      map.registerPlugin(geoMapHubexternalInteractive);
      map.registerPlugin(geoMapHubInteractiveTooltip);

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

  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 – External Interactive List</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>
    <div id="svg-wrapper-gmh"></div>
  </div>

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

  <!-- External Interactive List -->
  <script type="module">
    const currentCountry = "<?= strtolower($country) ?>";

    async function initMap() {
      try {
        // Dynamically import map-specific data
        const {
          map_config,
          external_interactive_list,
          general_config
        } = await import(`/data/${currentCountry}/map-content.js`);
        const {GEOMapHub} = await import('/assets/js/script/geomaphub.js');
        const {geoMapHubexternalInteractive} = await import('/assets/js/script/lib/external-interactive-list-gmh.js');
        const {geoMapHubInteractiveTooltip} = await import('/assets/js/script/lib/interactive-tooltip-gmh.js');

        const map = new GEOMapHub("#svg-wrapper-gmh", {
          svgUrl: `/data/${currentCountry}/${currentCountry}.svg`,
          mapConfig: map_config,
          externalInteractiveList: external_interactive_list,
          generalConfig: general_config,
        });

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

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

    initMap();
  </script>
  <!-- External Interactive List -->
</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

✅ Defined map_config with targetClass

✅ Set external_interactive_list

✅ Assigned content_id and html_list_id

✅ Styled list with color and stroke

✅ Registered geoMapHubexternalInteractive plugin

🎯 Result

You now have an external list of clickable or hoverable regions. When a user clicks or hovers a list item, the corresponding region on the map highlights and displays detailed information in a content pane. It's perfect for turning maps into full interactive dashboards or region directories.