Custom Events

Custom events enable Qrvey Software Developers to handle custom scenarios. This article describes several custom events that can be triggered by Qrvey widgets. The host application can be programmed to listen to these events and then perform its own custom tasks. The Dashboard widgets support the following custom events:

• Dashboard Loaded Event
• Items Loaded Event

Dashboard Loaded Event

The Dashboard Loaded event qvDSHPageLoaded is emitted when the dashboard is loaded (and the “loading” spinner is no longer displayed) in the Dashboard widgets.

const event = new CustomEvent('qvDSHPageLoaded');

document.addEventListener(“qvDSHPageLoaded”, () => { 
    // Do Something
});

document.dispatchEvent(event);

Items Loaded Event

The Items Loaded event qvDSHItemsLoaded is emitted when all charts in the viewable area have rendered (and their corresponding “loading” spinners are no longer displayed) in the Dashboard widgets.

const event = new CustomEvent('qvDSHItemsLoaded');

document.addEventListener(“qvDSHItemsLoaded”, () => { 
    // Do Something
});

document.dispatchEvent(event);

---

JWT Expiration Event: qvTokenExpired

The qvTokenExpired event is dispatched by embedded Qrvey widgets whenever the system detects that the authentication token (qvToken) has expired (HTTP status 401).

When It Occurs: Triggered automatically by the widget when a qvToken is invalid or expired.

What It Does: The widget dispatches a global event in the host application called qvTokenExpired. The event payload contains a detail object with the source widget that triggered the event:

{
  "trigger": "Dashboard View Widget"
}

Purpose: This event enables host applications embedding Qrvey widgets to react to expired tokens in a controlled way.

• Implementers are free to decide how to handle it.
• Common approaches include refreshing the token silently or prompting the user to confirm they are still active.

Typical Use Cases:

• Refreshing the token by requesting a new qvToken from the backend.
• Prompting the user with a modal (“Your session expired, click continue to refresh”).
• Notifying the user that their session has expired for a given widget (dashboard, report, etc.).

Example Usage:

document.addEventListener('qvTokenExpired', (event) => {
  console.log('Event captured:', event.detail);

  if (event.detail.trigger === 'Dashboard View Widget') {
    // Example: Show a custom modal to the user
    showSessionExpiredModal(() => {
      // Callback: regenerate qvToken and reinitialize the widget
      regenerateTokenAndReloadWidget();
    });
  }
});