Use an AddonsApplication to manage load/reload of all addons

public/_/readthedocs-addons.json

@@ -93,6 +93,9 @@
   "readthedocs": {
     "analytics": {
       "code": "UA-12345"
+    },
+    "resolver": {
+      "filename": "/index.html"
     }
   },
   "addons": {

public/index.html

@@ -22,6 +22,9 @@ <h1 id="documentation-addons">Documentation Addons</h1>
       <h2 id="docdiff">CustomEvent</h2>
       <p>Project slug using <em>CustomEvent</em>: <span id="custom-event-project-slug"></span></p>
 
+      <h2 id="flyout">Flyout</h2>
+      <readthedocs-flyout></readthedocs-flyout>
+
       <h2 id="docdiff">DocDiff</h2>
       <p>Visit <a href="docdiff.html">this page</a> to take a look at it.</p>
 

src/analytics.js

@@ -3,8 +3,7 @@
 import { default as fetch } from "unfetch";
 
 import { ajv } from "./data-validation";
-import { AddonBase } from "./utils";
-import { CLIENT_VERSION } from "./utils";
+import { AddonBase, CLIENT_VERSION } from "./utils";
 
 export const API_ENDPOINT = "/_/api/v2/analytics/";
 
@@ -27,8 +26,7 @@ export class AnalyticsAddon extends AddonBase {
   static addonName = "Analytics";
   static enabledOnHttpStatus = [200, 404];
 
-  constructor(config) {
-    super();
+  loadConfig(config) {
     this.config = config;
 
     // Only register pageviews on non-external versions

src/application.js

@@ -0,0 +1,174 @@
+import { CSSResult } from "lit";
+
+import {
+  docTool,
+  domReady,
+  isEmbedded,
+  IS_PRODUCTION,
+  setupLogging,
+  setupHistoryEvents,
+  getMetadataValue,
+} from "./utils";
+import { getReadTheDocsConfig } from "./readthedocs-config";
+import {
+  EVENT_READTHEDOCS_ADDONS_INTERNAL_DATA_READY,
+  EVENT_READTHEDOCS_URL_CHANGED,
+} from "./events";
+
+import * as notification from "./notification";
+import * as analytics from "./analytics";
+import * as search from "./search";
+import * as docdiff from "./docdiff";
+import * as flyout from "./flyout";
+import * as ethicalads from "./ethicalads";
+import * as hotkeys from "./hotkeys";
+import * as linkpreviews from "./linkpreviews";
+import * as filetreediff from "./filetreediff";
+import * as customscript from "./customscript";
+import * as application from "./application";
+import { default as objectPath } from "object-path";
+
+import doctoolsStyleSheet from "./doctools.css";
+
+export class AddonsApplication {
+  constructor() {
+    setupLogging();
+    setupHistoryEvents();
+
+    this.addonsInstances = [];
+    this.config = null;
+
+    console.debug(
+      "Addons Application config (from constructor() method)",
+      this.config,
+    );
+
+    this.addons = [
+      flyout.FlyoutAddon,
+      notification.NotificationAddon,
+      analytics.AnalyticsAddon,
+      ethicalads.EthicalAdsAddon,
+      search.SearchAddon,
+
+      // HotKeys & FileTreeDiff have to be initialized before DocDiff because when
+      // `?readthedocs-diff=true` DocDiff triggers an event that HotKeys has to
+      // listen to to update its internal state.
+      // https://github.com/readthedocs/addons/blob/47645b013724cdf244716b549a5baa28409fafcb/src/docdiff.js#L105-L111
+      hotkeys.HotKeysAddon,
+      filetreediff.FileTreeDiffAddon,
+      docdiff.DocDiffAddon,
+
+      linkpreviews.LinkPreviewsAddon,
+      customscript.CustomScriptAddon,
+    ];
+
+    this.httpStatus = getMetadataValue("readthedocs-http-status");
+
+    this.addDoctoolData();
+    getReadTheDocsConfig(this.sendUrlParam());
+  }
+
+  reload(config) {
+    console.debug("Addons Application config (from reload() method)", config);
+
+    if (!config) {
+      return;
+    }
+    this.config = config;
+    if (this.config && !this.loadWhenEmbedded()) {
+      return;
+    }
+
+    if (!this.addonsInstances.length) {
+      // Addons instances were not created yet
+      try {
+        this.addonsInstances = this.addons
+          .filter((addon) => addon.isEnabled(this.config, this.httpStatus))
+          .map((addon) => new addon(this.config));
+      } catch (err) {
+        console.error(err);
+      }
+    } else {
+      // Addons instances were already created. We just need to reload them with
+      // the new config object.
+      for (const addon of this.addonsInstances) {
+        addon.loadConfig(config);
+      }
+    }
+    return;
+  }
+
+  loadWhenEmbedded() {
+    const loadWhenEmbedded = objectPath.get(
+      this.config,
+      "addons.options.load_when_embedded",
+      false,
+    );
+    if (isEmbedded() && !loadWhenEmbedded) {
+      return false;
+    }
+    return true;
+  }
+
+  sendUrlParam() {
+    for (const addon of this.addons) {
+      if (addon.requiresUrlParam()) {
+        console.debug(`${addon.addonName} requires "url=" parameter.`);
+        return true;
+      }
+    }
+    return false;
+  }
+
+  addDoctoolData() {
+    // Apply fixes to variables for individual documentation tools
+    const elementHtml = document.querySelector("html");
+    if (elementHtml) {
+      // Inject styles at the parent DOM to set variables at :root
+      let styleSheet = doctoolsStyleSheet;
+      if (doctoolsStyleSheet instanceof CSSResult) {
+        styleSheet = doctoolsStyleSheet.styleSheet;
+      }
+      document.adoptedStyleSheets = [styleSheet];
+
+      // If we detect a documentation tool, set attributes on :root to allow
+      // for CSS selectors to utilize these values.
+      if (docTool.documentationTool) {
+        elementHtml.setAttribute(
+          "data-readthedocs-tool",
+          docTool.documentationTool,
+        );
+      }
+      if (docTool.documentationTheme) {
+        elementHtml.setAttribute(
+          "data-readthedocs-tool-theme",
+          docTool.documentationTheme,
+        );
+      }
+    }
+  }
+}
+
+export const addonsApplication = new AddonsApplication();
+
+/**
+ * Subscribe to `EVENT_READTHEDOCS_ADDONS_INTERNAL_DATA_READY` to reload all the
+ * addons with fresh Addons API data once it's ready.
+ *
+ */
+document.addEventListener(
+  EVENT_READTHEDOCS_ADDONS_INTERNAL_DATA_READY,
+  (event) => {
+    addonsApplication.reload(event.detail.data(true));
+  },
+);
+
+/**
+ * Subscribe to `EVENT_READTHEDOCS_URL_CHANGED` to trigger a new request to
+ * Addons API to fetch fresh data.
+ *
+ */
+window.addEventListener(EVENT_READTHEDOCS_URL_CHANGED, (event) => {
+  console.debug("URL Change detected. Triggering a new API call", event);
+  getReadTheDocsConfig(addonsApplication.sendUrlParam());
+});

src/customscript.js

@@ -15,8 +15,7 @@ export class CustomScriptAddon extends AddonBase {
   static addonName = "CustomScript";
   static enabledOnHttpStatus = [200, 403, 404, 500];
 
-  constructor(config) {
-    super();
+  loadConfig(config) {
     this.config = config;
 
     if (objectPath.get(this.config, "addons.customscript.src")) {
@@ -25,6 +24,11 @@ export class CustomScriptAddon extends AddonBase {
   }
 
   injectJavaScriptFile() {
+    // Do not add the script if it already exists in the page.
+    if (document.querySelector(`#${SCRIPT_ID}`) !== null) {
+      return;
+    }
+
     const script = document.createElement("script");
     script.id = SCRIPT_ID;
     script.src = objectPath.get(this.config, "addons.customscript.src");

src/data-validation.js

@@ -131,7 +131,7 @@ const addons_ethicalads = {
 const addons_flyout = {
   $id: "http://v1.schemas.readthedocs.org/addons.flyout.json",
   type: "object",
-  required: ["addons", "projects", "versions"],
+  required: ["addons", "projects", "versions", "readthedocs"],
   properties: {
     addons: {
       type: "object",
@@ -242,14 +242,27 @@ const addons_flyout = {
         },
       },
     },
+    readthedocs: {
+      type: "object",
+      required: ["resolver"],
+      properties: {
+        resolver: {
+          type: "object",
+          required: ["filename"],
+          properties: {
+            filename: { type: "string" },
+          },
+        },
+      },
+    },
   },
 };
 
 // Validator for File Tree Diff Addon
 const addons_filetreediff = {
   $id: "http://v1.schemas.readthedocs.org/addons.filetreediff.json",
   type: "object",
-  required: ["addons"],
+  required: ["addons", "versions"],
   properties: {
     addons: {
       type: "object",
@@ -272,6 +285,19 @@ const addons_filetreediff = {
         },
       },
     },
+    versions: {
+      type: "object",
+      required: ["current"],
+      properties: {
+        current: {
+          type: "object",
+          required: ["type"],
+          properties: {
+            type: { type: "string" },
+          },
+        },
+      },
+    },
   },
 };
 
@@ -317,7 +343,7 @@ const addons_hotkeys = {
 const addons_notifications = {
   $id: "http://v1.schemas.readthedocs.org/addons.notifications.json",
   type: "object",
-  required: ["addons"],
+  required: ["addons", "readthedocs"],
   properties: {
     addons: {
       type: "object",
@@ -429,6 +455,19 @@ const addons_notifications = {
         },
       },
     },
+    readthedocs: {
+      type: "object",
+      required: ["resolver"],
+      properties: {
+        resolver: {
+          type: "object",
+          required: ["filename"],
+          properties: {
+            filename: { type: "string" },
+          },
+        },
+      },
+    },
   },
 };
 

src/docdiff.js

@@ -11,15 +11,14 @@ import docdiffGeneralStyleSheet from "./docdiff.document.css";
 // See https://github.com/readthedocs/addons/pull/234
 import * as visualDomDiff from "visual-dom-diff";
 
-import { AddonBase } from "./utils";
 import {
   EVENT_READTHEDOCS_DOCDIFF_ADDED_REMOVED_SHOW,
   EVENT_READTHEDOCS_DOCDIFF_HIDE,
   EVENT_READTHEDOCS_ROOT_DOM_CHANGED,
 } from "./events";
 import { nothing, LitElement } from "lit";
 import { default as objectPath } from "object-path";
-import { getQueryParam, docTool } from "./utils";
+import { AddonBase, getQueryParam, docTool } from "./utils";
 import { EMBED_API_ENDPOINT } from "./constants";
 
 export const DOCDIFF_URL_PARAM = "readthedocs-diff";
@@ -266,23 +265,7 @@ export class DocDiffAddon extends AddonBase {
     "http://v1.schemas.readthedocs.org/addons.docdiff.json";
   static addonEnabledPath = "addons.doc_diff.enabled";
   static addonName = "DocDiff";
-
-  constructor(config) {
-    super();
-
-    // TODO: is it possible to move this `constructor` to the `AddonBase` class?
-    customElements.define("readthedocs-docdiff", DocDiffElement);
-    let elems = document.querySelectorAll("readthedocs-docdiff");
-    if (!elems.length) {
-      elems = [new DocDiffElement()];
-      document.body.append(elems[0]);
-      elems[0].requestUpdate();
-    }
-
-    for (const elem of elems) {
-      elem.loadConfig(config);
-    }
-  }
+  static elementClass = DocDiffElement;
 
   static requiresUrlParam() {
     return (
@@ -294,3 +277,5 @@ export class DocDiffAddon extends AddonBase {
     );
   }
 }
+
+customElements.define(DocDiffElement.elementName, DocDiffElement);

src/ethicalads.js

@@ -31,9 +31,14 @@ export class EthicalAdsAddon extends AddonBase {
   static addonEnabledPath = "addons.ethicalads.enabled";
   static addonName = "EthicalAds";
 
-  constructor(config) {
-    super();
+  loadConfig(config) {
     this.config = config;
+
+    // Do not add another ad if we already added one
+    if (document.querySelector(`#${AD_SCRIPT_ID}`) !== null) {
+      return;
+    }
+
     this.injectEthicalAds();
   }