Adding custom image carousels to a classic Map Tour

So, you want to add multiple images to each place in your classic Map Tour. Although the classic Map Tour builder doesn’t support this out of the box, it does allow you to embed external web pages in lieu of images and videos — and with a bit of trickery, you can use this option to embed custom image slideshows directly into your tour.

An image carousel in action. View the live version here.

In this tutorial, I’ll show you how to create multi-image carousels (also sometimes referred to as sliders or slideshows), how to upload these carousels to a server so they can be accessed online, and finally, how to embed them directly into your Map Tour. Here’s what you’ll need:

• A code editor (Visual Studio Code, Atom, and Sublime Text are all solid, free options)
• A basic understanding of HTML and JavaScript
• Access to a web server, such as Github Pages, to host your image carousels

Just want to download the code and figure it out on your own? No problem—you can grab the full project ZIP here.

Getting started

The first step is to create your custom image carousels. There are plenty of decent image carousel libraries available, but for the purposes of this demo I’ve opted to use Swiper. It’s actively maintained, well-documented, relatively easy to use (even for a non-developer like myself), and includes lots of options for customization.

To get started, download the latest release of Swiper from Github. Next, extract the ZIP file you just downloaded, and open the unzipped directory. You’ll notice that it contains dozens of folders and files, but only a few of these are relevant to us:

• dist/js/swiper.min.js
• dist/css/swiper.min.css
• demos/010-default.html

Next, create a new folder on your computer, and within that folder, create three additional folders: css, js, and img. We’ll use this new directory to store our carousels. Copy over the three files above, placing swiper.min.css in your new css folder, swiper.min.js in your js folder, and 010-default.html in the root folder. Then, copy all of your images to the img folder. When you’re done, it should look something like this:

Creating your first slider

Once you’ve set up your working directory, open the whole folder in a code editor, and navigate to 010-default.html. This file is a basic slider template; we’re going to make some adjustments to adapt it for our use. Once we’re satisfied with its appearance and behavior, we’ll use it as a template for the other sliders in the Map Tour.

Since we’ve simplified our directory structure, we have to update the references to the CSS and JS files in 010-default.html. On line 7, change the stylesheet reference from ../dist/css/swiper.min.css to css/swiper.min.css, to match our simplified directory structure. On line 66, change the script reference from ..dist/js/swiper.min.js to js/swiper.min.js.

Now, scroll up to the body HTML element — it should be around line 48. The swiper-wrapper element contains a list of divs belonging to the swiper-slide class. Each div corresponds to an individual slide. By default, however, these slides just contain some placeholder text; to turn them into fullscreen images, we’re going to set a background image. To do this, add a style attribute to the div, and then set the background-image property to point to the image’s path. You can go ahead and delete the placeholder text, too. Here’s how your slide code should look once you’re done:

<div class="swiper-slide" style="background-image: url('img/slider1-image1.jpg')"></div>

Note that the image paths can be relative (as in this example), or they could be absolute paths, if your images are already hosted online somewhere, like on Flickr.) To add additional slides, simply duplicate the div above and update the image path. Here’s how it looks after I’ve created four slides:

Once you’ve added a few slides, you probably want to test your carousel. To do this, open a new command line window, navigate to your working directory, fire up a local server (http-server is a reliable, no-nonsense option), and then navigate to the HTML file in your browser. If you’re using http-server, the URL will be localhost:8080/010-default.html.

If everything goes according to plan, you should see your first slide in glorious fullscreen detail! However, you may find that important parts of your image have been cropped out—or conversely, that your image doesn’t fill the screen. This is because, by default, background images are shown at their original sizes. We can fix that! Hop back over to your code editor, and scroll to the swiper-side CSS selector (around line 27). Add the following rules:

background-size: cover !important;
background-repeat: no-repeat !important;
background-position: center !important;

This’ll ensure that the background image is stretched, or shrunken, to fit the whole screen. Much better, right? Right.

Note that you can also override this setting on a slide-by-slide basis in order to “anchor” the slide to specific focal points. For example, if you always want the bottom-right corner of your slide to be visible, you can add a background-position override to the HTML style attribute:

<div class=”swiper-slide” style=”background-image: url(‘img/slider1-image1.jpg’); background-position: right bottom !important”></div>

Customizing your slider

The Swiper library includes a ton of options for adjusting the appearance/behavior of your slides, so we’re going to make a few more adjustments. Scroll to the bottom of the HTML page, to the script that initializes the swiper. By default, it should just read var swiper = new Swiper(‘.swiper-container’); . Go ahead and replace that entire line with the snippet below.

We’ll walk through these options one at a time.

• loop: true enables looping, so that the carousel restarts from the beginning after the final slide.
• Lines 3–6 extend the dwell time on each slide from the default value of 3000ms to 5000ms, and prevent autoplaying from stopping if someone interacts with the slider.
• Lines 7–13 create small pagination bullets, allowing readers to click to navigate to a specific slide.

This final option involves a new HTML element, but we haven’t actually added it into the DOM yet. Paste the following snippet immediately below your swiper-wrapper div, but still within the swiper-container element.

<div class="swiper-pagination"></div>

It should look like this:

Then, scroll up to the style section of the HTML page and paste in the following rules immediately after the .swiper-slide style:

Now if you refresh your test slider, you should see small dots along the bottom, which link to the corresponding slides. Nice! Feel free to play around with the style of these navigation dots, and be sure to check out all the other Swiper options.

Extending your style to multiple carousels

If you want to include a carousel for each place in your Map Tour, you’ll need to create separate carousels. To do so, simply duplicate your modified HTML file and update the slide’s background-image references to point to the images for that slider.

You also probably want to rename your HTML files to something more easily identifiable (e.g., slider-place1.html , or similar). You should also update the title of the HTML page on line 5—by default, it’s set to “Swiper demo”. If, after you’ve created multiple carousels, you discover that you need to make a change to all HTML pages, you can run a find-and-replace operation within the entire directory.

Hosting and embedding your carousels

Once you’re satisfied with your carousels, your next task is to publish them to the web so that they can be embedded in your Map Tour. If you have access to a web server, you can upload the entire directory via FTP. If you don’t have access to a web server, you can use a free hosting service like Github Pages to web-enable your sliders. Configuring Github Pages is beyond the scope of this article, but it’s relatively straightforward, and there’s lots of good documentation elsewhere on the web.

Once your carousels are hosted online, you are ready to add them to your Map Tour. Fire up the Map Tour builder, and—this is critically important—select the “Advanced Options” button, and then click the “Start a new Tour” button.

This will create a fresh, unconfigured Map Tour, with the option to link to content already on the web. In the resulting “Add a new tour point” modal window, the “Media” tab should already be selected. Choose the “Video” option, and then click the “Other” checkbox. Then, paste in the URL of your hosted slider. (In this example, I’m hosting mine on Github Pages.) You should also add a thumbnail image. Since your slider images are already hosted, you could just reuse one image from each slider for the thumbnails—but it’s a much better idea to use smaller images. The optimal size for thumbnails is 250px x 166px. For more information on image sizes, check out the Map Tour FAQ.

Be sure to fill out all the required fields in the “Information” and Location” tabs as well. Then, hit the “Add tour point” button, and revel in the beauty of your multi-image slider! That’s all there is to it.

Oh, and in case you’re wondering, these sliders work on mobile devices as well. In fact, the Swiper library is optimized for touch devices—a nice touch indeed (har har har).

Let us know if you end up using this method in your own stories. We’d love to see what you create!