API: save a "flag" on window object

[humitos]

We need to find a way for people subscribing to the Read the Docs data ready event after it was triggered. This is an idea about how to solve this use case.

It adds a "flag" in the window object that users can check before subscribing to that event to make usage of the data if the event was triggered already.

• Reference: Add meta tags "noindex, nofollow" for hidden version readthedocs.org#10648 (comment)
• Example: https://github.com/readthedocs/test-builds/blob/full-feature/docs/static/readthedocs.js

[agjohnson]

Seems good for now, but I think the context API probably will solve this is a cleaner way later.

[DimedS]

Hi @humitos, @agjohnson,
Happy New Year! 🎉 Do you have any plans to merge that PR? I believe it would resolve the issue mentioned in readthedocs/readthedocs.org#10648.

[humitos]

@DimedS We are still experimenting with a different, and more generic approach. I want to continue testing that, before moving forward here since it may replace the idea from this branch. I will let you know when I have some progress on this.

[DimedS]

@DimedS We are still experimenting with a different, and more generic approach. I want to continue testing that, before moving forward here since it may replace the idea from this branch. I will let you know when I have some progress on this.

Thanks, @humitos! Appreciate the update and your efforts!

[humitos]

As a reference, I started the work I refer to previously at #491

[humitos]

This is an example of how we can use this feature on projects:

if (document.querySelector("meta[name='readthedocs-addons-api-version']") === null) {
  // Add a META tag to specify the API version we are expecting
  const meta = document.createElement("meta");
  meta.name = "readthedocs-addons-api-version";
  meta.content = "1";
  document.head.append(meta);
}

// Show a message in the console immediatelly loading this script
console.log("This message comes from a file injected by CustomScript addon.");

function _handleReadTheDocsData (data) {
  console.log("_handleReadTheDocsData function called.");
  console.log("Project slug:", data.projects.current.slug);
}

// The event "readthedocs-addons-data-ready" has been already fired when this script is run.
// We need to check for `window.ReadTheDocsEventData` first, and if it's available
// use that data to call the handler.
if (window.ReadTheDocsEventData !== undefined) {
  _handleReadTheDocsData(window.ReadTheDocsEventData.data());
}

// After that, we subscribe to the Read the Docs Addons event to access data
// on future dispatchs (e.g. when a URL changes on a SPA)
document.addEventListener("readthedocs-addons-data-ready", function (event) {
  _handleReadTheDocsData(event.detail.data());
});

Live example: https://test-builds.readthedocs.io/en/full-feature/