Embedding


Maps are for sharing with all those with an interest in history, including your visitors and audience. You can embed Running Reality maps on your website, using a sharing platform, using a learning management system, or via social media.

Overview

Running Reality provides a wide range of options to share historical maps with your visitors and audience. The simplest approach is to share a map URL, but you can also configure how that URL will make the map look to tailor it to the specific needs you have. Deeper embedding options are also possible if your platform makes it possible. Using story map-style Running Reality projects can provide more structured narrative and in-map options like custom layers. Finally, if you use the app you can export standalone products like highly tailored HTML, images, or movies.

As always, when using the work of others, we ask that embedded content be provided with proper citation back to Running Reality so that Running Reality can provide the citation details for the data that went into the historical map you are using. See our data use policy for more details.

Integrations

Running Reality has tested integrations with common platforms to smooth the process for you. These are the primary tested platforms:

PlatformMethodInstructions
Esri StoryMap Embed any map URL as a StoryMap "embed" block. Instructions
Wordpress Embed any map URL in a "link" block. Instructions
Jupyter Add a historical map to a Jupyter Notebook as a static map or connected to notebook variables as an interactive map. Instructions
Blackboard Add the student-access URL (which includes an access key if sharing a Lesson Plan) to your Blackboard class resources page. Instructions
Google Classroom Add the student-access URL (which includes an access key if sharing a Lesson Plan)to the class materials using "Classwork" tab -> "Create" button -> "Material" menu item. Instructions
Schoology Add the student-access URL (which includes an access key if sharing a Lesson Plan) as a Schoology "link", by copy-pasting any Running Reality URL or iFrame. Instructions

Running Reality also provides the metadata needed by social media platforms to enable map sharing:

PlatformMethod
Facebook Share from the social media links or copy-paste any Running Reality URL.
Threads Share from the social media links or copy-paste any Running Reality URL.
Instagram Share a map image from the social media links or copy-paste any Running Reality URL.
YouTube Share from the social media links or copy-paste any Running Reality URL.
Twitter Share from the social media links or copy-paste any Running Reality URL.
Pinterest Share from a copy-paste of any Running Reality URL.

Parameters

If you want to hide certain parts of the interface, you can add parameters to the Running Reality URL. These can be helpful to remove distractions when creating a map specific for your embedding needs and audience. For a classroom presentation, you might want to remove certain features so that there is just the map onscreen. For an iFrame embedded map, you might want your readers to see a fixed map on a single fixed date to illustrate a specific written passage.

This is an example of how to use these parameters to construct your own specific URL:

And this is an example for embedding in an HTML iFrame:

For embedding a map, using an iFrame with URL parameters is the simplest way to get a historical map on your own web page. If you want more interactivity than an iFrame can provide, you might find that the standalone HTML approach below might be more appropriate. That approach enables fine-grained JavaScript interactivity and custom data layers.

The full set of parameters are:

ParameterEffect
07/08/1585 The date, either just the year or the month/day/year. Without it, the default is 1700AD.
36.30364,-78.47428 The latitude and longitude to 5 decimal places. Without it, the default is your visitor's current location.
zoom=7 The zoom level from 1 to 20. Without it, the default is a region-level view.
simple Removes most of user interface for a simple map, equivalent to nocontrols&nosidebar
student Removes ads in a link that you provide to students.
nocontrols Removes in-map controls such as the compass rose, zoom buttons, geolocation, and augmented reality.
nomenu Removes the "hamburger" menu in the timeline which removes access to projects, documentation, QR code generation, etc.
nosocials Removes the social media sharing buttons.
nosidebar Removes the search box and sidebar panel
notimeline Removes the timeline bar so the date can not be changed
nogeo Removes the geolocation button so that Running Reality can not ask for the visitor's precise GPS location.
nolabels Removes labels in the map and the map scale legend.
highlight=[id] Shows the Highlight with the given id in the sidebar.
lesson=[id] Shows the Lesson Plan with the given id in the sidebar.
lesson=[id]&key=[accesskey] A student access key that makes their web page synchronize to the matching step of a teacher's lesson plan.
research=[id] Shows the Research Project with the given id in the sidebar.
research=[id]&layer=[layername] A layer name from a research project to directly show only that layer in a map.

Note that parameters that are part of the URL query string (starting with a ? and separated by & characters) affect the user interface where parameters that are part of the URL hash (starting with a # and separated by commas) affect the display position in space and time. Sometime social media or sharing platforms could ignore or truncate the hash values.

OEmbed

Many websites, blogging platforms, social media, and "story map" sites where you may be creating content use the Open Embedding (OEmbed) standard to determine how best to show an embedded version of a linked website like Running Reality. Running Reality includes OEmbed metadata in all map pages so that you can simply paste any Running Realty map URL into the platform and it will handle the embedding details for you. Sites that use OEmbed include Esri StoryMaps and Wordpress blogs.

The technical details are that Running Reality maintains an OEmbed "endpoint" at https://www.runningreality.org/data/oembed that will provide embedding details in the JSON format. The details will include an HTML snippet that proposes using an iFrame tag wrapping the Running Reality URL. The URL will honor all configuration parameters listed above so that you can embed a map with no sidebar or timeline if you like.

Standalone HTML

From the world menu of the app version of Running Reality, there is an option to export a world to a standalone HTML page. There are many configuration options to include your raw layer data within that HTML page, including any GeoJSON layers or CSV, XLS, or SQL tabular data. This produces an HTML page that you can then host from your own web server, such as a university server. The HTML includes documentation on how you can directly modify the HTML to add or remove layers or change styles. The HTML gives you direct JavaScript access to the instance of OpenLayers that Running Reality uses for rendering so that you can directly control OpenLayers with your own custom Javascript. This gives you maximum flexibility to host a map of your own.

Standalone Images and Movies

From the share menu of the app version of Running Reality, you can embed an image or movie into your own work. You can copy-paste an image of the map directly to your computer's clipboard. You can create a JPEG image of a point in time or create an MP4 movie or GIF animation of a span of time.

Note that the web map uses a Mercator projection but the app uses an equi-rectangular projection. In most cases, you might not notice a difference, but at street level, Mercator keeps right angles looking correct and equi-rectangular can show some distortion. Eventually, we will migrate the app to Mercator.

Sharing Highlights, Lessons, and Research

Running Reality has special projects that add onto the regular historical map and these also have additional sharing and embedding capabilities. These special projects -- highlights, lesson plans, and research projects -- can include extra features for the sidebar or in-map layers and markers. Highlights are platform-wide areas where Running Reality has particularly detailed historical data to highlight for visitors. Lesson Plans are a premium feature to allow teachers to step classroom students through a guided history lesson. Research Projects are a premium feature for research professionals to share data products including in-map layers.

When sharing or embedding one of these projects, including the URL parameter will enable those special features. Extra metadata is provided within the page HTML header to the embedding website such as the project title, author, text description, and thumbnail image. Social media sites and OEmbed sites pick up this data to produce their sharing "cards," previews, or thumbnails.

From the projects page you can access a range of sharing and embedding links if you have either read-only or edit access to the project. These sharing links simplify the process of sharing. You can also generate QR Codes for the project from here. However, you can also share the main URL for a project just by viewing the project, such as this highlight https://www.runningreality.org/?highlight=34

Feedback


If you can not find an answer here, please feel free to ask us for help. Send us an email if you would like us to get back to you with a response:

Send the Running Reality team an email: