readthedocs · humitos · Nov 18, 2024 · Nov 13, 2024 · Nov 13, 2024 · Nov 13, 2024
@@ -149,6 +149,10 @@
       ],
       "default_filter": "subprojects:example/latest"
     },
+    "userjsfile": {
+      "enabled": true,
+      "src": "userjsfile.js"
+    },
     "hotkeys": {
       "enabled": true,
       "doc_diff": {

@@ -34,6 +34,9 @@ <h2 id="ethicalads">Ethical Ad</h2>
           data-ea-type="readthedocs-sidebar">
       </div>
 
+      <h2 id="userjsfile">UserJsFile</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/public/userjsfile.js b/public/userjsfile.js
@@ -0,0 +1,2 @@
+const section = document.querySelector("#userjsfile + p");
+section.innerHTML = "This was injected by the userjsfile script";
@@ -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,
   ],
 });
 

@@ -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,38 @@
+<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;
+  });
+});
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		const section = document.querySelector("#userjsfile + p");
		section.innerHTML = "This was injected by the userjsfile script";