The Embedding API

Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.

IFRAME (manually embedding the map)

To embed a map in another web page, simply use an IFRAME, like this:

 <iframe src=url>(non-iframe text)</iframe>

where url is a standard map linking URL - see The Map URL API. For example:

 <iframe src="http://map.cam.ac.uk/Lucy+Cavendish+College"></iframe>

Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:

 <iframe src="http://map.cam.ac.uk/Lucy+Cavendish+College" style="width: 400px; height: 400px;"></iframe>

The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.

We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then the map will

• adjust if the institution moves (using  a bounding box or building reference leaves it showing the old geographical location)
• centre on the institution concerned 
• show a marker for just the institution concerned, not all of its neighbbours

The src link can include an annotation overlay or positioning fragment.

HTTPS

Note that if your page is served using HTTPS, you will also need to use https to retrieve the map, otherwise users will receive messages warning about mixed and unprotected content on the page:

 <iframe src="https://map.cam.ac.uk/Lucy+Cavendish+College"></iframe>

Firefox version 23 (and presumably later) actually blocks such content entirely if http is used in the iframe src when embedding in an https page.

If you can serve the same pages using either protocol, you can arrange for the map to serve using the same protocol as the page in which it is embedded by omitting the protocol, just starting with the two slashes, thus:

 <iframe src="//map.cam.ac.uk/Lucy+Cavendish+College"></iframe>

oEmbed (automatically recognising a map URL)

What is oEmbed?

oEmbed is a protocol which enables a content management system (such as Wordpress), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube) and replace it with HTML which presents the resource directly instead of the link to it.

In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.

Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. This differs between systems.

Basic information

Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the URL scheme and the API endpoint. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See the oEmbed specification if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.

For the University map, these two are:

• URL scheme: http://map.cam.ac.uk/*
• API endpoint: http://map.cam.ac.uk/oembed/

Providing these to a compliant CMS will then allow your authors to include URLs such as

 http://map.cam.ac.uk/Department+of+Geography

in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map. You can also include markers, overlaid annotation etc in these URLs.

Falcon

oEmbed functionality will be added to Falcon with the next round of enhancements, during Michaelmas Term.

Wordpress

You can add knowledge of University Map URLs to Wordpress in two ways:

• by installing a plugin, provided below.
• programatically, as a PHP function call in the file functions.php for the theme you are using

Quoting a map URL will then automatically include an <iframe> as above.

If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [embed] shortcode, quoting the size, like this:

 [embed width="400" height="300"]http://map.cam.ac.uk/Department+of+Geography[/embed]

Plugin

• Download the plugin from http://map.cam.ac.uk/oembed/ucammapoembed.zip
• If you have Wordpress installed on a server where the dashboard has permission to write to your files:
  • install it using Add New at the top of the Plugins page in the control panel;
  • identify the zip file when asked;
  • then activate the plugin.
• If you don't have dashboard access,
  • upload the zip file to the wp-content/plugins directory in your Wordpress installation;
  • unzip it on the server;
  • delete the zip file from the server;
  • go to the Plugins page on the Wordpress dashboard and activate the plugin.
• Alternatively, if you can't unzip on the server,
  • first unzip the zip file you downloaded, and then
  • upload the unzipped files (they are small).

(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).

PHP

The relevant Wordpress function is wp_oembed_add_provider.

Add it to your theme code like this:

 
  function ucammapoembed_handler() {
           wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');
  }
  add_action( 'init', 'ucammapoembed_handler' );