Widgets

Embed PERSCOM data displays on any website.

Widgets display your PERSCOM organizational data on external websites. Each widget is an HTML snippet that renders a visual component such as a roster, calendar, or awards list.

Preview Widgets

Preview widgets before adding them to your website:

1. In the sidebar, select Integrations > Widgets.
2. Select Choose Widget to switch between available widgets.
3. Use Get Widget Code to generate the embed code.

Installation

Copy and paste the HTML snippet below into your website. Replace APIKEY with your API key and set the data-widget attribute to the widget ID you want to display.

Roster

<div id="perscom_widget_wrapper">
    <script
        id="perscom_widget"
        data-apikey="APIKEY"
        data-widget="roster"
        src="https://widget.perscom.io/widget.js"
        type="text/javascript"
    ></script>
</div>

To avoid leaking sensitive data, it is recommended to create an API key with only view permissions. Your API key will be publicly accessible.

Available Widgets

The following widgets are currently available. Each widget is identified by a widget ID passed to the data-widget attribute.

1. Roster data-widget='roster'
2. Awards data-widget='awards'
3. Calendar data-widget='calendar'
4. Forms data-widget='forms'
5. Positions data-widget='positions'
6. Qualifications data-widget='qualifications'
7. Specialties data-widget='specialties'
8. Ranks data-widget='ranks'

Options

Widgets can be customized by providing additional data attributes. Below are the list of available configurable options:

Option	Type	Default	Description
data-dark	bool	false	Enables dark mode support for the widget.
data-resource	string		Returns a specific resource for the widget using the provided identifier.

Specific Resources

A few widgets support the ability to provide an identifier to retrieve a specific resource. For example, you may want to display a specific form in your website. By providing the data-resource attribute, you can retrieve a specific form.

Supported Widgets: Forms

Ranks

<div id="perscom_widget_wrapper">
    <script
        id="perscom_widget"
        data-apikey="APIKEY"
        data-widget="forms"
        data-resource="1"
        src="https://widget.perscom.io/widget.js"
        type="text/javascript"
    ></script>
</div>

Advanced Usage

The following examples demonstrate advanced widget integration techniques for developers.

Alpine.js Integration

Alpine.js provides a lightweight way to add dynamic behavior to your HTML. Use Alpine to conditionally configure widgets based on your page state.

This example detects dark mode on the parent page and enables dark mode on the widget:

<div x-data="{
  init() {
    const script = document.createElement('script');
    script.id = 'perscom_widget';
    script.src = 'https://widget.perscom.io/widget.js';
    script.type = 'text/javascript';
    script.setAttribute('data-apikey', '{{ $this->apiKey }}');
    script.setAttribute('data-widget', '{{ $this->widget }}');

    if (document.documentElement.classList.contains('dark')) {
      script.setAttribute('data-dark', 'true');
    }

    document.getElementById('perscom_widget_wrapper')?.appendChild(script);
  }
}" x-init="init">
  <div id="perscom_widget_wrapper"></div>
</div>

Programmatic Navigation

Navigate the widget to a different view by dispatching a browser event. The widget iframe listens for these events and updates its content accordingly.

document.addEventListener("DOMContentLoaded", () => {
  window.parent.postMessage({
    type: 'widget:navigate',
    path: 'roster' // The widget ID. This will translate to the iframe URL being: https://api.perscom.io/v2/widgets/{path}
  }, '*')
});