> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perscom.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#available-widgets) you want to display.

<CodeGroup>
  ```html Roster {4-5} theme={"system"}
  <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>
  ```

  ```html Awards {4-5} theme={"system"}
  <div id="perscom_widget_wrapper">
      <script
          id="perscom_widget"
          data-apikey="APIKEY"
          data-widget="awards"
          src="https://widget.perscom.io/widget.js"
          type="text/javascript"
      ></script>
  </div>
  ```

  ```html Calendar {4-5} theme={"system"}
  <div id="perscom_widget_wrapper">
      <script
          id="perscom_widget"
          data-apikey="APIKEY"
          data-widget="calendar"
          src="https://widget.perscom.io/widget.js"
          type="text/javascript"
      ></script>
  </div>
  ```

  ```html Forms {4-5} theme={"system"}
  <div id="perscom_widget_wrapper">
      <script
          id="perscom_widget"
          data-apikey="APIKEY"
          data-widget="forms"
          src="https://widget.perscom.io/widget.js"
          type="text/javascript"
      ></script>
  </div>
  ```

  ```html Positions {4-5} theme={"system"}
  <div id="perscom_widget_wrapper">
      <script
          id="perscom_widget"
          data-apikey="APIKEY"
          data-widget="positions"
          src="https://widget.perscom.io/widget.js"
          type="text/javascript"
      ></script>
  </div>
  ```

  ```html Qualifications {4-5} theme={"system"}
  <div id="perscom_widget_wrapper">
      <script
          id="perscom_widget"
          data-apikey="APIKEY"
          data-widget="qualifications"
          src="https://widget.perscom.io/widget.js"
          type="text/javascript"
      ></script>
  </div>
  ```

  ```html Specialties {4-5} theme={"system"}
  <div id="perscom_widget_wrapper">
      <script
          id="perscom_widget"
          data-apikey="APIKEY"
          data-widget="specialties"
          src="https://widget.perscom.io/widget.js"
          type="text/javascript"
      ></script>
  </div>
  ```

  ```html Ranks {4-5} theme={"system"}
  <div id="perscom_widget_wrapper">
      <script
          id="perscom_widget"
          data-apikey="APIKEY"
          data-widget="ranks"
          src="https://widget.perscom.io/widget.js"
          type="text/javascript"
      ></script>
  </div>
  ```
</CodeGroup>

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

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

```html Ranks {6} theme={"system"}
<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](https://alpinejs.dev/) 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:

```js theme={"system"}
<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.

```js theme={"system"}
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}
  }, '*')
});
```