Showcase your photos in Map Tour with Readmore.js
The Story Map Tour application provides a engaging user experience when you want to showcase a sequence of photos and their associated locations. By design your photo will become the “hero” of the app while the map comes along for supporting content. While the app does provide a space for a title and description, it is easy to write too much. Long descriptions and can easily begin to cover up large portions of the photos and be distracting.
Readmore.js is a small jQuery plugin that allows us to automatically condense the description and provide a “Read more” button to fully expand the text.
Essentials for Success
- Have access to a web server to host your customized story.
- Create a Story Map using one of Esri’s Story Map apps.
- Basic understanding of HTML/CSS/JavaScript.
Getting Started
A few years ago, our team created a Story Map Tour displaying a selection of great tourist attractions around San Diego, CA. This app had lots of beautiful photos but the the longer descriptions makes it a perfect choice for this demo.
To begin, we’ll first need to download the source code. All of the Story Map apps are open source and available for download so you can use and customize as you wish. The source code for each app can be found by navigating to our apps page and clicking the “Learn More” button under the description for each app. About halfway down this page, you should see a link to “Download configurable app.” Unzip the contents of this download to a new folder on your server.
Next, you’ll need to get the application ID that is associated with the version of the app that is hosted on ArcGIS Online. All the content of your story will still be hosted on ArcGIS Online and you’ll still be able to use the online builder to edit your story. The application ID will link your hosted version with the customized version that is now on your server. This application ID can be found by looking at the URL of your hosted app. Just copy the alphanumeric code that comes after the “appid=” in the url (see example in bold below).
http://www.arcgis.com/apps/MapTour/?appid=d1ef0471365e400ebb540472b477871eOnce you have this open the index.html file in your favorite text editor. Notepad works fine but I recommend using a text editor that has syntax highlighting to make it much easier to read. Notepad++ and Atom Editor are two free apps that work really well on both Mac and PC. Scroll down to configuration section and paste the application ID between the quotes of the appid variable.
At this point, if you open the app in your browser, you should have an exact duplicate of the app you created in ArcGIS Online except it will be hosted on your own server.
Add supporting CSS
The default design of the map tour app places the description next to the title. When providing a collapsable description, I find it much easier to read if the description is stacked below the title. This will provide less movement when expanding the description. We can accomplish this by adding a small amount of CSS in the index.html.
Open the index.html file and scroll down to the first line of the body tag (this should be around line 185). Here you’ll find a style tag that and a comment that reads “Enter custom CSS here.”
Go ahead and add the following lines of code:
#placard .name, #placard .description {
padding: 10px;
width: auto;
}Here were selecting both the title and description elements and giving them even padding. We’re also reseting their width to 100% so they will not float to the same line.
While we’re here, we’ll also provide the CSS for our “Read more” button.
#placard a[data-readmore-toggle] {
font-size: 12px;
text-decoration: underline;
color: #ccc;
}We’ll make the text a little small, give it an underline so it looks clickable and drop the color back to a light gray so it doesn’t distract from the content.
Get Readmore.js
As I mentioned previously, Readmore.js is a small jQuery plugin. It is open-sourced under the MIT license so you are free to use in your apps including commercial apps.
Readmore recommends using Bower to download the code but since we’re using the minified version of the Map Tour, we can just download the minified version from the Readmore’s github page:
Readmore.js minified code available here
Just go to the link above and save the script into the app folder of the map tour code you downloaded.
Add the required JavaScript
Lastly, we’ll need to add a bit of JavaScript that will add the “read more” button and collapse the description every time the a new point is selected.
All of a story maps apps that have online builders provide a small set of events that developers can listen to so that they can easily make small feature enhancements without needing to understand the underlying source code. More information about these events can be found under the developer section of each github repo.
For this modification, we’ll be listening the “maptour-point-change-after” which fires immediately after a new point has be selected and all the content has be updated.
Add the following lines of JavaScript to the very bottom of the index.html page but just before the closing body tag:
This code does the following:
- Sets the path variable to the full url of the index.html
- Loads the dojo/topic event library (used for global event listening) and load the readmore.min.js file that we saved into the app folder.
- topic.subscribe starts listening to the “maptour-point-change-after” event and calls readmore plugin any time the event is fired.
Preview your app your app once more. You should now see the read more button appear at the bottom of your description:
If you’ve been working off a test server, it’s now time to move your code over to your production server and share your story with the public. If you haven’t already done it, I recommend filling in the open graph tags so your app is discoverable by Google and looks nice when shared as well as add Google Analytics so you know who is visiting your story.
