Simple Google Maps
Provides a field formatter that displays Google Maps embeds or links from plain text address fields.
simple_gmap
Install
composer require 'drupal/simple_gmap:^4.0'
composer require 'drupal/simple_gmap:^3.1'
Overview
Simple Google Maps is a lightweight module that provides the simplest way to display a Google Map or link to Google Maps from address content. Unlike complex mapping solutions, it requires no Google Maps API key for dynamic maps and no JavaScript configuration.
The module works by providing a field formatter for Drupal's standard plain text fields. Users enter a one-line address (like "100 Madison Ave, New York, NY") into a text field, and the formatter converts it to an embedded Google Map iframe, a static map image, a link to Google Maps, or any combination of these options.
This approach leverages Google Maps' native iframe embedding capability, making it extremely simple to set up and use. The module is ideal for sites that need basic address-to-map functionality without the overhead of dedicated geocoding fields or complex mapping APIs.
Features
- Field formatter that converts plain text addresses to embedded Google Maps iframes
- Optional static map image display using Google Maps Static API (requires API key)
- Configurable link to open the location in Google Maps in a new window
- Display of the original address text alongside or instead of the map
- Customizable map dimensions (width and height in pixels or percentages)
- Zoom level control from 1 (minimum) to 20 (maximum)
- Multiple map types: Map, Satellite, Hybrid, and Terrain
- Language configuration for map display (fixed language code or automatic page language)
- Retina display support for static maps with 2x scaling option
- Accessibility support with configurable iframe titles and alt text for static images
- Special 'use_address' option to use the address itself as the link text
- XSS protection for address text input
Use Cases
Business Location Display
Add a simple text field to a Business content type where editors enter the business address. Configure the formatter to show an embedded map and the address text, allowing visitors to see the location visually and copy the address.
Event Venue Mapping
For event content types, add a location text field formatted with Simple Google Maps. Use the link option with 'use_address' to let users click through to Google Maps for directions.
Contact Page with Static Map
On a contact page, use the static map option to display a non-interactive map image. This provides a clean visual without allowing users to interact with the map, and the image can be optimized for page speed. Requires a Google Maps API key.
Multi-language Site
Set the langcode setting to 'page' to automatically display map labels in the current page language, providing a consistent experience for international visitors.
Mobile-Optimized Maps
Use percentage-based widths (e.g., 100%) for the map to ensure it scales properly on mobile devices. Enable retina scaling for static maps to ensure crisp display on high-resolution screens.
Address Directory with Links
For a directory of locations, configure the formatter to show only the link without the embedded map. This keeps the listing compact while still providing quick access to each location's Google Maps page.
Tips
- Use 'page' as the langcode setting for multilingual sites to automatically display maps in the visitor's language
- Enter 'use_address' as the link text to use the actual address as the clickable link, which is more meaningful to users
- Add help text to your text field explaining the expected format so content editors know to enter Google-recognizable addresses
- The static map option creates a non-interactive image that loads faster and uses less bandwidth than dynamic maps
- For accessibility, always configure the iframe_title and alt_text settings to describe the map's purpose
- Test addresses on maps.google.com first to ensure Google can locate them correctly before entering them in your content
Technical Details
Hooks 1
hook_theme
Implements hook_theme() to define the 'simple_gmap_output' theme hook for rendering the map output.
Troubleshooting 5
Static maps require a valid Google Maps API key. Ensure you have obtained an API key from the Google Cloud Console with the Static Maps API enabled, and enter it in the formatter settings when 'Include embedded static map' is checked.
Ensure the address entered in the text field is a format that Google Maps can recognize. Test by searching for the same address on maps.google.com. Use complete addresses including city and state/country for best results.
Configure the 'Title of the iframe for embedded map' setting in the formatter options. Use [address] to dynamically include the address in the title.
Check the 'Language' setting in the formatter configuration. Set a specific two-letter language code (e.g., 'en', 'de', 'ja') or use 'page' to automatically match the current page language.
For dynamic maps, dimensions can be in pixels (600px) or percentages (100%). For static maps, only pixel values are accepted and should be entered without the 'px' suffix (e.g., 600, not 600px).
Security Notes 4
- The module properly sanitizes user input to prevent XSS attacks in address fields
- API keys for static maps are stored in configuration and exposed in page source - use appropriately restricted API keys
- Address text is URL-encoded before being sent to Google Maps to prevent injection attacks
- All output uses Drupal's render system and Twig auto-escaping for security