Widgets

PERSCOM.io offers powerful widgets that allow the integration of your organizational data into another website for display. Each widget is a snippet of HTML that can be injected into your website.

​

Demo

If you’d like to try the widgets out before using them on your website, you can preview every widget from within your own PERSCOM dashboard. Visit the Widgets section under Integrations section for more information.

​

Installation

To start using the PERSCOM widget, copy and paste the following HTML snippet into your website. Make sure to replace APIKEY with your own API key. Replace the widget ID with ID you’d like to display.

<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>

​

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:

​

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

<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

The information below is for users who have experience in software development and provide option for advanced usage of the widgets.

​

Alpine.js

Alpine is a rugged, minimal tool for composing behavior directly in your markup. Think of it like jQuery for the modern web. Plop in a script tag and get going. The widgets can be injected into the page using a dynamic approach that allows for logic to be run before the widget is rendered.

In this example, we can check if dark mode is enabled on the parent web page. If it is, we render the widget with data-dark='true' enabled.

<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>

​

Navigation

You may programmatically force the widget to navigate to a new URL by dispatching a browser based event. This is how we, for example, open a form when the button is clicked. The iframe that renders the widget listens for events and will force the iframe to navigate using the information provided in the event payload. See the example below.

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}
  }, '*')
});