New CustomScript addon (#431)

humitos · web-flow · commit 0b605f6240e3 · 2024-11-18T16:48:03.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/public/_/readthedocs-addons.json b/public/_/readthedocs-addons.json
@@ -149,6 +149,10 @@
       ],
       "default_filter": "subprojects:example/latest"
     },
+    "customscript": {
+      "enabled": true,
+      "src": "customscript.js"
+    },
     "hotkeys": {
       "enabled": true,
       "doc_diff": {
diff --git a/public/customscript.js b/public/customscript.js
@@ -0,0 +1,2 @@
+const section = document.querySelector("#customscript + p");
+section.innerHTML = "This was injected by the customscript addon";
diff --git a/public/index.html b/public/index.html
@@ -34,6 +34,9 @@ <h2 id="ethicalads">Ethical Ad</h2>
           data-ea-type="readthedocs-sidebar">
       </div>
 
+      <h2 id="customscript">CustomScript</h2>
+      <p>Content of the section</p>
+
       <h2 id="search">Search</h2>
       <p>Hit <code>/</code> to trigger the search modal, or click on the input from the flyout.</p>
       <readthedocs-search></readthedocs-search>
diff --git a/src/customscript.js b/src/customscript.js
@@ -0,0 +1,35 @@
+import { default as objectPath } from "object-path";
+import { AddonBase } from "./utils";
+
+const SCRIPT_ID = "readthedocs-addons-custom-script";
+
+/**
+ * User JavaScript file.
+ *
+ * Allow a user to inject a custom JavaScript file in all the pages.
+ */
+export class CustomScriptAddon extends AddonBase {
+  static jsonValidationURI =
+    "http://v1.schemas.readthedocs.org/addons.customscript.json";
+  static addonEnabledPath = "addons.customscript.enabled";
+  static addonName = "CustomScript";
+  static enabledOnHttpStatus = [200, 403, 404, 500];
+
+  constructor(config) {
+    super();
+    this.config = config;
+
+    if (objectPath.get(this.config, "addons.customscript.src")) {
+      this.injectJavaScriptFile();
+    }
+  }
+
+  injectJavaScriptFile() {
+    const script = document.createElement("script");
+    script.id = SCRIPT_ID;
+    script.src = objectPath.get(this.config, "addons.customscript.src");
+    script.async = true;
+
+    document.body.appendChild(script);
+  }
+}
diff --git a/src/data-validation.js b/src/data-validation.js
@@ -493,6 +493,29 @@ const addons_linkpreviews = {
   },
 };
 
+// Validator for CustomScript Addon
+const addons_customscript = {
+  $id: "http://v1.schemas.readthedocs.org/addons.customscript.json",
+  type: "object",
+  required: ["addons"],
+  properties: {
+    addons: {
+      type: "object",
+      required: ["customscript"],
+      properties: {
+        customscript: {
+          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_customscript,
   ],
 });
 
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 customscript from "./customscript";
 import {
   domReady,
   IS_PRODUCTION,
@@ -26,6 +27,7 @@ export function setup() {
     hotkeys.HotKeysAddon,
     linkpreviews.LinkPreviewsAddon,
     filetreediff.FileTreeDiffAddon,
+    customscript.CustomScriptAddon,
   ];
 
   return new Promise((resolve) => {
diff --git a/tests/customscript.test.html b/tests/customscript.test.html
@@ -0,0 +1,38 @@
+<html>
+  <body>
+    <script type="module">
+      import { expect, elementUpdated } from "@open-wc/testing";
+      import { runTests } from "@web/test-runner-mocha";
+      import * as customscript from "../src/customscript";
+
+      let config;
+
+      runTests(async () => {
+        beforeEach(() => {
+          config = {
+            addons: {
+              customscript: {
+                enabled: true,
+                src: "https://myproject.readthedocs.io/en/latest/_static/readthedocs.js",
+              },
+            },
+          };
+        });
+
+        describe("CustomScript addon", () => {
+          it("script element is added", async () => {
+            const addon = new customscript.CustomScriptAddon(config);
+            const element = document.querySelector(
+              "#readthedocs-addons-custom-script",
+            );
+
+            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/customscript.test.js b/tests/customscript.test.js
@@ -0,0 +1,42 @@
+import { expect, assert, fixture, html } from "@open-wc/testing";
+import { CustomScriptAddon } from "../src/customscript";
+
+describe("CustomScript addon", () => {
+  it("invalid configuration disables the addon", () => {
+    expect(
+      CustomScriptAddon.isEnabled({
+        addons: {
+          customscript: {
+            invalid: true,
+          },
+        },
+      }),
+    ).to.be.false;
+  });
+
+  it("is disabled", () => {
+    expect(
+      CustomScriptAddon.isEnabled({
+        addons: {
+          customscript: {
+            enabled: false,
+            src: "/en/latest/_static/readthedocs.js",
+          },
+        },
+      }),
+    ).to.be.false;
+  });
+
+  it("valid data and enabled", () => {
+    expect(
+      CustomScriptAddon.isEnabled({
+        addons: {
+          customscript: {
+            enabled: true,
+            src: "/en/latest/_static/readthedocs.js",
+          },
+        },
+      }),
+    ).to.be.true;
+  });
+});

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+const section = document.querySelector("#customscript + p");`
	`2`	`+section.innerHTML = "This was injected by the customscript addon";`