🔗 Live Filter - GEO Map Hub Plugin

This guide explains how to group and toggle markers on your SVG map using live filters. Categories like "Blue Markers" or "Orange Markers" let users quickly filter locations with distinct styles, tooltips, and click actions.

🌐 What is Live Filter?

The Live Filter Plugin enables interactive filtering of markers on the map based on predefined categories. When users toggle filter buttons, only markers associated with the selected category are shown, enhancing clarity and focus on relevant data.

✅ Use Cases

• 🎯 Toggle visibility of different types of points (e.g., Airports, Schools, Factories)

• 🌈 Categorize markers by color, type, or intensity

• 👤 Allow users to interactively explore data points by category

• 📊 Build dynamic dashboards using visual filters

📁 Folder Structure

Make sure the following files are correctly placed:

your-project/
├── gmh-plugin/
│    ├── assets/
│    │    ├── css/
│    │    │    └── style.css
│    │    ├── js/
│    │    │    └── script/
│    │    │    │    ├── geomaphub.js
│    │    │    │    └── lib/
│    │    │    │    │   ├── live-filter-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

export const map_config = [
  {
    "targetClass": "US-WA",  // Unique identifier for region.
    "name": "Washington",  // Display name for the region.
  },
  {
    "targetClass": "US-AL",  // Unique identifier for region.
    "name": "Alabama",  // Display name for the region.
  },
  {
    "targetClass": "US-AK",  // Unique identifier for region.
    "name": "Alaska",  // Display name for the region.
  },
  {
    "targetClass": "US-AZ",  // Unique identifier for region.
    "name": "Arizona",  // Display name for the region.
  }
];

🔹 live_filter

export const live_filter = {
  // HTML ID of the button used to toggle or interact with the live filter
  "button_html_id": "html-content-gmh",

  // Default styling for the map when the filter is applied
  "map": {
    // Background color of the map
    "color": {
      "default": "#f3faff", // Default background color
    },

    // Styling for the map's borders
    "stroke": {
      "color": "#6B8B9E",  /** Border color. */
      "width": "0.8px"     /** Border width. */
    },
  },

  // List of filter categories used to group markers
  "categories": [
    {
      "name": "Blue Markers",   // Display name for the category
      "slug": "blue-markers",   // Unique identifier for the category
      "default": "inactive",    // Default state of the category
    },
    {
      "name": "Orange Markers", // Display name for the category
      "slug": "orange-markers", // Unique identifier for the category
      "default": "inactive",    // Default state of the category
    },
  ],

  // List of markers to be displayed on the map
  "markers": [
    {
      "category_id": "blue-markers", // Slug of the category the marker belongs to
      "tooltip": "Washington", // Text displayed when hovering over the marker
      "shape": "rounded", // Shape of the marker (e.g., "rounded", "cubic")

      // Coordinates for the marker's position
      "position": {
        "x": 120, // Horizontal position of the marker
        "y": 64 // Vertical position of the marker
      },

      // Optional
      "on_click": {
        "url": "https://en.wikipedia.org/wiki/Washington",
        "target": "_blank",
        "cursor": "pointer"
      },

      // Dimensions of the marker
      "size": {
        "radius": 5, // Radius of circular markers
        "width": 8, // Width of rectangular markers
        "height": 8 // Height of rectangular markers
      },

      // Styling for the marker's color
      "color": {
        "default": "#1e73be", // Default color of the marker
        "on_hover": "#005999" // Color of the marker when hovered
      },

      // Border styling for the marker
      "stroke": {
        "color": "white", // Border color
        "width": "1px" // Border width
      },
    },
    {
      "category_id": "orange-markers", // Slug of the category the marker belongs to
      "tooltip": "Texas", // Text displayed when hovering over the marker
      "shape": "rounded", // Shape of the marker (e.g., "rounded", "cubic")

      // Coordinates for the marker's position
      "position": {
        "x": 410, // Horizontal position of the marker
        "y": 430 // Vertical position of the marker
      },

      // Dimensions of the marker
      "size": {
        "radius": 5, // Radius of circular markers
        "width": 8, // Width of rectangular markers
        "height": 8 // Height of rectangular markers
      },

      // Styling for the marker's color
      "color": {
        "default": "orange", // Default color of the marker
        "on_hover": "#005999" // Color of the marker when hovered
      },

      // Border styling for the marker
      "stroke": {
        "color": "white", // Border color
        "width": "1px" // Border width
      },
    },
  ]
}

🧪 Live Filter Configuration

🗺️ Map Styling

🏷️ Filter Categories

📍 Marker Configuration

🔹 general_config

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. */
    "marker_id": "US-MARKER-GMH",  /** ID for the marker element. */
  },
}

🛠️ Initialization Script

<!-- Live Filter -->
<script type="module">
  const currentCountry = "us";

  async function initMap() {
    try {
      // Dynamically import map-specific data
      const {live_filter, 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 {geoMapHubLiveFilter} = await import('/gmh-plugin/assets/js/script/lib/live-filter-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,
          liveFilter: live_filter,
          generalConfig: general_config,
      });

      map.registerPlugin(geoMapHubLiveFilter);
      map.registerPlugin(geoMapHubInteractiveTooltip);

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

  initMap();
</script>
<!-- Live Filter -->

📌 HTML Button Target

Place a container in your HTML with the ID html-content-gmh to inject category buttons dynamically:

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

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 – Live Filter</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="row row-gap-2">
    <div class="col-lg-12 col-12">
      <div class="svg-container-gmh">
        <div id="html-content-gmh"></div>

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

  <!-- Live Filter -->
  <script type="module">
    const currentCountry = "us";

    async function initMap() {
      try {
        // Dynamically import map-specific data
        const {live_filter, 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 {geoMapHubLiveFilter} = await import('/gmh-plugin/assets/js/script/lib/live-filter-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,
          liveFilter: live_filter,
          generalConfig: general_config,
        });

        map.registerPlugin(geoMapHubLiveFilter);
        map.registerPlugin(geoMapHubInteractiveTooltip);

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

    initMap();
  </script>
  <!-- Live Filter -->
</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.

🧪 Output Behavior

When the Live Filter Plugin is initialized and active, it dynamically renders and updates the map's visual elements based on user interactions with filter buttons. Here's what happens on screen:

• ✅ Category buttons are automatically injected into the HTML element with ID defined in button_html_id (e.g., #html-content-gmh)

• 🟢 Buttons toggle states: active/inactive, with optional styling updates

• 📍 Markers appear/disappear based on selected category

• 🔄 Markers associated with selected categories become visible

• 🛑 Markers from unselected categories are hidden