Get started with Travelers’ Map – WordPress Plugin

French translation here.

Table of contents:

  1. Geolocate your posts
  2. Customize your markers
  3. Display your first map
  4. Filter your items and change the map dimensions using the Shortcode Helper
  5. Add several markers on a single post
  6. Change Tiles Provider to customize your map
  7. Uninstall Travelers’ Map and clean up your database
  8. Developers documentation

Geolocate your posts

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

Adding markers to an article with Travelers’ Map

The map makes it quick and easy to change the location of your marker. You can search or simply browse the map. Click on the map to place your first marker. It will then be displayed. You can click again on the map to move it, or with a click and drag. The Latitude and Longitude fields update automatically.

Choose the marker of your choice in the second part (on the right of the map, or below depending on the size of your screen).

By default, the marker will display the title, the excerpt, and the featured image of your post. You can change this information by clicking on the « Change information displayed in popover » button. If you fill in any of these fields, this information will replace the post information in your popover.

Once finished, don’t forget to publish or update your post 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 posts).

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.

Each setting is explained on the helper page, so take the time to read all the possibilities offered by the extension if you want to customize it.

For example, here are some useful parameters:

  • this_post=true: displays only the marker of the current post (if the shortcode is added on your posts)
  • centered_on_this=true: displays all markers, but will zoom in on the current item when the page loads.
  • current_query_markers=true: display the markers corresponding to the page’s query. For example, on your category pages, you can display the posts of the current category, without having to change the shortcode on all your categories (example on my blog).
    You can also display a map on your search results page. Awesome, isn’t it?
  • You can filter by category (cats=isere,savoie), by tag (tags=randonnee), by post type (e.g. your Woocommerce products) and by custom taxonomies (e.g. your Woocommerce product categories)

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

Add several markers on a single post (coming soon)

New in Travelers’ Map V2 (currently in beta, download on github) : You can add multiple markers to a single post! This is great for multiple days of hiking, or city tours for instance. Go to the edit page of your article, in the Travelers’ Map section.

ClClick on « Add an additional marker » to add a marker.

Editing the second marker is done in the same way as the first. When there are several markers on the map, the click moves the « active » marker, i.e. the marker surrounded by a blue border. This border surrounds the marker icon on the map as well as the marker edit block. The first marker is mandatory, it is the main marker.

Adding an anchor to additional markers

If your article contains several markers, it is helpful to be able to add an anchor to your link. This way, the user will be automatically directed to the desired location in your post when they click on the link in the tag.

Step 1: Add an anchor to the desired element on your page.

Click on the block you want to link to your marker. Go to the right in the block settings. In the « Advanced » tab, fill in the « HTML anchor » field.

Step 2: Go to the Travelers’ Map editor at the bottom of the page, click on « Edit information displayed in popover » and fill in the link anchor (#id) fields.

There you go, save your post and your marker will point directly to the right place when users click on it.

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.

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 (let 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 (let 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 😉