/
Widgets User Guide

Widgets User Guide

Creating Widgets in the Gateway

This guide explains how to create a custom widget that displays Datasets & BioSamples, Data Uses / Research Projects, Analysis Scripts & Software and Collections uses on your own website. By the end, you will have generated embed code that you can copy directly into your site.

1. Logging in and Navigating to Widgets

  1. Log into the Health Data Research Gateway as a user with Team Administrator or Developer permissions*.

  2. Navigate to your Team page.

  3. In the left-hand menu, select Integrations.

  4. Click on Widgets.

You will now see an overview of all widgets created for your team, as well as the option to create new ones.

image-20251127-112557.png

*You will not see the ‘Integrations’ option if you do not have Team Administrator or Developer permissions. To gain either or both permissions, you can have your permissions changed by one of your existing Team Administrators or Developers (see guidance on Managing your Team on the Gateway).

2. Creating a New Widget

  1. Select Create new widget.

  2. A dialog box will appear showing a range of templates.

  3. Choose a template or select Start from scratch.

  4. Click Confirm to proceed.

image-20251202-164239.png

3. Configuring Your Widget

3.1 Select Data Custodians and Determine Content Types and Content

Your team will be listed as the default Selected Custodian. You may choose to add additional Data Custodians (multiple can be selected). Doing so expands the pool of content that can be included in your widget.

Once Data Custodians are selected, choose the content types you would like to display:

  • Datasets & BioSamples

  • Data Uses / Research Projects

  • Analysis Scripts & Software

  • Collections

Ticking a content type allows you to select specific items from the chosen Data Custodians, or ‘Select all’ to add all content of that type from the chosen Data Custodians.

image-20251127-112829.png

 

3.2 Add Widget Functionality

At present, the following optional features are available:

  • Search Bar – Adds a search box to your widget, allowing users to search by the titles of the selected items.

  • Link to Cohort Discovery – Provides a direct link to Cohort Discovery from the widget.

Tick the checkboxes for features you want to enable.

image-20251127-112902.png

 

3.3 List the Permitted Domains

Enter the domain(s) where the widget will be embedded.


For example:

https://www.mytestwebsite.com

Widgets will only function on the domains listed here.

image-20251127-112931.png

Note: the URL must contain https:// to pass validation.

3.4 Define the Widget Size

Define the size of the widget as it will appear on your website. Adjust the height and width to suit your page layout.

image-20251127-112953.png

Unit options include px (pixels), % (percentage) and rem (root em). Percentage measures are in relation to the parent container where you embed the widget. Rem is a measure in relation to the root element, more information on which can be found here: Rem in CSS: Understanding and Using rem Units — SitePoint.

3.5 Assign a Widget Name

Provide a clear, descriptive name for your widget. This name will be used to identify it within the your Team management page (Widgets User Guide | widget_management_view ) .

image-20251127-113013.png

 

4. Save and Generate Embed Code

Once all fields are complete, save your widget. The Gateway will generate embed code (usually an HTML snippet) that you can drop directly into your website.

image-20251127-113102.png

5. Updating Widgets

With the current set up. Any changes made to your widgets, the changes will be brought in almost automatically without the need to regenerate any code. There is some caching involved, the cache will last between 3-5 minutes.

Troubleshooting Widget Issues

This page outlines common problems you may encounter when embedding Gateway widgets into your website, along with steps to help you resolve them. Many issues relate to modern browser security controls—particularly Content Security Policy (CSP) settings—so this guide includes a brief explanation and an example CSP directive.

1. Content Security Policy (CSP) Issues

What is CSP?

Content Security Policy (CSP) is a browser security mechanism that controls which external domains your website is allowed to load scripts, iframes, and other resources from. If your site has a restrictive CSP, it may block your Gateway widget from loading unless the widget’s domain is explicitly permitted.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy

Example CSP Directive

If you are embedding a Gateway widget, you may need to allow the widget’s domain in your CSP.
For example:

frame-src 'self' www.healthdatagateway.org;

This directive allows your site to load iframes from the Gateway while still blocking unauthorised external framing sources.

Common CSP-Related Symptoms

  • The widget iframe appears blank.

  • You see console errors such as "Refused to load the script because it violates the site's Content Security Policy".

  • The widget loads partially, but interactive features (e.g., search) do not work.

  • Browser blocks external scripts, fonts, or API calls required by the widget.

How to Resolve CSP Problems

  1. Review the domains the widget loads resources from (these are provided in the widget’s embed code or documentation).

  2. Add the relevant domains to your CSP under directives such as:

    • frame-src (or child-src in older CSP versions)

    • script-src

    • connect-src

    • style-src

  3. Apply your updated CSP headers and redeploy your site if necessary.

  4. Clear your browser cache and reload the page to test whether the widget now loads correctly.

Important: Only allow domains you fully trust.

2. Widget Not Displaying on Your Website

If nothing appears where the widget should be:

  • Confirm that your website’s domain is listed under Permitted Domains in the widget configuration. (Widgets User Guide | 3.3 List the Permitted Domains )

    • NOTE: If you are testing the widget on a development version of your website, make sure the domain for the development site is listed as a permitted domain - e.g. if your website is https://our.website.org and your development or test website is https://dev.our.website.org, make sure both URLs are listed in Permitted Domains

  • Ensure the full embed code—including any <script> tags—has been copied correctly.

  • Check for browser extensions (such as adblockers) that may be blocking external content.

3. Widget Does Not Display the Expected Data

If items are missing or not loading as expected:

  • Verify that the correct Data Custodians and content types were selected when creating the widget. (Widgets User Guide | 3. Configuring Your Widget )

  • Ensure the selected items have not been archived or restricted since the widget was created.

4. Search Bar Not Functioning

If the search bar is visible but not returning results:

  • Confirm that the Search Bar feature was enabled during widget creation. (Widgets User Guide | 3.2 Add Widget Functionality )

  • Check for CSP or script-loading errors in your browser’s developer console.

  • Ensure the selected Datasets & BioSamples, Collections, Analysis Scripts & Software, or Data Uses uses have valid titles or metadata for search.

5. Layout or Sizing Issues

If the widget appears distorted, clipped, or incorrectly sized:

  • Check the Widget Size settings in the configuration panel. (Widgets User Guide | 3.4 Define the Widget Size )

  • Review your site’s CSS to ensure the widget container allows the specified dimensions.

  • If using a responsive layout, confirm that the parent container supports dynamic resizing.

6. Further Assistance

If you continue to experience problems, consider: