How to Use the Scroll Post Message Functionality

This document provides an overview and instructions for utilizing the scroll messaging feature integrated into the exported HTML. The feature enables communication of scroll progress from the embedded page to its parent window via post messages.

Overview

When the exported HTML content is embedded (e.g., in an iframe), the scroll messaging functionality sends notifications to the parent window. This is achieved through the updateScrollUI function defined in src/tools/html-generation/modules/navigationSystem.ts.

Message Types

Two types of messages are sent via window.parent.postMessage:

• scrollUpdate:
  Sent each time the scroll percentage is updated. The message payload contains the property:

• value: The current scroll percentage (rounded to the nearest integer).

• scrollComplete:
  Sent when the scroll percentage reaches or exceeds 100%. The payload ensures that the scroll is marked as complete with:

• value: Always 100.

How It Works

Inside the updateScrollUI function, after updating the scroll percentage in the DOM, the function: 1. Rounds the current scroll percentage. 2. Sends a message: js window.parent.postMessage({ type: 'scrollUpdate', value: rounded }, '*'); 3. If the rounded value is 100 or more, it sends an additional message: js if (rounded >= 100) { window.parent.postMessage({ type: 'scrollComplete', value: 100 }, '*'); }

Note: The target origin is set to '*' for simplicity. For enhanced security, it is recommended to specify the exact origin of the parent window.

How to Listen for Messages

On the parent page (the page embedding the exported HTML, e.g., in an iframe), add an event listener for messages:

window.addEventListener('message', (event) => {
  // Validate the origin if necessary:
  // if (event.origin !== "https://your-allowed-origin.com") return;

  if (event.data && typeof event.data === 'object') {
    switch (event.data.type) {
      case 'scrollUpdate':
        console.log('Scroll Update:', event.data.value, '%');
        // Handle scroll update (e.g., update UI elements, trigger animations)
        break;
      case 'scrollComplete':
        console.log('Scroll completed!');
        // Handle scroll completion event (e.g., show a completion message)
        break;
      default:
        break;
    }
  }
});

Best Practices

• Origin Check:
  For security reasons, replace '*' in postMessage with a specific target origin, and perform an origin check in the message handler.

• UI Updates:
  Use the scrollUpdate messages to drive user interface changes, such as progress bars or notifications that reflect the scrolling progress.

• Scroll Completion:
  The scrollComplete message can be used to trigger events once the user has scrolled through the entire content.

Conclusion

This scroll messaging feature enables seamless communication between the embedded exported HTML and its parent container. Integrate the provided listener code into your parent page to react to scroll updates and complete the interactive experience.

For additional details or modifications, please refer to the source code in src/tools/html-generation/modules/navigationSystem.ts.