At the end of April Backdrop CMS was graced with the addition of the Leaflet module which enables us Backdrop fans to do much of the mapping that we used to do in Drupal. Thanks for this go to the module’s maintainers, Wes Jones and Indigoxela. This is a huge step for the Backdropcommunity and the champagne corks deserve to be popped. (At the time of writing, the module is an rc1 version.)

One of the reasons that people reach for Drupal and its simpler but just as powerful fork of Backdrop is the existence of the Views module. Drupal Views and Backdrop Views offer something that WordPress people would pay dearly for. It’s a module of immense power, lying at the heart of these two CMSs which provides configurable out-of-the-box database reporting. If you need to display structured lists of content, Views does it brilliantly. Both versions are modular systems into which can be plugged additional modules/sub-modules for increased functionality. Such is the case with the Backdrop Leaflet module, to which this post is devoted, as it has a Leaflet views sub-module which provides Views functionality within the Leaflet mapping environment.

Who needs the Leaflet module in Backdrop CMS?

You will need Leaflet if you have content that uses location data that can be displayed on a map. More specifically, if your content nodes contain location data that can be expressed as longitude-latitude co-ordinates, and if you wish all these points to be displayed side-by-side on a single map, then Leaflet is for you.

Some examples of this type of map-based presentation are: town/city/county/state/region/country maps of restaurants, electric car charge points, traffic pollution monitoring sites, etc. Each instance of these groups will be represented by a different marker on the same map. Clicking any marker will pop up its name (the node title), then clicking the title link in that popup will navigate users to that content page in the site. Maps like these can serve as indexes of similar content (although link behaviour of this kind can be toggled off). (An example of such a map on this site displays places of interest that I have visited in north-west Europe — done in Backdrop, naturally.) The internet is replete with such map displays but having a module that helps you create them in Backdrop is new.

Leaflet, if you’re not familiar with it, is “an open-source JavaScript library for mobile-friendly interactive maps”. It is elegant, powerful and lightweight, and gives you a library of different maps to work with, thrillingly expanding a site builder’s choice far beyond Google. Play also with maps from Bing, Esri, MapBox, OSM, Stamen and Yandex. It’s a big toy chest! Spend a bit of time on their website to get a feel of what’s available — because a lot of this is now yours to play with in Backdrop, tada!

Here’s how to do it …

Configuring a content type to store geolocation data

Install and enable the Geofield module. Navigate to your content type and add a new field. Name it Geofield; specify Geofield as the data store; and specify Latitude / Logitude as the form element to edit the data, then save your changes:

Adding a Geofield field to a content type in Backdrop
Adding a Geofield field to a content type in Backdrop

This will give you the ability to input longitude and latitude only. Here’s the editing view:

The editor's view of the Backdrop Geofield module's functionality.
The editor’s view of the Backdrop Geofield module’s functionality.

This may be perfectly adequate as is, but you might prefer for content editors to have a map view with which to add a geolocation. To accomplish that, you will need to install the separate Geolocation module. Download that module and install it. You will see that it has two sub-modules: Geolocation Google Maps and Geolocation HTML5. First enable the Geolocation module and save the configuration, then install the Geolocation Google Maps submodule:

Installing the Geolocation module and sub-module in Backdrop
Installing the Geolocation module and Geolocation Google Maps sub-module in Backdrop

You will need to unlock the field’s functionality with a Google Simple API Access Key, which can be requested here, and which you then paste in to the single field at /admin/config/services/googlemaps. (It’s a while since I first picked up my own API Key so there may be some gotchas that I’m not aware of. When I did this, there was no charge or requirement to provide payment details.)

You can use the Geolocation Google Maps module on its own to save location co-ordinates for use with the Leaflet module. If you don’t want to engage with Google’s API and possible subscription model, the Geofield module on its own will function perfectly well, although that module won’t provide a location selection process using a map in edit mode.

What you have just done is to provision your content type with ‘location awareness’ such that Views can access the entire collection of the content type and render all their locations together on a single Leaflet map. You may wish to think about what effect this has on the public appearance of each individual instance of that content type. To do that, visit the Manage Displays page of the content type:

Depending upon which of these two modules you installed, you would either work on the display of the Geolocation Google Maps module:

Display options for the Google Map field
Display options for the Google Map field

… or work on the display of the Geofield module:

Display options for the Geofield field
Display options for the Geofield field

You could select the ‘Hidden’ options in the two drop-downs under the Label and Format column. Equally, you could publicly display either the long-lat co-ordinates and/or a Google Map with just the one map marker relevant to that single piece of content. (Remember that here you don’t need both modules; you have the choice of using either the Geolocation Google Maps module or the Geofield module.)

Installing and enabling the Leaflet module in Backdrop

Next pick up the Leaflet module, and enable it:

Enabling the Leaflet module and sub-modules in Backdrop
Enabling the Leaflet module and sub-modules in Backdrop

Start by enabling the Leaflet module, then Save your changes. Then enable the Leaflet views and Leaflet More Maps sub-modules. The latter provides the ability to input a Thunderforest API Key and a Mapbox access token, and to create hybrid maps that combine layers from different map providers. (The Leaflet Markerclusterer sub-module is discussed below.)

Building a Backdrop view to display node data on a Leaflet map

Now for the fun bit. Fire up Views in Backdrop (/admin/structure/views/add). Give the view a name, and select your newly-created location aware content type in the “of type” drop-down. Create a page, give it a path and create a menu link. Specify “0” items to display so that all instances of the selected content type will be displayed. Click the “Continue & Configure” button.

The editing side of the wonder that is Views will now appear. The first step is to select the Format. Do this by clicking the “Unformatted list” link. In the resulting popup, select the “Leaflet Map” option:

Selecting the Leaflet Map format for the new view
Selecting the Leaflet Map format for the new view

You will then be prompted to “add at least one geofield to the view”. The Fields section will at this point show just the Title field. Click the “ADD” link and select the Geofield field that you created earlier:

Adding a Geofield field to the Leaflet view
Adding a Geofield field to the Leaflet view

Clicking the “ADD & CONFIGURE FIELDS” button in the above popup will display the following popup for configuring the Geofield field.

Configuring the Geofield field in the Leaflet view
Configuring the Geofield field in the Leaflet view

The settings you need are: no label; exclude from display; Latitude/Longitude for the Formatter; Use full geometry for the Data options; Decimal degrees for the Format. For everything else: leave the default settings which could be refined later.

The final step — which is probably the fun bit that you will wish to explore repeatedly — is the Settings option for the View format. The Settings link is the one to click:

The Settings link for the View format
The Settings link for the View format

Here’s this all-important Settings popup:

Configuring the settings for the Leaflet view
Configuring the settings for the Leaflet view

The Data Source has to be the Geofield field; if you followed the above, there will be no other option. You will probably want the Title field to be the node’s title; this will appear as a tooltip when hovered with a mouse, as seen here:

A tooltip for a marker in a Leaflet view
A tooltip for a marker in a Leaflet view

The Description Content is what will appear in the marker’s popup window. You could choose the “<node entity>” option, and in the View mode drop-down that will then appear (circled in red above — and only shown if and when you choose the “<node entity>” value), you could choose the Teaser option. Experiment and see which works best for your content. (The Popup minimum width setting will be helpful if you have chosen an image field in the Description Content drop-down.) Finally, you have the type of map and its height, the best bits of the toy chest!

Based upon the above settings and with just two pieces of content, here’s a screenshot of the resulting map:

A screenshot of the resulting Leaflet map
A screenshot of the resulting Leaflet map

Clicking one of those two map markers will display the popup for the node whose marker you clicked, here showing the node’s teaser content.

A screenshot of the resulting Leaflet map with its marker popup showing node teaser content
A screenshot of the resulting Leaflet map with its marker popup showing node teaser content

If instead of the teaser content showing in each content piece’s popup, you wanted an image, then you’d need to add an image field to the content type, then add that field to the fields section of the view:

Adding a field to the Leaflet view's field list
Adding a field to the Leaflet view’s field list

Clicking that newly-added field link pops up the configuration options for the field:

Configuring the image field in the Leaflet view
Configuring the image field in the Leaflet view

The default settings will be mostly correct. You can ignore the image style as at the time of writing the module does not respect image style sizes. Instead, return to the Format Settings options and specify a Popup minimum width, as this will override any image styles that would otherwise have been operating:

Specify a minimum width for the Leaflet map markers' popups
Specify a minimum width for the Leaflet map markers’ popups

Link the image to the content (meaning that users will be able to navigate to the page on the site devoted to the content whose map marker they have just clicked). The resulting popup will look something like this.

Leaflet map marker showing an image beneath its title
Leaflet map marker showing an image beneath its title

At the time of writing it is not possible to display both teaser text and an image within these map marker popups.

The Leaflet Markerclusterer sub-module

When your map displays an abundance of markers near a given location, you can aggregate these into a single ‘cluster’ marker. As users zoom in on the map, those clusters expand into distinct markers for each separate location.

Leaflet map with markers
Leaflet map with markers
Leaflet map with marker clustering
Leaflet map with marker clustering

The Leaflet module provides no ability to tweak the way in which this functions, although in practice it works just fine, providing an intuitive way of handling over-crowded maps.

Leaflet modules and sub-modules in Backdrop CMS
Leaflet modules and sub-modules in Backdrop

If you want your map markers to be clustered, make sure that you enable the Leaflet Markercluster sub-module. If you originally enabled that sub-module and find that you don’t want marker clustering, disable that sub-module. (You will find that clustering appears to be enabled by default for Thuderforest maps even if this particular sub-module has been disabled.)

(As a screenshot of the Leaflet sub-modules is within view, above, it’s worth noting that the Leaflet Demo sub-module did nothing at the time of writing.)

Possible options for the Backdrop Leaflet module

An item on any wish list for this module — which would be beyond good — would be to be able to have two fields shown in each marker’s popup beneath the title, such as a teaser (or specified string length of a given text field) as well as an image. When this sort of mapping service was provided with Leaflet courtesy of the Drupal 7 IP Geolocation Views & Maps module, this was indeed possible with following result:

Leaflet map marker showing more than one field in Drupal 7
Leaflet map marker showing more than one field in Drupal 7

But this is being greedy, isn’t it? The state of play at present allows maps of nearly this degree of sophistication to be displayed in Backdrop and for those of us whose are passionately loyal to this particular CMS, this is very good news indeed.

If this post has helped you make sense of it all and allowed you to publish a map of your content, please drop me a line. Happy mapping!

(The finished Leaflet map view on this website can be found here. As and when additional functionality is added to this powerful module, this map will be updated accordingly.)