Get started with Travelers’ Map – WordPress Plugin

French translation here.

Table of contents:


Geolocate your articles

Once the plugin is installed and activated on your WordPress website, the first step is to geolocate your articles. To do this, Travelers’ Map automatically adds a section at the bottom of the editing area of each article.

This is what Travelers’ Map section looks like when added to your article editing pages.

Latitude and Longitude are the position of the marker on the map, and are automatically filled when you place a marker on the map.

Choose a marker allows you to choose the marker’s image that will be displayed on the map. By default, only one marker is available. To add more, see the section “Customize your markers“.

Click directly on the map to add your marker. You can move this marker by clicking and dragging, or by clicking a second time on the map.

  • At the top left of the map are the zoom and unzoom buttons (you can also use your mousewheel when you clicked on the map a first time).
  • Below is a magnifying glass icon that allows you to search for a place. Type your location in the form and suggestions appear. Click on one of them to have your dynamic map automatically zoom in on your location. All you have to do is place your marker on it by clicking on the map.

Once finished, don’t forget to publish or update your article to save the changes.


Customize your markers

To add markers images, go to the left side panel of WordPress administration, under “Travelers’ Map” tab > “Customize markers“.

Travelers’ Map adds 3 submenus to your WordPress administration

A similar page to adding a post opens. To create a new marker, click on “Add new” at the top of the page.
All you have to do now is add a title, add a “Featured image” representing your custom icon and Publish.

Note: .png format is prefered, as it allows you to have a transparent background around the marker unlike the .jpg format. The optimal size for a marker is 45 pixels on its longest side.


Display your first map

To display a map on a page or post, you will use a shortcode. A shortcode is a small code you insert into your content between [brackets]. It is then automatically executed when the page is viewed by visitors.

The shortcode of Travelers’ Map is [travelers-map]. When it is inserted into the content of your page, it turns into a dynamic map, with a width ofv 100% of your content area and 600 pixels high. All the articles you have previously geolocated are displayed there (see: Geolocate your articles).

If you want to change the size of the map and filter the items to display, read the section below.


Filter your items and change the map dimensions using the Shortcode Helper

The Travelers’ Map shortcode also accepts settings. To simplify your task, help is integrated into the plugin in “Travelers’ Map” > “Shortcode Helper” tab.

Shortcode Helper

In this page, when you insert settings or filter categories / labels, the shortcode at the top of the page is automatically updated. Once finished, all you have to do is copy and paste this shortcode into one of your pages.

Instructions are available below each field, here is additional informations:

  • The Max width and Max height values are not used by default. They represent the maximum width or height of your map. For example, if the width of your map is 100%, but you want its maximum width to be 1200px, you can assign a Max width of 1200px. This is particularly useful for sites that adapt to mobile with a percentage value, but don’t want a huge map displayed on a computer screen.
  • Categories allows you to select the categories you want to display on the map. When none is checked, all items are displayed. This is particularly useful if you want to display your maps in your category pages. For example, on my website, the Japan category only displays the articles that are assigned to it.
  • The use of tags is similar to Categories.

Note: Filters can be added together, for example, you can sort items in the “France” category that have a “Bivouac” tag.


Change Tiles Provider to customize your map

Note: You may have noticed that the map on my site is different from the default Travelers’ Map map.
The difference is the Tile provider. Providers use OpenStreetMap’s open data to create maps, each with its own specificities. Some are specialized in hiking and display elevation contours, others are black and white…

To personalize your map, go to the left side panel of WordPress administration, under the “Travelers’ Map” tab.

Settings page

To find a free tile supplier, I recommend Leaflet Providers demo page.

On this website, when you click on the different suppliers on the right, the map changes, and all the information you need in Travelers’ Map are available:

Correspondences with Leaftlet-Providers

Tiles Server URL is represented by L.tileLayer (“Address”) on Leaflet Providers. If your tiles provider requires an API key, insert it directly into the address, as indicated on their website. For example, the url of Thunderforest looks like this: https://{s}{z}/{x}/{y}.png?apikey={apikey}
Here, replace {apikey} with your API key, without the acolades.

Tiles Server sub-domains They are represented by “subdomains” on Leaflet Providers. If subdomains are not specified, enter abc in the field.

Attribution is the text displayed at the bottom right of your map module. It is mandatory when you use the free data from OpenStreetMap and the Leaflet module. In addition, each Tiles provider requires attribution. You will find the necessary Attribution on Leaflet Providers.

If you wish to support this plugin, do not hesitate to add :
| Built with <a href=”” target=”_blank”>Travelers’ Map</a>

Once finished, save the information by clicking on Save Changes. You can reset the options to their original state by clicking Reset settings to default.


Uninstall Travelers’ Map and clean up your database

The geolocation data of your posts are saved as meta-data and are not deleted if Travelers’ Map is disabled or deleted. This is to prevent a user from losing all his data when he mistakenly deactivates/deletes his plugin for debugging purpose.

However, if you want to uninstall Travelers’ Map permanently, an option is available in the “Travelers’ Map” tab at the bottom of the page to delete all geolocation data from your posts.

Please understand this action is irreversible.

Once the data has been deleted, you can uninstall the extension in your “Plugin” tab.


Developers documentation

If you want to interact with your maps on the front-end with javascript, it’s possible since version 1.7.0 of Travelers’ Map! Let’s dive into it with an example.

Interact with the maps objects

The array “cttm_map” containing all the maps objects of Travelers’ Map is now set as a global variable, so you can interact with it from anywhere.

I also created the custom event “cttm_map_loaded” to listen to, so that you know when the maps have been initialised.

Here is a commented code showing how to interact with the maps:

// Listen for the event.
document.addEventListener('cttm_map_loaded', function (e) {
  // cttm_map is an array of all the maps included in the page, so we loop through each.
  for (var i = 0; i < cttm_map.length; i++) {
    //You can now interact with the map object.
    cttm_map[i].setView([45.30824,5.85554], 10);
}, false);

There we go, now the maps on my pages are centered on “La Dent de Crolles”, a beautiful peak you should hike 😉

Example: Adding  Leaflet.Locate plugin to my maps

Leaflet.Locate is a Leaflet plugin adding a button to geolocate the user. It’s available here.

First, we need to enqueue the plugin’s styles and scripts into our wordpress theme. Be sure to upload the .css and .js files into your ‘wp-content/themes/your-theme/css’ and ‘…/js’ folder, register them and enqueue them in your functions.php file.

If you are not familiar with this, you can easily find how to do it by searching on the internet. As a last resort, you can copy and paste the code below in the head tag of your header.php, but you should know this is not the best way to do it.

<link rel="stylesheet" href="">
<link rel="stylesheet" href="" />
<script src="" charset="utf-8"></script>

Now that the files are enqueued, we will add the plugin to every instance of our maps, only after they are initialized. For that, add this javascript code into your theme script.js or in a <script> tag just before the end of your html </body> tag (generally in your footer.php file):

// Listen for the event.
document.addEventListener('cttm_map_loaded', function (e) {
  // cttm_map is an array of all the maps included in the page, so we loop through each.
  for (var i = 0; i < cttm_map.length; i++) {
    //We add a locate control (button) on each of our maps in the page.
}, false);

That’s it! Your users can now locate themselves on your Travelers’ maps. Have fun 😉