Adding Image Hyperlinks to a Cascade
Use images to create buttons, galleries, and more
The current version of the Cascade builder does not support clickable images, partially because humans (and search engines) tend to understand text hyperlinks better than image hyperlinks. We may add support for this feature in a future release, but if you’re eager to add clickable images right away, you can do so by editing your story map’s JSON. What follows is a basic walkthrough of the procedure, plus some tips for advanced image hyperlink configuration.
Requirements:
- A Story Map Cascade
- A publicly accessible image hosted somewhere on the web (including an image uploaded directly to a story map)
- Basic familiarity with HTML and JSON syntax
- A code editor (optional, but highly recommended)
Instructions
If you’ve never edited a story map’s JSON before, be sure to read the article below. It details the risks of, and best practices for, manually modifying the content, structure, and configuration of a story map. Once you’re comfortable with the process, read on!
With the Cascade builder open, insert a new text block wherever you’d like your image link to appear. Add some placeholder text — you’ll eventually replace this with your image — and add your desired hyperlink to that text. Center the text, and save the Cascade.
Next, navigate to https://ago-assistant.esri.com/ and login using the same account you used to create the Cascade. Choose “View an item’s JSON” from the dropdown menu at the top of the screen, and then locate your Cascade in the lefthand column. (You can use the search bar, if necessary.) Select the Cascade item. The righthand column should now be divided into two sections, both filled with JSON code. The top section, “Description,” contains basic metadata about the Cascade item — its title, URL, tags, and so forth. The bottom section, “Data,” includes the content your Cascade—text, maps, images, etc.—and the arrangement thereof. It’s the meat and bones of your story map.
Before tinkering with your story map’s JSON, you should create a backup copy; this way, if you accidentally break something, you can always revert to an earlier version by pasting in the unmodified JSON and re-saving it in AGO Assistant. Click the duplicate (leftmost) button to copy all of the text in the “Data” section, and then open a new window in your code editor and paste in the copied JSON. Save this file to your local machine, and close the window, to avoid any unintended edits. Then, open another tab in your code editor, and paste in the JSON again. This is the version that you’ll modify. (Note: it is possible to edit the JSON directly in AGO Assistant, but it can get a little messy, so we strongly advise using a code editor instead.)
With this file open, locate your placeholder text from before. (You can use CMD+F/CTRL+F to find it in the JSON.) If you added a hyperlink properly, it should look something like the highlighted text below:
The placeholder text is wrapped in a pair of <a></a> (anchor/link) tags, indicating that this entire passage is a hyperlink. We merely want to replace this placeholder text with our image, using the proper HTML syntax. Paste the following snippet exactly where the placeholder text is, in between the <a></a> tags:
<img src=\”https://my-image-path/image.jpg\” style=\”max-width:100%\”>Be sure to replace the placeholder URL in the snippet above with your image’s actual URL, and to include the backslashes, which ensure that the double quotes of the URL are parsed properly. The max-width:100% property will prevent your image from exceeding the maximum width of the paragraph section, and ensure it’s fully responsive. When you’re done, the whole block of code should look something like this (the edited image code is bolded):
{
"type": "text",
"text": {
"value": "<p class=\"block\" style=\"text-align: center; \"><a href=\"https://my-target-url.com\" target=\"_blank\"><img src=\"https://my-image-path/image.jpg\" style=\"max-width:100%\"></a></p>"
}Tip: if you’re not sure where to host your image, and are creating a public story map, you can upload your image directly to your Cascade, add it to your story map, use the developer tools to find its URL, and then remove it from your story map. As long as you don’t delete the image using the Media Picker, and your story is shared publicly, its URL will work just fine.
Highlight and copy all of the JSON from your code editor, and head back to AGO Assistant. Click the edit (middle) button next to the “Data” header to enable edit mode. Paste in your edited JSON from the clipboard. If the code you entered was formatted correctly, the pencil icon will change to a green save icon. Click this button to save the JSON. Return to your Cascade, and bask in the glory of your new, totally clickable image.
Advanced configuration
If you’re feeling adventurous, you can go a step further and style your image hyperlinks using CSS. There are two ways to do this: the first option is to add CSS rules directly to the <img /> or <a> HTML tags, using the following syntax:
<img style=\”CSS property:value\” … />
If you followed the steps above, your image should already contain a max-width:100% CSS rule.
Unfortunately, inline styles don’t support the full range of CSS selectors (such as pseudo-classes, which include hover/active states), and since they mix content (HTML) with presentation (CSS), their use is typically discouraged. If you’re self-hosting your story, a better option is to add a unique CSS class or ID to your <img> or <a> elements, and then add custom styling rules in index.html. This method allows to you implement mouseover effects and other interaction-based styles, and keeps your code nice and tidy.
In the example GIF above, the buttons have been styled using a combination of these two techniques: each image is assigned to the .button class, whose rules are defined in the /* CUSTOM CSS RULES */ section of index.html:
a .button {
filter: saturate(0%) !important;
-webkit-filter: saturate(0%) !important;
-moz-filter: saturate(0%) !important;
max-width: 100%;
transition: filter 0.3s;
-webkit-transition: -webkit-filter 0.3s;
-moz-transition: -moz-filter 0.3s;
} a .button:hover {
filter: saturate(100%) !important;
-webkit-filter: saturate(100%) !important;
-moz-filter: saturate(100%) !important;
}
The .button class leverages CSS filters and transitions to desaturate the images until mouseover.
Additionally, the first image in the example above has its max-width property set to 100% inline, while the second and third images have max-width set to 48% so that the latter two appear side-by-side at most sizes, with a small amount of breathing room. Here’s how the JSON looks for all three images (with placeholder image codes bolded):
{
"type": "text",
"text": {
"value": "<p class=\"block\" style=\"text-align: center; \"><a href=\"https://url-1.com\" target=\"_blank\"><img class=\"button\" src=\"https://url-1.com/image1.jpg\" style=\"max-width=100%\"></a></p>"
}
},
{
"type": "text",
"text": {
"value": "<p class=\"block\"></p>"
}
},
{
"type": "text",
"text": {
"value": "<p class=\"block\" style=\"text-align: center; \"><a href=\"https://url-2.com\" target=\"_blank\"><img class=\"button\" src=\"https://url-2.com/image2.jpg\" style=\"max-width=48%\"></a><a href=\"https://url-3.com/image3.jpg\" target=\"_blank\"><img class=\"button\" src=\"https://url-3.com/image3.jpg\" style=\"max-width=48%\"></a></p>"
}
}
...Whether you’re using image hyperlinks to create simple buttons (like the ones above), or to build a visually striking gallery of related story maps, we’d love to hear about it. Share your customizations with us on Twitter @EsriStoryMaps, or in the comments below!
