Integrate Pathway Progress API In Module Pages (No Auth)

by ADMIN 57 views

Integrating the Pathway Progress API into module pages without authentication is an exciting step towards enhancing user experience. This article guides you through the process, ensuring a smooth implementation while adhering to SEO best practices. Let's dive in, guys!

Context and Scope

Before we get our hands dirty with the code, it's essential to understand the context of this integration. The pathway detail now features a localStorage-based progress UI, coupled with a global API: window.hhUpdatePathwayProgress(started, completed). This API is the backbone of our progress-tracking mechanism. The goal is to create a placeholder UX for v0.2, where module pages will have a simple way to mark a module as started or completed. This functionality will call the API when it's available.

The scope of this project primarily includes template integration within the module-page.html file. Specifically, we're focusing on the detail mode. Here’s what we aim to achieve:

  1. Client-Side Block: Add a small, client-side block that detects the presence of window.hhUpdatePathwayProgress. This block will be responsible for exposing:
    • A non-intrusive “Mark as started” link/button, triggering hhUpdatePathwayProgress(1, 0).
    • A “Mark complete” link/button, triggering hhUpdatePathwayProgress(1, 1).
    • Optionally, if document.referrer matches /learn/pathways/…, a “Back to pathway” link will be displayed. This makes navigation seamless for users.
  2. Server-Side Guard: Ensure that the code within <script> tags runs only after DOMContentLoaded. This prevents any premature execution and potential errors. We must also avoid referencing window in HubL to maintain server-side integrity.
  3. Maintain SEO Structure: It’s crucial to preserve the existing SEO structure. This means keeping a single H1 tag and not altering the list rendering. SEO is king, after all!

Styling and Documentation

Styling is another aspect we need to consider. The aim is to reuse existing button styles wherever possible. This keeps the design consistent and reduces the overall footprint. Accessibility is paramount; therefore, we must ensure that the buttons are usable and include appropriate aria-labels.

Documentation plays a crucial role in the longevity and maintainability of this feature. We need to update docs/content-sync.md (or create a short note in docs/README.md) to describe the placeholder progress behavior. This documentation should also guide authors on how to test the functionality effectively. Clear documentation ensures everyone is on the same page and can contribute confidently.

File Paths

Knowing the exact file paths is crucial for implementation. Here are the key files we'll be working with:

  • clean-x-hedgehog-templates/learn/module-page.html: This is where the primary template integration will occur.
  • docs/README.md (or docs/content-sync.md): This is where we'll document the changes and the new placeholder progress behavior.

Acceptance Criteria

To ensure our integration is successful, we need clear acceptance criteria. These criteria act as a checklist, verifying that we've met all the requirements.

  1. Functional Buttons: On a module detail page, two buttons (“Mark as started” and “Mark complete”) should appear. These buttons must correctly call the global progress API without any errors, if the API is present. If the API is not present, the buttons should silently do nothing (no-op).
  2. SEO Compliance: The integration must not introduce any changes to the SEO structure. We need to maintain a single H1 tag on the page.
  3. Responsiveness: The design should be responsive and work well on mobile devices. Mobile-first, always!
  4. Server-Side Safety: The code should avoid using window on the server-side. This prevents errors on pages, regardless of whether the pathway script is loaded.

Verification Steps

To verify that our integration works as expected, we'll perform the following steps:

  1. Progress Update Test: Open a module via /learn/<module-slug>. Click the “Mark complete” button. Then, navigate back to the pathway detail. The progress bar should reflect the update for the corresponding step. This end-to-end test validates the entire flow.
  2. Accessibility Check: Perform a quick check using Lighthouse or axe to ensure that the buttons are keyboard accessible and properly labeled. Accessibility is key to inclusive design.

Agent Protocol

Following a structured protocol helps maintain transparency and facilitates collaboration. Here's the protocol we'll adhere to:

  • Progress Updates: Post updates on progress, any questions that arise, and screenshots of tests as comments on the issue. This keeps everyone informed and allows for timely feedback.
  • Pull Request: Open a PR (Pull Request) titled “Module pages: integrate pathway progress API (no auth) (refs this issue)”. This ensures that the PR is clearly linked to the issue it addresses.

Detailed Integration Steps

Now, let's break down the integration steps in a more detailed manner. This will provide a clear roadmap for the implementation process.

1. Template Integration (module-page.html)

The first step involves modifying the module-page.html template. We'll add a client-side block that detects the window.hhUpdatePathwayProgress API and exposes the necessary buttons and links.

<div class="module-progress-buttons">
  <button id="mark-started" aria-label="Mark as started">Mark as started</button>
  <button id="mark-complete" aria-label="Mark complete">Mark complete</button>
  <!-- Optional: Back to pathway link -->
  <a id="back-to-pathway" href="#" style="display: none;">Back to pathway</a>
</div>

<script>
  document.addEventListener('DOMContentLoaded', function() {
    if (typeof window.hhUpdatePathwayProgress === 'function') {
      const markStartedButton = document.getElementById('mark-started');
      const markCompleteButton = document.getElementById('mark-complete');
      const backToPathwayLink = document.getElementById('back-to-pathway');

      markStartedButton.addEventListener('click', function() {
        window.hhUpdatePathwayProgress(1, 0);
      });

      markCompleteButton.addEventListener('click', function() {
        window.hhUpdatePathwayProgress(1, 1);
      });

      // Show back to pathway link if referrer matches
      if (document.referrer && document.referrer.includes('/learn/pathways/')) {
        backToPathwayLink.href = document.referrer;
        backToPathwayLink.style.display = 'inline';
      }
    }
  });
</script>

In this snippet:

  • We create a div with the class module-progress-buttons to contain our buttons.
  • Two buttons, “Mark as started” and “Mark complete”, are added with appropriate aria-labels for accessibility.
  • An optional “Back to pathway” link is included, which will be displayed if the user navigates from a pathway page.
  • The JavaScript code is wrapped inside a DOMContentLoaded listener to ensure it runs after the DOM is fully loaded.
  • We check if window.hhUpdatePathwayProgress is a function before attempting to use it. This prevents errors if the API is not available.
  • Event listeners are added to the buttons to call hhUpdatePathwayProgress with the correct parameters.
  • The “Back to pathway” link’s href is set to document.referrer if the referrer matches the pathway URL pattern.

2. Styling

Next, we need to ensure that our buttons are styled consistently with the rest of the application. This typically involves reusing existing button styles and keeping the footprint small.

.module-progress-buttons button {
  /* Reuse existing button styles */
  background-color: #007bff;
  color: white;
  padding: 10px 20px;
  margin: 5px;
  border: none;
  border-radius: 5px;
  cursor: pointer;
}

.module-progress-buttons button:hover {
  background-color: #0056b3;
}

.module-progress-buttons a {
  /* Style the link */
  color: #007bff;
  text-decoration: none;
  margin: 5px;
}

.module-progress-buttons a:hover {
  text-decoration: underline;
}

This CSS snippet provides basic styling for the buttons and the “Back to pathway” link. You should replace the placeholder styles with your application's existing button styles to maintain consistency.

3. Documentation (docs/content-sync.md or docs/README.md)

Documentation is crucial for ensuring that others (and your future self) understand how this feature works. Update the appropriate documentation file with a section describing the placeholder progress behavior and how authors can test it.

## Placeholder Pathway Progress

This feature provides a placeholder implementation for tracking pathway progress using `localStorage`. It includes “Mark as started” and “Mark complete” buttons on module pages that call the `window.hhUpdatePathwayProgress` API.

### How it Works

*   The buttons are displayed on module detail pages.
*   Clicking “Mark as started” calls `window.hhUpdatePathwayProgress(1, 0)`. 
*   Clicking “Mark complete” calls `window.hhUpdatePathwayProgress(1, 1)`. 
*   Progress is stored in `localStorage` and is not persisted beyond the user’s browser session.

### Testing

To test this feature:

1.  Navigate to a module page (e.g., `/learn/<module-slug>`).
2.  Click the “Mark as started” or “Mark complete” buttons.
3.  Navigate back to the pathway detail page (e.g., `/learn/pathways/<pathway-slug>`).
4.  Verify that the progress bar reflects the changes.

### Notes

*   This is a placeholder implementation and does not require authentication.
*   Ensure that the `window.hhUpdatePathwayProgress` API is available for the buttons to function correctly.

This markdown snippet provides a clear explanation of the placeholder progress behavior, how it works, and how to test it.

Acceptance Testing

Once you've implemented the changes, it's time to run through the acceptance criteria to ensure everything works as expected.

  1. Functional Buttons: Open a module page and verify that the “Mark as started” and “Mark complete” buttons appear. Click each button and check for any errors in the console. Navigate back to the pathway detail page and confirm that the progress is updated.
  2. SEO Compliance: Use your browser’s developer tools to inspect the page and ensure that there is only one H1 tag. Verify that the list rendering has not been altered.
  3. Responsiveness: Open the module page on a mobile device or use your browser’s responsive design mode to ensure that the buttons are displayed correctly and are usable on smaller screens.
  4. Server-Side Safety: Check the page for any JavaScript errors when the pathway script is not loaded. The code should gracefully handle the absence of the window.hhUpdatePathwayProgress API.

Lighthouse/Axe Check

Finally, use Lighthouse or axe to perform a quick accessibility check. This ensures that the buttons are keyboard accessible and have appropriate labels.

  1. Open the module page in Chrome.
  2. Open Chrome DevTools (F12).
  3. Go to the “Audits” tab.
  4. Select “Accessibility” and click “Generate report”.
  5. Review the report for any issues related to keyboard accessibility and labels.

Final Thoughts

Integrating the Pathway Progress API into module pages without authentication is a significant step forward. By following these detailed steps, you can ensure a smooth and successful implementation. Remember to keep the user experience in mind, maintain SEO best practices, and document your changes thoroughly. Happy coding, guys!