Skip to content

Widget

The sUNC Embeddable Widget (SEW) allows you to embed sUNC test results as interactive widgets into other webpages via an <iframe>. The widget is reusable and highly customiseable using it's postMessage API.

This widget is ideal for developers who want to display sUNC results on status websites, show their score off on an executor website, or to use it in forums.

Widget features

  • Load any sUNC test result into a sandboxed viewer widget.
  • Change the widget theme to match your website using a custom colour scheme.
  • Dynamically control the widget through JavaScript using the postMessage API.

Example

sUNC Widget Example

You may view this example preview here or look at the source code.

Usage

You can embed the widget using a standard <iframe> and control it using the postMessage API.

A minimum height of 610px is recommended, but not required.

Embedding the sUNC widget
<iframe id="sunc-widget" src="https://sunc.rubis.app/widget/" allowfullscreen></iframe>
Sending a message to load a scrap (test result)
<script>
  const iframe = document.getElementById("sunc-widget");

  iframe.contentWindow.postMessage({
    type: "sunc-widget:loadScrap",
    payload: {
      scrapId: "766F7uirM9D9ZlAF",
      key: "Hvj2XFk6nVJtJQQ9VtPoHoDpnxBDhesL"
    }
  }, "https://sunc.rubis.app");
</script>

Communicating with the widget may be done via the postMessage API, and message types are described here.

Optimisation Guide: A Persistent SEW

A minimum height of 610px is recommended, but not required.

If your site frequently uses the sUNC Embeddable Widget (SEW) - for example, to display many different results or support multiple themes (e.g., an executor comparison website) - then it is highly recommended that you keep a persistent <iframe> in the DOM rather than dynamically creating and destroying it. In fact, the SEW was designed around this principle and is easier to use this way.

Instead of doing something like this:

The bad practice of dynamically creating a new iframe each time
// do NOT do this!!
button.onclick = () => {
  const iframe = document.createElement("iframe")
  iframe.src = "https://sunc.rubis.app/widget/"
  document.body.appendChild(iframe)

  iframe.contentWindow.postMessage({ ... }, "https://sunc.rubis.app")
}

You should create the <iframe> once, keep it hidden by default (e.g., with Tailwind's hidden class or display: none in CSS), and simply show/hide or update it as needed:

Creating one persistent widget with the name of 'sunc-widget'
<iframe id="sunc-widget" class="hidden" src="https://sunc.rubis.app/widget/"></iframe>

Then use the postMessage API to load different results or change the theme:

Using the postMessage API to load a different result
iframe.contentWindow.postMessage({
  type: "sunc-widget:loadScrap",

  payload: {
    scrapId: "...",
    key: "..."
  }
}, "https://sunc.rubis.app");

Why is this better?

Overall, using a persistent <iframe> is better because of a few reasons:

  1. Even if the widget might be cached by the browser, it does not need to re-initialise the <iframe> every time.
  2. Performance is slightly improved by avoiding unnecessary DOM churn and repeated <iframe> creation.
  3. Your state is perserved in the widget, meaning you can set a custom theme once and it will persist across result reloads.
  4. If your site supports multiple themes (e.g., light/dark mode, seasonal themes like a halloween theme for example), then you can instantly update the widget using the postMessage API without waiting for the SEW to re-load, or having to maintain a separate state in your own code just to provide the SEW with your custom theme.