WP Go Maps V10 and above support replacing our internal HTML templates in a few ways, allowing you to easily customize the underlying structure, layout and appearance of nearly every components within the plugin.
This includes our Store Locator, Marker Listings, Directions, and Panel structures on the frontend! For more advanced users, thanks to our underlying core architecture, developers can also take full control of the admin templates using these same techniques!
Modifying our default templates is the most powerful and future-proof way to integrate the map interface perfectly into any theme or integrated customer experience. You can achieve deep customization without ever needing to modify the core plugin files, ensuring your changes persist across plugin updates.
When Should You Override a Template? #
You should override a template when simple CSS or JavaScript modifications are insufficient, or where no internal setting/control is available. Template overrides are the correct approach when your goals require changing the underlying HTML markup.
Let’s take a look at a few example scenarios that might warrant a template override:
- You need to rearrange the order of elements, and CSS reordering is not possible.
- You need to change the wrapping tags to one of our elements to better support your theme styles.
- You would like to fully remove or add new elements to one of our components
- You would like to add a new field to a form, or components (Additional logic handle would be needed as well)
- You are developing a solution for a client with very specific needs and would like to restructure, or isolate components to achieve a very specific niche goal.
Template Files #
Most of our HTML is now controlled via a templated HTML/PHP file which we load as needed within the plugin, and populate dynamically using PHP.
In all cases, regardless of which technique you use to override a template it is important that your own variation of that template contain the same attributes and classnames as our original files. This is to ensure events are triggerred correctly, and that population of dynamic content (inputs, translations, media, etc) continue to function after you complete your override.
To locate, and confirm if a component can be replaced with your own templates, navigate to the respective template folder in each of our plugins:
- Basic: wp-content/plugins/wp-google-maps/html/atlas-novus/
- Pro Add-on: wp-content/plugins/wp-google-maps-pro/html/atlas-novus/
If a file is available within these folders it is almost certainly possible to override it using our template system. There are exceptions to this rule, as some files may be replaced dynamically, or fallback to an alternative template in rare cases.
What About Files Outside of the Atlas Novus Folder? #
Some files, considered legacy files, like older marker listings, or older UI panels are still in use and available even within the Atlas Novus build engine.
Yes, you can override these files as well, and it may be necessary, particularly for marker listing overrides, but your mileage may vary as these files do follow a slightly older structure.
How Can I View These Folders? #
We recommend viewing and downloading the templates via FTP or your hosting Control Panel, however, you can also view the basic files directly on our Github.
Changing Templates via Your WordPress Theme #
This method involves copying the template file into a specific folder structure within your active Child Theme. This is the recommended approach for most visual and structural modifications.
We recommend this approach for developers who would like to modify our templates in a way that will not be undone by future plugin updates, without the need for a dedicated customization plugin.
Parent themes should NOT be used to hold these changes, as any updates released by a theme developer would likely remove/undo your changes. Additionally, if anything goes wrong while making these changes to a parent WordPress theme, it could lead to site-crashing errors that cannot be easily undone.
Instead, we highly recommend creating a child theme. This allows you to extend your parent theme in a safe way, override templates and change structures without any risk of future updates, or file crashes directly within the primary parent theme files.
Child Theme Overrides #
For our example, we will assume you are using a child theme as it is the safest way to approach this kind of override.
- Start by navigating to wp-content/plugins/wp-google-maps/html/atlas-novus/
- Copy the preferred template file, for example store-locator.html.php
- Add it within your child theme under wp-content/themes/childtheme/wp-google-maps/store-locator.html.php
You should end up with a structure like the one found above. The filename (store-locator.html.php) must remain unchanged, and it must be located within a folder named wp-google-maps for the override to take effect.
- Edit your new custom template (wp-content/themes/childtheme/wp-google-maps/store-locator.html.php), in our example we will add a custom CSS class to the store locator, which we will style within our child theme stylesheet:
- Save the file and refresh your map page, and you should see that WP Go Maps has automatically replaced our default store locator with your new customized store locator instead:
Note: When you implement a theme override like this, if our core plugin receives an update, the plugin architecture will update as expected, but the template for your component will not receive that update. This allows the rest of the plugin to remain up to date, while still allowing for deep customization.
Changing Templates via Hooks #
This advanced method involves using a PHP filter to programmatically change the file path the plugin uses to locate a template. This is useful for themes that cannot use a traditional child theme or when managing templates across multiple plugins.
It can also be useful if you instead prefer to make a custom plugin (WP Go Maps Customizations for My Site) to contain your template changes. Doing this may also be helpful if you need the same changes across multiple websites.
Our system utilizes the WordPress action/filter mechanism, specifically a filter hook, to allow developers and advanced users to override the default template file paths, and point them to their own files instead.
The Template Filter #
The core idea is to filter the computed template path file before the template is loaded into our system. We use this same hook for our internal theme filtering mentioned above.
Our internal filter is named: wpgmza_internal_engine_template_path
Here’s an example which filters the store-locator.html.php template and replaces it path with a local plugin file instead:
<?php function my_custom_plugin_template_override($template, $path) { if ($path === 'store-locator.html.php') { $custompath = trailingslashit(__DIR__) . 'templates/custom-locator.php'; if (file_exists($custompath)) { return $custompath; } } // Always return the original $template if no override was applied return $template; } // Hook the custom function into the plugin's template path filter add_filter('wpgmza_internal_engine_template_path', 'my_custom_plugin_template_override', 10, 2);What are Hooks? #
WordPress hooks are a core way for WordPress plugins and themes to interact with eachother, without the need to modify core code, this allows you to extend functionality within our plugin far more easily. If you’d like to learn mode about hooks, please take a look at the WordPress documentation.
Do you have more Hooks? #
Yes! We have many hooks included within WP Go Maps, across our Basic, Pro, Gold and VGM Add-ons. At the moment you can search and explore all basic hooks in our documentation: Hooks
In the future, we plan on also documenting the Pro, Gold, and VGM hooks more diligently.
How can I handle Custom Logic? #
It’s not uncommon when altering tempaltes, to add new controls and form fields. In these cases it may be necessary to develop your own logic to handle these events.
For JavaScript based events, realtime click events for example, we recommend binding your own event handlers using jQuery within a Custom Script.
For PHP logic, you may want to take a look at your developer hooks to determine the best place to implement your custom logic.
