🔎 External Search & Select - GEO Map Hub Plugin

This guide explains how to enable a searchable dropdown that highlights and displays region-specific content on your SVG map. Users can select a region to trigger tooltips, color changes, and custom content inside a modal.

📘 What is External Search & Select?

External Search & Select is a powerful feature in GEO Map Hub that enables users to search and select regions from a dropdown list and view relevant map content in a modal. This is especially useful for larger maps (e.g., US states, world countries) where users might prefer to find a region by name rather than visually navigating the map.

💡 Use Case

✅ Common real-world use cases:

• 🔍 Searchable country/state/district directory

• 🗺️ Accessibility for visually complex maps

• 💼 Region-wise business listings

• 🏥 Healthcare or service locator by region

• 🧑‍🎓 School/university lists linked to locations

Example: A user selects "Alabama" from the dropdown → the region is highlighted on the map and a modal shows content like history, flag, or services.

📁 Folder Structure

Make sure the following files are correctly placed:

your-project/
├── gmh-plugin/
│    ├── assets/
│    │    ├── css/
│    │    │    └── style.css
│    │    ├── js/
│    │    │    └── lib/
│    │    │    │    ├── jquery.min.js
│    │    │    │    └── select2.min.js
│    │    │    └── script/
│    │    │    │    ├── geomaphub.js
│    │    │    │    └── lib/
│    │    │    │    │   ├── external-search-and-select-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_config

Each region includes an external_search_select key with interactive settings:

/**
 * 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-WA",  // Unique identifier for region.
    "name": "Washington",  // Display name for the region.

    /*
     * External Search and Select Configuration
     * This object defines the interactive behavior and styling for a region on the map
     * that supports external search functionality with clickable content.
    */
    "external_search_select": {
      "tooltip": "Washington", // Tooltip text displayed when hovering over the region

      /*
       * Content Display on Click
       * The HTML content to be displayed when the region is clicked.
      */
      "content": `<p><b>Washington</b> most commonly refers to..</p>`, // Content Display On Click

      /*
       * Color Configuration
       * Defines the region's background color in various states.
      */
      "color": {
        "default": "#afcde3",   // Default background color
        "on_hover": "#005999", // Background color when hovered
        "active": "#005999"    // Background color when active (clicked)
      }
    },
  },
];

✅ This section ties each region to dropdown functionality and modal display behavior.

🔹 general_config

The external_search_select section contains modal configuration, color, stroke, and element IDs:

/*
 * 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. */
    "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. */
    "modal_id": "MODAL-GMH",  /** ID for the modal window element. */
  },

  /*
   * External Search Select Configuration
   * This section defines the configuration for the external search select box,
   * including modal HTML structure, colors, and stroke properties.
  */
  "external_search_select": {
    /*
     * Select Box Configuration
     * These IDs are used to reference the select box and its content.
    */
    "select_box_id": "html-content-gmh", /** ID for the select box container. */

    "select_id": "external-search-select-gmh", /** ID for the select element itself. */

    /*
     * Modal HTML Structure
     * This defines the HTML structure for the modal that will be displayed
     * when interacting with the select box. The modal contains a header,
     * body, and a close button.
    */
    "modal_html": `
      <div class="modal" id="MODAL-GMH" tabindex="-1" role="dialog">
        <div class="modal-dialog" role="document">
          <div class="modal-content">
            <div class="modal-header">
              <h5 class="modal-title"></h5>

              <button type="button" class="close close-gmh" data-dismiss="modal" aria-label="Close">
                <span aria-hidden="true">&times;</span>
              </button>
            </div>

            <div class="modal-body"></div>
          </div>
        </div>
      </div>
    `,

    /*
     * Modal ID
     * The ID used to reference the modal element. This ID should be unique
     * to avoid conflicts with other modals on the page.
    */
    "modal_id": "MODAL-GMH", /** ID for the modal element. */

    /*
     * Color Settings
     * These define the default and hover colors for the regions.
    */
    "color": {
      "default": "#f3faff",  /** Default background color. */
      "on_hover": "#005999"   /** Color when hovered over. */
    },

    /*
     * Stroke Settings
     * These define the border (stroke) properties for the select box or modal.
    */
    "stroke": {
      "color": "#6B8B9E", /** Border color for the select box or modal. */
      "width": "0.8px" /** Border width for the select box or modal. */
    },
  },
}

🔹 id Section

🔹 external_search_select Section

⚙️ Script Setup

Make sure you've included jQuery and Select2:

<script src="/gmh-plugin/assets/js/lib/jquery.min.js"></script>
<script src="/gmh-plugin/assets/js/lib/select2.min.js"></script>

Then initialize:

<!-- External Search and Select -->
<script type="module">
  const currentCountry = "us";

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

      map.registerPlugin(geoMapHubExternalSearchSelect);
      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 Search & Select</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="svg-wrapper-gmh"></div>
  </div>

  <script src="/gmh-plugin/assets/js/lib/jquery.min.js"></script>
  <script src="/gmh-plugin/assets/js/lib/select2.min.js"></script>

  <!-- External Search and Select -->
  <script type="module">
    const currentCountry = "us";

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

          map.registerPlugin(geoMapHubExternalSearchSelect);
          map.registerPlugin(geoMapHubInteractiveTooltip);

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

      initMap();
    </script>
    <!-- External Search and Select -->
</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

✅ Region defined in map_config with external_search_select

✅ Modal HTML included in general_config

✅ IDs correctly mapped (select, modal, content)

✅ Select2 and jQuery libraries loaded

✅ Registered geoMapHubExternalSearchSelect plugin

🎯 Result

Users can now search and select regions from a dropdown, triggering:

• 🗺️ Highlighted region on the map

• 💬 Modal popup with dynamic HTML content

• 🎯 Fully styled interface with tooltip and hover effects

This enhances usability, especially for large datasets, and creates a clean, interactive experience for non-visual users or mobile layouts.