Vengala Vinay

Having 12+ Years of Experience in Software Development

Home » Step-by-Step Guide to building a custom interactive mapping module block for Gutenberg using Vanilla JS Web Components

Step-by-Step Guide to building a custom interactive mapping module block for Gutenberg using Vanilla JS Web Components

Project Setup: WordPress Plugin and Block Registration

We’ll begin by establishing the foundational WordPress plugin structure and registering our custom Gutenberg block. This involves creating a simple plugin directory and a main PHP file to enqueue our JavaScript and register the block type. For this example, we’ll assume a plugin named custom-map-block.

First, create the plugin directory and the main PHP file:

mkdir wp-content/plugins/custom-map-block
touch wp-content/plugins/custom-map-block/custom-map-block.php

Populate custom-map-block.php with the standard plugin header and the block registration code. We’ll use the register_block_type function, pointing to a block.json file for metadata and a build directory for our compiled assets.

Create wp-content/plugins/custom-map-block/custom-map-block.php:

<?php
/**
 * Plugin Name: Custom Map Block
 * Description: A custom interactive mapping module block for Gutenberg.
 * Version: 1.0.0
 * Author: Your Name
 * License: GPL-2.0-or-later
 * Text Domain: custom-map-block
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly.
}

/**
 * Registers the block using the metadata loaded from the `block.json` file.
 * Behind the scenes, it registers also all assets so they can be enqueued
 * through the block editor in the corresponding context.
 *
 * @see https://developer.wordpress.org/reference/functions/register_block_type/
 */
function custom_map_block_init() {
    register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'custom_map_block_init' );
?>

Next, create the block.json file to define our block’s attributes, script dependencies, and editor/frontend scripts. This file is crucial for Gutenberg to understand and load our block correctly.

Create wp-content/plugins/custom-map-block/block.json:

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "custom-map-block/interactive-map",
    "version": "0.1.0",
    "title": "Interactive Map",
    "category": "widgets",
    "icon": "location-alt",
    "description": "An interactive map module using Web Components.",
    "keywords": [ "map", "interactive", "custom" ],
    "attributes": {
        "mapCenter": {
            "type": "object",
            "default": { "lat": 40.7128, "lng": -74.0060 }
        },
        "zoomLevel": {
            "type": "number",
            "default": 12
        },
        "apiKey": {
            "type": "string",
            "default": ""
        }
    },
    "textdomain": "custom-map-block",
    "editorScript": "file:./build/index.js",
    "editorStyle": "file:./build/index.css",
    "style": "file:./build/style-index.css",
    "viewScript": "file:./build/view.js"
}

Frontend and Editor JavaScript with Web Components

The core of our interactive map will be a Web Component. This component will encapsulate the map’s logic and rendering, making it reusable and framework-agnostic. We’ll use Vanilla JavaScript for this. The editorScript in block.json will load the editor-specific JavaScript, while viewScript will load the frontend JavaScript.

First, let’s define our Web Component. Create a file for the component’s definition, for example, src/map-component.js.

// src/map-component.js
class InteractiveMap extends HTMLElement {
    constructor() {
        super();
        this.attachShadow({ mode: 'open' });
        this.mapContainer = null;
        this.map = null;
        this.center = { lat: 40.7128, lng: -74.0060 }; // Default
        this.zoom = 12; // Default
        this.apiKey = '';
    }

    static get observedAttributes() {
        return ['data-center-lat', 'data-center-lng', 'data-zoom', 'data-api-key'];
    }

    connectedCallback() {
        this.center.lat = parseFloat(this.getAttribute('data-center-lat')) || this.center.lat;
        this.center.lng = parseFloat(this.getAttribute('data-center-lng')) || this.center.lng;
        this.zoom = parseInt(this.getAttribute('data-zoom'), 10) || this.zoom;
        this.apiKey = this.getAttribute('data-api-key') || this.apiKey;

        this.render();
        this.initMap();
    }

    attributeChangedCallback(name, oldValue, newValue) {
        if (oldValue !== newValue) {
            switch (name) {
                case 'data-center-lat':
                    this.center.lat = parseFloat(newValue);
                    if (this.map) this.map.setCenter(this.center);
                    break;
                case 'data-center-lng':
                    this.center.lng = parseFloat(newValue);
                    if (this.map) this.map.setCenter(this.center);
                    break;
                case 'data-zoom':
                    this.zoom = parseInt(newValue, 10);
                    if (this.map) this.map.setZoom(this.zoom);
                    break;
                case 'data-api-key':
                    this.apiKey = newValue;
                    // Re-initialize map if API key changes and map already exists
                    if (this.map) {
                        this.initMap();
                    }
                    break;
            }
        }
    }

    render() {
        this.shadowRoot.innerHTML = `
            <style>
                :host {
                    display: block;
                    width: 100%;
                    height: 400px; /* Default height, can be overridden */
                }
                #map-container {
                    width: 100%;
                    height: 100%;
                }
            </style>
            <div id="map-container"></div>
        `;
        this.mapContainer = this.shadowRoot.getElementById('map-container');
    }

    initMap() {
        if (!this.apiKey) {
            console.error('API Key is required for the map.');
            this.mapContainer.innerHTML = '<p>Map API key is missing.</p>';
            return;
        }

        // Placeholder for actual map initialization (e.g., Leaflet, Google Maps API)
        // For demonstration, we'll simulate map initialization.
        // In a real scenario, you'd load a map library here.

        console.log(`Initializing map with center: ${this.center.lat}, ${this.center.lng}, zoom: ${this.zoom}, apiKey: ${this.apiKey}`);

        // Example using a hypothetical map library
        // if (typeof MapLibrary !== 'undefined') {
        //     this.map = new MapLibrary(this.mapContainer, {
        //         center: this.center,
        //         zoom: this.zoom,
        //         apiKey: this.apiKey
        //     });
        // } else {
        //     console.error('Map library not loaded.');
        //     this.mapContainer.innerHTML = '<p>Map library failed to load.</p>';
        // }

        // For this example, we'll just display a message
        this.mapContainer.innerHTML = `<p>Map would be initialized here with center (${this.center.lat}, ${this.center.lng}) and zoom ${this.zoom}. API Key: ${this.apiKey}</p>`;
        // Simulate map object for attribute updates
        this.map = {
            setCenter: (newCenter) => {
                console.log('Map center updated to:', newCenter);
                this.center = newCenter;
            },
            setZoom: (newZoom) => {
                console.log('Map zoom updated to:', newZoom);
                this.zoom = newZoom;
            }
        };
    }
}

// Define the custom element
if (!customElements.get('interactive-map')) {
    customElements.define('interactive-map', InteractiveMap);
}

Now, we need to register this Web Component within our Gutenberg block’s JavaScript. This involves creating the index.js for the editor and view.js for the frontend.

Create src/index.js (for the editor):

// src/index.js
import { registerBlockType } from '@wordpress/blocks';
import { InspectorControls, useBlockProps } from '@wordpress/block-editor';
import { PanelBody, TextControl, RangeControl } from '@wordpress/components';
import './map-component'; // Import the Web Component definition

const Edit = ({ attributes, setAttributes }) => {
    const { mapCenter, zoomLevel, apiKey } = attributes;

    const blockProps = useBlockProps();

    const handleCenterLatChange = (newLat) => {
        setAttributes({ mapCenter: { ...mapCenter, lat: parseFloat(newLat) } });
    };

    const handleCenterLngChange = (newLng) => {
        setAttributes({ mapCenter: { ...mapCenter, lng: parseFloat(newLng) } });
    };

    const handleZoomChange = (newZoom) => {
        setAttributes({ zoomLevel: newZoom });
    };

    const handleApiKeyChange = (newApiKey) => {
        setAttributes({ apiKey: newApiKey });
    };

    // Render the Web Component in the editor.
    // We pass attributes as data-* properties for the Web Component.
    return (
        <>
            <InspectorControls>
                <PanelBody title="Map Settings" initialOpen={ true }>
                    <TextControl
                        label="API Key"
                        value={ apiKey }
                        onChange={ handleApiKeyChange }
                        help="Enter your map service API key."
                    />
                    <TextControl
                        label="Center Latitude"
                        value={ mapCenter.lat.toString() }
                        onChange={ handleCenterLatChange }
                        type="number"
                        step="any"
                    />
                    <TextControl
                        label="Center Longitude"
                        value={ mapCenter.lng.toString() }
                        onChange={ handleCenterLngChange }
                        type="number"
                        step="any"
                    />
                    <RangeControl
                        label="Zoom Level"
                        value={ zoomLevel }
                        onChange={ handleZoomChange }
                        min={ 1 }
                        max={ 20 }
                    />
                </PanelBody>
            </InspectorControls>
            <div { ...blockProps }>
                <interactive-map
                    data-center-lat={ mapCenter.lat }
                    data-center-lng={ mapCenter.lng }
                    data-zoom={ zoomLevel }
                    data-api-key={ apiKey }
                ></interactive-map>
            </div>
        </>
    );
};

registerBlockType('custom-map-block/interactive-map', {
    edit: Edit,
    save: ({ attributes }) => {
        const { mapCenter, zoomLevel, apiKey } = attributes;
        // The save function should return the markup that will be saved to the database.
        // For Web Components, we typically render the element with its attributes.
        // The viewScript will then hydrate it on the frontend.
        return (
            <interactive-map
                data-center-lat={ mapCenter.lat }
                data-center-lng={ mapCenter.lng }
                data-zoom={ zoomLevel }
                data-api-key={ apiKey }
            ></interactive-map>
        );
    },
});

Create src/view.js (for the frontend):

// src/view.js
import './map-component'; // Ensure the Web Component is defined

document.addEventListener('DOMContentLoaded', () => {
    // Find all instances of our custom map element on the page.
    const mapElements = document.querySelectorAll('interactive-map');

    mapElements.forEach(mapElement => {
        // The Web Component's connectedCallback will handle initialization
        // when it's attached to the DOM. Since we're rendering it directly
        // in the save function, it will be present on page load.
        // If dynamic loading or further JS interaction is needed, you might
        // re-initialize or update properties here.

        // Example: If you needed to explicitly trigger initialization after
        // some other script has run, you could do:
        // if (mapElement.initMap) { // Assuming initMap is a public method
        //     mapElement.initMap();
        // }

        console.log('Interactive map element found on frontend.');
        // The Web Component's connectedCallback should have already run.
        // If the map library needs to be loaded dynamically or if there are
        // complex dependencies, you might add logic here.
    });
});

We also need a CSS file for the block’s styles. Create src/index.css for the editor styles and src/style.scss (or .css) for frontend styles. For simplicity, we’ll use index.css for both editor and frontend in this example, though a separate style.css is best practice.

Create src/index.css:

/* src/index.css */
.wp-block-custom-map-block-interactive-map {
    margin-bottom: 1.5em;
}

/* Styles for the Web Component itself, if needed outside the shadow DOM */
interactive-map {
    display: block;
    width: 100%;
    height: 400px; /* Default height */
    border: 1px solid #ccc;
}

Build Process and Asset Compilation

To compile our JavaScript and CSS, we need a build process. WordPress development typically uses tools like `@wordpress/scripts` which provides a convenient way to handle bundling, transpilation, and asset generation. We’ll set this up using npm.

Initialize npm in your plugin directory and install the necessary scripts:

cd wp-content/plugins/custom-map-block
npm init -y
npm install @wordpress/scripts --save-dev

Add the build scripts to your package.json:

{
  "name": "custom-map-block",
  "version": "1.0.0",
  "description": "",
  "main": "custom-map-block.php",
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@wordpress/scripts": "^27.7.0"
  }
}

Now, create the src directory and place your JavaScript and CSS files inside it:

mkdir src
mv src/map-component.js src/index.js src/index.css .

Run the build command to compile your assets into the build directory:

npm run build

This command will generate build/index.js, build/index.css, and build/style-index.css (which is a combination of editor and frontend styles by default with `@wordpress/scripts`). The block.json file correctly points to these compiled assets.

Integrating a Real Mapping Library (e.g., Leaflet)

The previous example used a placeholder for map initialization. To make this functional, we need to integrate a real mapping library. Leaflet is a popular, lightweight, open-source JavaScript library for mobile-friendly interactive maps. We’ll demonstrate how to include it and use it within our Web Component.

First, add Leaflet as a dependency. You can either install it via npm or include it via a CDN. For production, using npm and bundling is generally preferred for better performance and dependency management.

npm install leaflet --save

Update your src/map-component.js to use Leaflet:

// src/map-component.js (Updated for Leaflet)
import L from 'leaflet'; // Import Leaflet
import 'leaflet/dist/leaflet.css'; // Import Leaflet CSS

class InteractiveMap extends HTMLElement {
    constructor() {
        super();
        this.attachShadow({ mode: 'open' });
        this.mapContainer = null;
        this.map = null;
        this.center = { lat: 40.7128, lng: -74.0060 }; // Default
        this.zoom = 12; // Default
        this.apiKey = ''; // For services like Mapbox or Google Maps
        this.tileLayerUrl = 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'; // Default OpenStreetMap
    }

    static get observedAttributes() {
        return ['data-center-lat', 'data-center-lng', 'data-zoom', 'data-api-key', 'data-tile-layer-url'];
    }

    connectedCallback() {
        this.center.lat = parseFloat(this.getAttribute('data-center-lat')) || this.center.lat;
        this.center.lng = parseFloat(this.getAttribute('data-center-lng')) || this.center.lng;
        this.zoom = parseInt(this.getAttribute('data-zoom'), 10) || this.zoom;
        this.apiKey = this.getAttribute('data-api-key') || this.apiKey;
        this.tileLayerUrl = this.getAttribute('data-tile-layer-url') || this.tileLayerUrl;

        this.render();
        this.initMap();
    }

    attributeChangedCallback(name, oldValue, newValue) {
        if (oldValue !== newValue) {
            switch (name) {
                case 'data-center-lat':
                    this.center.lat = parseFloat(newValue);
                    if (this.map) this.map.setView(this.center, this.zoom);
                    break;
                case 'data-center-lng':
                    this.center.lng = parseFloat(newValue);
                    if (this.map) this.map.setView(this.center, this.zoom);
                    break;
                case 'data-zoom':
                    this.zoom = parseInt(newValue, 10);
                    if (this.map) this.map.setZoom(this.zoom);
                    break;
                case 'data-api-key':
                    this.apiKey = newValue;
                    // If using an API key for tile layers, re-initialize
                    if (this.map) {
                        this.initMap();
                    }
                    break;
                case 'data-tile-layer-url':
                    this.tileLayerUrl = newValue;
                    if (this.map) {
                        this.initMap();
                    }
                    break;
            }
        }
    }

    render() {
        this.shadowRoot.innerHTML = `
            <style>
                :host {
                    display: block;
                    width: 100%;
                    height: 400px;
                }
                #map-container {
                    width: 100%;
                    height: 100%;
                    background-color: #f0f0f0; /* Placeholder background */
                }
                /* Leaflet icon fix for Web Components */
                /* You might need to adjust paths or use absolute URLs */
                @import url('https://unpkg.com/[email protected]/dist/leaflet.css'); /* Ensure Leaflet CSS is loaded */
            </style>
            <div id="map-container"></div>
        `;
        this.mapContainer = this.shadowRoot.getElementById('map-container');
    }

    initMap() {
        // Clear previous map if it exists
        if (this.map) {
            this.map.remove();
            this.map = null;
        }

        if (!this.mapContainer) {
            console.error('Map container not found.');
            return;
        }

        // Construct the tile layer URL, potentially including API key
        let currentTileLayerUrl = this.tileLayerUrl;
        if (this.apiKey && (this.tileLayerUrl.includes('{apiKey}') || this.tileLayerUrl.includes('key='))) {
            currentTileLayerUrl = this.tileLayerUrl.replace('{apiKey}', this.apiKey).replace('key=', `key=${this.apiKey}`);
        }

        try {
            this.map = L.map(this.mapContainer).setView(this.center, this.zoom);

            L.tileLayer(currentTileLayerUrl, {
                maxZoom: 19,
                attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
                // Add API key to options if the tile provider requires it (e.g., Mapbox)
                // apikey: this.apiKey // Example for a hypothetical provider
            }).addTo(this.map);

            // Add a marker as an example
            L.marker(this.center).addTo(this.map)
                .bindPopup('A marker at the center.')
                .openPopup();

            console.log('Leaflet map initialized.');

        } catch (error) {
            console.error('Error initializing Leaflet map:', error);
            this.mapContainer.innerHTML = '<p>Failed to load map. Check console for errors.</p>';
        }
    }
}

// Define the custom element
if (!customElements.get('interactive-map')) {
    customElements.define('interactive-map', InteractiveMap);
}

You’ll also need to ensure Leaflet’s CSS is correctly loaded. The import statement in the Web Component’s JS is one way, but it’s often better to enqueue it via WordPress’s `wp_enqueue_script` or `wp_enqueue_style` if you’re not bundling everything. For this example, we’ll rely on the import within the component and ensure the build process handles it.

Update your src/index.js to include Leaflet CSS if not handled by the Web Component’s import:

// src/index.js (Updated for Leaflet CSS)
import { registerBlockType } from '@wordpress/blocks';
import { InspectorControls, useBlockProps } from '@wordpress/block-editor';
import { PanelBody, TextControl, RangeControl } from '@wordpress/components';
import './map-component'; // Import the Web Component definition
import 'leaflet/dist/leaflet.css'; // Import Leaflet CSS for editor context

// ... (rest of the Edit and save functions remain similar)
// Ensure the Web Component is rendered with necessary data attributes.

const Edit = ({ attributes, setAttributes }) => {
    const { mapCenter, zoomLevel, apiKey } = attributes;

    const blockProps = useBlockProps();

    const handleCenterLatChange = (newLat) => {
        setAttributes({ mapCenter: { ...mapCenter, lat: parseFloat(newLat) } });
    };

    const handleCenterLngChange = (newLng) => {
        setAttributes({ mapCenter: { ...mapCenter, lng: parseFloat(newLng) } });
    };

    const handleZoomChange = (newZoom) => {
        setAttributes({ zoomLevel: newZoom });
    };

    const handleApiKeyChange = (newApiKey) => {
        setAttributes({ apiKey: newApiKey });
    };

    return (
        <>
            <InspectorControls>
                <PanelBody title="Map Settings" initialOpen={ true }>
                    <TextControl
                        label="API Key"
                        value={ apiKey }
                        onChange={ handleApiKeyChange }
                        help="Enter your map service API key (e.g., for Mapbox)."
                    />
                    <TextControl
                        label="Center Latitude"
                        value={ mapCenter.lat.toString() }
                        onChange={ handleCenterLatChange }
                        type="number"
                        step="any"
                    />
                    <TextControl
                        label="Center Longitude"
                        value={ mapCenter.lng.toString() }
                        onChange={ handleCenterLngChange }
                        type="number"
                        step="any"
                    />
                    <RangeControl
                        label="Zoom Level"
                        value={ zoomLevel }
                        onChange={ handleZoomChange }
                        min={ 1 }
                        max={ 20 }
                    />
                </PanelBody>
            </InspectorControls>
            <div { ...blockProps }>
                <interactive-map
                    data-center-lat={ mapCenter.lat }
                    data-center-lng={ mapCenter.lng }
                    data-zoom={ zoomLevel }
                    data-api-key={ apiKey }
                ></interactive-map>
            </div>
        </>
    );
};

registerBlockType('custom-map-block/interactive-map', {
    edit: Edit,
    save: ({ attributes }) => {
        const { mapCenter, zoomLevel, apiKey } = attributes;
        return (
            <interactive-map
                data-center-lat={ mapCenter.lat }
                data-center-lng={ mapCenter.lng }
                data-zoom={ zoomLevel }
                data-api-key={ apiKey }
            ></interactive-map>
        );
    },
});

After updating the JavaScript files, run npm run build again to recompile the assets.

Deployment and Usage

To deploy the plugin, simply copy the entire custom-map-block directory into your WordPress installation’s wp-content/plugins/ directory. Activate the “Custom Map Block” plugin from the WordPress admin area. You can then add the “Interactive Map” block to any post or page and configure its center coordinates, zoom level, and API key (if required by your chosen map tile provider).

For enterprise-level deployments, consider:

  • Asset Optimization: Ensure your build process is optimized for production (e.g., minification, code splitting).
  • API Key Management: Store API keys securely. Avoid hardcoding them directly in the block’s attributes if they are sensitive. Consider using WordPress options or custom fields managed server-side.
  • Performance: For very large sites, analyze the impact of loading map libraries. Lazy loading map components can be beneficial.
  • Accessibility: Ensure map interactions are accessible, potentially by providing alternative text descriptions or keyboard navigation for map features.
  • Error Handling: Robust error handling for map tile loading and API key validation is crucial.

This approach provides a flexible, reusable, and framework-agnostic interactive map component that can be seamlessly integrated into WordPress content via a custom Gutenberg block.

Recent Posts

Top Categories

Our Products

Our Services