Embedding Guide

roadworks.org v6 Embedding Guide

(V 1.2    10/10/2012)

1. Prerequisites

In order to embed roadworks.org into your website you will need to provide the following information to ELGIN by emailing support@elgin.org.uk

  • The web domain of the host page(s) e.g. http://www.kent.gov.uk. We require this to set security permissions without which the embedding will not work. (If you use a different domain for testing purposes we will also need to know that domain.)
  • The URL(s) of the host page(s). This information can be provided after the page is made live.
  • Technical contact details for support and notification of technical changes.
  • Business contact for notification of new functions.

2. Examples

Examples of embedded implementations of roadworks.org can be found here: http://roadworks.thecharles.co.uk Please feel free to look at the page source to see real examples of how to embed roadworks.org.

3. How to embed roadworks.org

Embedding is very simple and fundamentally consists of placing a div on the page with a specific ID and class:

The div
<div id="erwMap" class="ElginRoadworksWidget"></div>
The roadworks.org loader
<script type="text/javascript" src="//portal.roadworks.org/js/mylibs/Elgin.loader.js"></script>
Passing the required parameters to the roadworks.org loader
<script type="text/javascript">
    Elgin.loader.load({
        swlat: 51.51054, 
        swlng: -0.11423, 
        nelat: 51.51499, 
        nelng: -0.09957, 
        embedded: true, 
        infoHeader: '<img class="float-right" src="\/img\/chickenRoadworks.jpg" alt="No wonder I had so much trouble crossing the road.">' + '<p class="clear-both">Hello world! This is my own, my very own version of the embedded roadworks.org application. Don\'t you just love it!<\/p>'+ '<p>This is the full screen way of embedding to see other ways click <a href="/index.cfm">here<\/a><\/p>', 
        channel: 'demoEmbed', 
        positionCookie: false 
    }); 
</script>

Please note that the script should be run once the page has been loaded there are two ways to do this:

  1. Place the script tag at the end of the page just before the closing body tag. (This is the preferred way to do it however if your CMS restricts your access to specific parts of the page then you can use option 2.)
  2. Use the parameter delayedLoad to cause the loader to wait until the page is loaded before running.

4. JavaScript

roadworks.org will only work if JavaScript is enabled so we also recommend a noscript tag to inform users with JavaScript turned off that they need to turn it on or use a browser that is JavaScript capable. Here is an example noscript tag:

<noscript>
    <div style="margin:20px">
        <h3>roadworks.org</h3>
        For roadworks.org to function properly JavaScript must be enabled in your browser
        <br><br>
        For guidance on how to enable JavaScript this site may be helpful: <a href="http://enable-javascript.com/">http://enable-javascript.com/</a>
    </div>
</noscript>

5. The Div

The Div is where the roadworks.org application is loaded. It is up to you to determine the size of the div and how it sits within the rest of your page content and how it is resized when the browser window is resized. However we would recommend you give it the maximum size you can as the application tends to be easier to use with a larger window.

Please refer to the sample sites in section 2 for examples of how to embed roadworks.org.

6. Setting Parameters

The loader parameters must be supplied within a JavaScript object contained in curly brackets and each option separated by a comma (with no comma after the last element) for example:

{
    swlat: 51.51054,
    swlng: -0.11423,
    nelat: 51.51499,
    nelng: -0.09957,
    embedded: true,
    infoHeader: '<img class="float-right" src="\/img\/chickenRoadworks.jpg" alt="No wonder I had so much trouble crossing the road.">' +
'<p class="clear-both">Hello world! This is my own, my very own version of the embedded roadworks.org application. Don\'t you just love it!<\/p>'+
'<p>This is the full screen way of embedding to see other ways click <a href="/index.cfm">here<\/a><\/p>',
    channel: 'demoEmbed',
    positionCookie: false,
    newsWidget: { org_ref: 1234 }
}

7.     List of Parameters

The following parameters are supported. Additional parameters will be introduced in the future:

Mandatory parameters
7.1. Channel
channel

You will need a Channel ID supplied by ELGIN for the embedding to work. See section 1 above.

7.2. Embedded
embedded

This must be set to true.

Optional parameters
7.3. Set map area – longitude / latitude method
swlat   south west latitude
swlng   south west longitude
nelat   north east latitude
nelng   north east longitude

N.B. all 4 parameters must be supplied

7.4. Set map area – British National Grid method
swe       south west easting
swn       south west northing
nee       north east easting
nen       north east northing

N.B. all 4 params must be supplied together

7.5.       Set map centre point/zoom – longitude / latitude method
lat       latitude
lng       longitude
z         zoom

Zoom must be an integer between 5 and 21 and is optional.
N.B. lat and lng must both be supplied

7.6.       Set map centre point/zoom – British National Grid method
e                      easting
n                      northing
z                      zoom

Zoom must be and integer between 5 and 21 and is optional.
N.B. e and n must both be supplied together

7.7.       Set info panel content
infoHeader    Formatted html string

This can be used to display custom content in the header “Info panel” which is displayed by default in the right-hand map control. It can be used to display your organisation brand and any short message. Any valid snippet of HTML including images is permitted. It must be complete with closing tags and should be HTML5 compliant. Also as the string is a JavaScript string any special characters must be escaped with a .

7.8.       Position Cookie
positionCookie            true or false

Defaults to true if not set i.e. the position cookie will be used.

The position cookie is used to remember the last location of the user on the map when the user returns to the page after closing their browser. It expires after 24 hours. When testing the embed implementation it can be useful to set it to false to ensure that map centre point parameters are behaving correctly. We recommend that it is set to true in most cases.

7.9.       Delayed Load
delayedLoad          true or false

Defaults to false if not set.

This is used to delay the loader running until the document object model (DOM) is fully loaded. This is not required if the call to the loader is place at the end of the HTML page just before the closing body tag.

7.10.       Callback
callback      the name of a JavaScript function to call

This is a JavaScript call-back that allows you to wait for jQuery to be loaded by the Elgin loader and then use it. You can use this to let you use jQuery functions – for example: to resize the map div when the page is loading or when the user resizes their window (this example uses this method: http://roadworks.thecharles.co.uk/wrapped/).

7.11. News Widget
newsWidget    the name of a JavaScript function to call

This function allows users to display breaking news items, entered via the Communications Management App. Enter the org_ref which can be found here for Local Authorities.  The news widget will update automatically without requiring a page refresh when you add a new item in the Communications Management App.

Please note, the news widget is designed for maps bigger than 1024 pixels in width.

8. Common problems

8.1.       The map is not appearing
  • Make sure you have a div with the id of erwMap and class of ElginRoadworksWidget.
  • Ensure you have correctly called the Elgin.loader.js file from our server with the correct url:
    portal.roadworks.org/js/mylibs/Elgin.loader.js.
  • Make sure the code to call the Elgin.loader is at the end of the page or use the delayedLoad parameter.
8.2. I have a div and the loader is loading after the document is built – but the map still doesn’t appear.
  • Ensure the div has a height and a width in your CSS. The map cannot be displayed in a div that has no height or width.
8.4. The map is appearing but it appears differently in Internet Explorer than Chrome or Firefox.
  • This can happen when Internet Explorer renders the page using quirks mode instead of standards mode. This can be caused by malformed html or by incorrect meta tags.
  • Make sure your document is a valid html 4 or 5 document you can validate your html using http://validator.w3.org/
  • We would suggest the following meta tag
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">

    This ensures that the page is rendered in IE using the latest available engine for the browser you are using.

  • Be aware that only Internet Explorer version 9 and above support corner roundness using CSS and so the corners will appear square in versions 6-8
8.5. I have put in an parameter but it is not working
  • These options are JavaScript variables. Case is important, so ensure the case of the variables is as shown in this guide.
  • Certain parameters must be supplied as a group. For example with a bounding box you must supply all four parameters. And with a point and zoom you must supply all three parameters.
8.6. It’s still not working
  • Feel free to contact us. Contact details are shown on the last page.
  • Please give us the URL of your development page (on a server we can access) so we can investigate the problem.

8.     FURTHER INFORMATION

General enquiries about embedding roadworks.org:
support@elgin.org.uk
020 7127 6955 (switchboard)

ELGIN
John Carpenter House
John Carpenter Street
London
EC4Y 0AN
www.elgin.org.uk