Next-Generation Clustered Heat Maps (NG-CHMs) can be embedded in an HTML page as either full-size maps or expandable icons.

This page describes the new implementation of embeddable maps released in viewer release 2.20.0. The older style of embedding maps is deprecated (the article describing the old implementation is available for reference).

What are Embedded Next-Generation Clustered Heat Maps?

NG-CHMs can be embedded in an HTML page, either as open, full-scale maps or as thumbnail images that can be expanded into NG-CHMs by the reader.

Figure 1 shows the latter case, also known as an ‘expandable’ NG-CHM. When the user hovers over the thumbnail, an Expand Map graphic is superimposed on the thumbnail image. Clicking on the expand map graphic will load the NG-CHM into the browser, expand the thumbnail into a large, interactive NG-CHM that the user can explore as they would any other NG-CHM. Clicking the Collapse Map button on the top-left will hide the NG-CHM and redisplay the thumbnail.

The author of the web page decides where to include the thumbnail/heatmap, the image to use for the thumbnail, and the size of the thumbnail. The size and position of the NG-CHM can be tailored to the page using CSS styling.

Security Restrictions

Web browsers prevent an NG-CHM located on the user’s local drive from being embedded. The NG-CHM must be on a web server. If the domains of your web page and the NG-CHM server differ, the NG-CHM server must allow download of the NG-CHM via CORS.

What you need

1. One or more standalone NG-CHMs. The interactive web builder, the Galaxy NG-CHM builder, and the NG-CHM package for R can all directly generate a standalone NG-CHM. Alternatively, you can save a copy of any NG-CHM by selecting Save Heat Map Changes from the hamburger menu, perhaps after changing various display parameters (such as the color scheme, etc.).

2. Optionally, a copy of ngchmEmbed-min.js, at least version 2.20.0. You can also include it directly from the previous link.

3. Optionally, a copy of ngchmWidget-min.js, at least version 2.20.0. By default it is expected to reside in the same directory/folder as the HTML page, but with a little extra effort it can be loaded from anywhere (including directly from the previous link).

4. Optionally, but recommended, a thumbnail image for the NG-CHM. If not provided, a default thumbnail will be used, which probably does not look similar to your NG-CHM.

Basic Embedding

This section describes the minimum steps required to embed an NG-CHM. It requires that the HTML page have a simple structure and that the NG-CHM, the thumbnail, and ngchmWidget-min.js all reside in the same directory/folder as the HTML page. Also, the NG-CHM file should have extension .ngchm and the thumbnail’s file is the same with .ngchm replaced by .png.

1. Include ngchmEmbed-min.js in the page header:

   <script type='text/Javascript' src='ngchmEmbed-min.js'></script>
   

2. Create an identifiable DIV element in the page. The easiest way to make the DIV identifiable is to give it an id, e.g. “NGCHM”:

   <DIV id='NGCHM'></DIV>
   

3. After the DIV element has been defined, call embedNGCHM:

   <script type='text/Javascript'>
   embedNGCHM('#NGCHM', 'fileName', 'NGCHM-file-name.ngchm')
   </script>
   

The function takes three mandatory parameters and one optional parameter:

1. A DOM element, selector, or id that specifies the DIV element in which to insert the embedded NG-CHM.

2. The type of the NGCHM source: options are fileName, url, blob, and base64.

3. The NGCHM source specification.

4. An optional structure for passing additional options.

An HTML template containing these elements is available for download.

Including ngchmWidget-min.js from a different location

When an embeddded NG-CHM is expanded, it must include ngchmWidget-min.js from a known location, which by default is the same directory/folder as the HTML page. To specify another location, use the widgetPath option:

<script type='text/Javascript'>
embedNGCHM('#NGCHM', 'fileName', 'NGCHM-file-name.ngchm', {
    widgetPath: 'ngchmWidget-min.js'
})
</script>

Including custom linkouts and plugins

Custom linkouts and plugins can be included in the embedded map using the customJS option:

<script type='text/Javascript'>
embedNGCHM('#NGCHM', 'fileName', 'NGCHM-file-name.ngchm', {
    customJS: 'custom-plugins.js'
})
</script>

Controlling the appearance of the NG-CHM

The default appearance of the expanded NG-CHM is fairly basic. You can modify its appearance by specifying CSS styling options.

The style option specifies the CSS style that will be used for the interactive NG-CHM.

This page uses a style option similar to the following:

<script type='text/Javascript'>
embedNGCHM('#NGCHM', 'fileName', 'NGCHM-file-name.ngchm', {
    expandable: true,
    style: 'position: fixed; top: 0; left: 0; height:100vh; width: 100vw; padding: 0.5em; background-color: white;'
})
</script>

Specifying an expandable map

By default, embedded maps are displayed as an interactive NG-CHM. Alternatively, the embedded map can be initially represented by a thumbnail image that the user can click on to expand it into an interactive NG-CHM (as in Figure 1):

<script type='text/Javascript'>
embedNGCHM('#NGCHM', 'fileName', 'NGCHM-file-name.ngchm', {
    expandable: true
})
</script>

Specifying the thumbnail URL

For expandable maps, you can specify a URL for the thumbnail image to use for the collapsed NG-CHM by including the “thumbnail” property in the options (fourth) parameter:

<script type='text/Javascript'>
embedNGCHM('#NGCHM', 'fileName', 'NGCHM-file-name.ngchm', {
    expandable: true,
    thumbnail: 'some-other-path.png'
})
</script>

Specifying the thumbnail style

The style of the thumbnail image defaults to 150px by 150px with no border. A different style can be specified using the “thumbnailStyle” option:

<script type='text/Javascript'>
embedNGCHM('#NGCHM', 'fileName', 'NGCHM-file-name.ngchm', {
    expandable: true,
    thumbnailStyle: 'height: 200px; width: 200px;'
})
</script>

Embedding multiple NG-CHMs in a page

You can include multiple embedded NG-CHMs in a page by including multiple divs in the document and calling embedNGCHM for each.

Instead of passing the same optional parameters to each embedNGCHM call, you can modify the default parameters by calling embedNGCHM.setParameters:

<script type='text/Javascript'>
embedNGCHM.setParameters({ widgetPath: 'url-for-ngchm-Widget-min.js' });
</script>

Subsequent calls of embedNGCHM will use the new parameters by default. Parameters specified in the fourth parameter to embedNGCHM will take priority over the default parameters.