New UserJsFile addon

humitos · humitos · commit da6ab1652c25 · 2024-11-13T14:24:52.000+01:00
This is a new addon that allow users to inject a specific JavaScript file to all the versions to all the documentation pages to allow them to fix issues in old "frozen" (not able to re-build) versions. Requires readthedocs/readthedocs.org#11758
diff --git a/dist/readthedocs-addons.js b/dist/readthedocs-addons.js
diff --git a/dist/readthedocs-addons.js.map b/dist/readthedocs-addons.js.map
diff --git a/src/data-validation.js b/src/data-validation.js
@@ -493,6 +493,29 @@ const addons_linkpreviews = {
   },
 };
 
+// Validator for UserJsFile Addon
+const addons_userjsfile = {
+  $id: "http://v1.schemas.readthedocs.org/addons.userjsfile.json",
+  type: "object",
+  required: ["addons"],
+  properties: {
+    addons: {
+      type: "object",
+      required: ["userjsfile"],
+      properties: {
+        userjsfile: {
+          type: "object",
+          required: ["enabled"],
+          properties: {
+            enabled: { type: "boolean" },
+            src: { type: ["string", "null"] },
+          },
+        },
+      },
+    },
+  },
+};
+
 export const ajv = new Ajv({
   allErrors: true,
   schemas: [
@@ -505,6 +528,7 @@ export const ajv = new Ajv({
     addons_search,
     addons_linkpreviews,
     addons_filetreediff,
+    addons_userjsfile,
   ],
 });
 
diff --git a/src/index.js b/src/index.js
@@ -8,6 +8,7 @@ import * as ethicalads from "./ethicalads";
 import * as hotkeys from "./hotkeys";
 import * as linkpreviews from "./linkpreviews";
 import * as filetreediff from "./filetreediff";
+import * as userjsfile from "./userjsfile";
 import {
   domReady,
   IS_PRODUCTION,
@@ -26,6 +27,7 @@ export function setup() {
     hotkeys.HotKeysAddon,
     linkpreviews.LinkPreviewsAddon,
     filetreediff.FileTreeDiffAddon,
+    userjsfile.UserJsFileAddon,
   ];
 
   return new Promise((resolve) => {
diff --git a/src/userjsfile.js b/src/userjsfile.js
@@ -0,0 +1,35 @@
+import { default as objectPath } from "object-path";
+import { AddonBase } from "./utils";
+
+const SCRIPT_ID = "readthedocs-addons-user-js-file";
+
+/**
+ * User JavaScript file.
+ *
+ * Allow a user to inject a custom JavaScript file in all the pages.
+ */
+export class UserJsFileAddon extends AddonBase {
+  static jsonValidationURI =
+    "http://v1.schemas.readthedocs.org/addons.userjsfile.json";
+  static addonEnabledPath = "addons.userjsfile.enabled";
+  static addonName = "UserJsFile";
+  static enabledOnHttpStatus = [200, 403, 404, 500];
+
+  constructor(config) {
+    super();
+    this.config = config;
+
+    if (objectPath.get(this.config, "addons.userjsfile.src")) {
+      this.injectJavaScriptFile();
+    }
+  }
+
+  injectJavaScriptFile() {
+    const script = document.createElement("script");
+    script.id = SCRIPT_ID;
+    script.src = objectPath.get(this.config, "addons.userjsfile.src");
+    script.async = true;
+
+    document.body.appendChild(script);
+  }
+}
diff --git a/tests/userjsfile.test.html b/tests/userjsfile.test.html
@@ -0,0 +1,36 @@
+<html>
+  <body>
+    <script type="module">
+      import { expect, elementUpdated } from "@open-wc/testing";
+      import { runTests } from "@web/test-runner-mocha";
+      import * as userjsfile from "../src/userjsfile";
+
+      let config;
+
+      runTests(async () => {
+        beforeEach(() => {
+
+          config = {
+            addons: {
+              userjsfile: {
+                enabled: true,
+                src: "https://myproject.readthedocs.io/en/latest/_static/readthedocs.js",
+              },
+            },
+          };
+        });
+
+        describe("UserJsFile addon", () => {
+          it("script element is added", async () => {
+            const addon = new userjsfile.UserJsFileAddon(config);
+            const element = document.querySelector("#readthedocs-addons-user-js-file");
+
+            expect(element.src).to.equal("https://myproject.readthedocs.io/en/latest/_static/readthedocs.js");
+            expect(element.async).to.equal(true);
+        });
+
+        });
+      });
+    </script>
+  </body>
+</html>
diff --git a/tests/userjsfile.test.js b/tests/userjsfile.test.js
@@ -0,0 +1,42 @@
+import { expect, assert, fixture, html } from "@open-wc/testing";
+import { UserJsFileAddon } from "../src/userjsfile";
+
+describe("UserJsFile addon", () => {
+  it("invalid configuration disables the addon", () => {
+    expect(
+      UserJsFileAddon.isEnabled({
+        addons: {
+          userjsfile: {
+            invalid: true,
+          },
+        },
+      }),
+    ).to.be.false;
+  });
+
+  it("is disabled", () => {
+    expect(
+      UserJsFileAddon.isEnabled({
+        addons: {
+          userjsfile: {
+            enabled: false,
+            src: "/en/latest/_static/readthedocs.js",
+          },
+        },
+      }),
+    ).to.be.false;
+  });
+
+  it("valid data and enabled", () => {
+    expect(
+      UserJsFileAddon.isEnabled({
+        addons: {
+          userjsfile: {
+            enabled: true,
+            src: "/en/latest/_static/readthedocs.js",
+          },
+        },
+      }),
+    ).to.be.true;
+  });
+});
