From 9f8ff32c3660325596b35628af930aec069fcd60 Mon Sep 17 00:00:00 2001 From: Federico Bond Date: Wed, 26 Nov 2025 11:46:27 +1100 Subject: [PATCH 1/3] Use shadow dom to render the toolbar --- .../static/debug_toolbar/css/toolbar.css | 4 +- .../static/debug_toolbar/js/history.js | 8 +- .../static/debug_toolbar/js/timer.js | 9 ++- .../static/debug_toolbar/js/toolbar.js | 52 ++++++------ .../static/debug_toolbar/js/utils.js | 21 +++-- .../templates/debug_toolbar/base.html | 79 ++++++++++--------- docs/configuration.rst | 2 +- docs/panels.rst | 4 +- 8 files changed, 97 insertions(+), 82 deletions(-) diff --git a/debug_toolbar/static/debug_toolbar/css/toolbar.css b/debug_toolbar/static/debug_toolbar/css/toolbar.css index 044e15e5f..13b88f5c2 100644 --- a/debug_toolbar/static/debug_toolbar/css/toolbar.css +++ b/debug_toolbar/static/debug_toolbar/css/toolbar.css @@ -1,5 +1,5 @@ /* Variable definitions */ -:root { +:host { /* Font families are the same as in Django admin/css/base.css */ --djdt-font-family-primary: "Segoe UI", system-ui, Roboto, "Helvetica Neue", Arial, sans-serif, @@ -13,7 +13,7 @@ "Noto Color Emoji"; } -:root, +:host, #djDebug[data-theme="light"] { --djdt-font-color: black; --djdt-background-color: white; diff --git a/debug_toolbar/static/debug_toolbar/js/history.js b/debug_toolbar/static/debug_toolbar/js/history.js index c2644eca7..148051330 100644 --- a/debug_toolbar/static/debug_toolbar/js/history.js +++ b/debug_toolbar/static/debug_toolbar/js/history.js @@ -1,6 +1,6 @@ -import { $$, ajaxForm, replaceToolbarState } from "./utils.js"; +import { $$, ajaxForm, getDebugElement, replaceToolbarState } from "./utils.js"; -const djDebug = document.getElementById("djDebug"); +const djDebug = getDebugElement(); function difference(setA, setB) { const _difference = new Set(setA); @@ -19,7 +19,7 @@ function pluckData(nodes, key) { function refreshHistory() { const formTarget = djDebug.querySelector(".refreshHistory"); - const container = document.getElementById("djdtHistoryRequests"); + const container = djDebug.querySelector("#djdtHistoryRequests"); const oldIds = new Set( pluckData( container.querySelectorAll("tr[data-request-id]"), @@ -85,7 +85,7 @@ function switchHistory(newRequestId) { ajaxForm(formTarget).then((data) => { if (Object.keys(data).length === 0) { - const container = document.getElementById("djdtHistoryRequests"); + const container = djDebug.querySelector("#djdtHistoryRequests"); container.querySelector( `button[data-request-id="${newRequestId}"]` ).innerHTML = "Switch [EXPIRED]"; diff --git a/debug_toolbar/static/debug_toolbar/js/timer.js b/debug_toolbar/static/debug_toolbar/js/timer.js index a01dbb2d1..a60e931a9 100644 --- a/debug_toolbar/static/debug_toolbar/js/timer.js +++ b/debug_toolbar/static/debug_toolbar/js/timer.js @@ -1,4 +1,6 @@ -import { $$ } from "./utils.js"; +import { $$, getDebugElement } from "./utils.js"; + +const djDebug = getDebugElement(); function insertBrowserTiming() { const timingOffset = performance.timing.navigationStart; @@ -58,10 +60,10 @@ function insertBrowserTiming() { tbody.appendChild(row); } - const browserTiming = document.getElementById("djDebugBrowserTiming"); + const browserTiming = djDebug.querySelector("#djDebugBrowserTiming"); // Determine if the browser timing section has already been rendered. if (browserTiming.classList.contains("djdt-hidden")) { - const tbody = document.getElementById("djDebugBrowserTimingTableBody"); + const tbody = djDebug.querySelector("#djDebugBrowserTimingTableBody"); // This is a reasonably complete and ordered set of timing periods (2 params) and events (1 param) addRow(tbody, "domainLookupStart", "domainLookupEnd"); addRow(tbody, "connectStart", "connectEnd"); @@ -75,7 +77,6 @@ function insertBrowserTiming() { } } -const djDebug = document.getElementById("djDebug"); // Insert the browser timing now since it's possible for this // script to miss the initial panel load event. insertBrowserTiming(); diff --git a/debug_toolbar/static/debug_toolbar/js/toolbar.js b/debug_toolbar/static/debug_toolbar/js/toolbar.js index 609842209..bedf364b6 100644 --- a/debug_toolbar/static/debug_toolbar/js/toolbar.js +++ b/debug_toolbar/static/debug_toolbar/js/toolbar.js @@ -1,4 +1,10 @@ -import { $$, ajax, debounce, replaceToolbarState } from "./utils.js"; +import { + $$, + ajax, + debounce, + getDebugElement, + replaceToolbarState, +} from "./utils.js"; function onKeyDown(event) { if (event.keyCode === 27) { @@ -6,15 +12,6 @@ function onKeyDown(event) { } } -function getDebugElement() { - // Fetch the debug element from the DOM. - // This is used to avoid writing the element's id - // everywhere the element is being selected. A fixed reference - // to the element should be avoided because the entire DOM could - // be reloaded such as via HTMX boosting. - return document.getElementById("djDebug"); -} - const djdt = { handleDragged: false, needUpdateOnFetch: false, @@ -27,7 +24,7 @@ const djdt = { return; } const panelId = this.className; - const current = document.getElementById(panelId); + const current = djDebug.querySelector(`#${panelId}`); if ($$.visible(current)) { djdt.hidePanels(); } else { @@ -103,7 +100,7 @@ const djdt = { } ajax(url, ajaxData).then((data) => { - const win = document.getElementById("djDebugWindow"); + const win = djDebug.querySelector("#djDebugWindow"); win.innerHTML = data.content; $$.show(win); }); @@ -116,7 +113,7 @@ const djdt = { const toggleClose = "-"; const openMe = this.textContent === toggleOpen; const name = this.dataset.toggleName; - const container = document.getElementById(`${name}_${id}`); + const container = djDebug.querySelector(`#${name}_${id}`); for (const el of container.querySelectorAll(".djDebugCollapsed")) { $$.toggle(el, openMe); } @@ -156,7 +153,7 @@ const djdt = { }); let startPageY; let baseY; - const handle = document.getElementById("djDebugToolbarHandle"); + const handle = djDebug.querySelector("#djDebugToolbarHandle"); function onHandleMove(event) { // Chrome can send spurious mousemove events, so don't do anything unless the // cursor really moved. Otherwise, it will be impossible to expand the toolbar @@ -240,16 +237,17 @@ const djdt = { }, hidePanels() { const djDebug = getDebugElement(); - $$.hide(document.getElementById("djDebugWindow")); + $$.hide(djDebug.querySelector("#djDebugWindow")); for (const el of djDebug.querySelectorAll(".djdt-panelContent")) { $$.hide(el); } - for (const el of document.querySelectorAll("#djDebugToolbar li")) { + for (const el of djDebug.querySelectorAll("#djDebugToolbar li")) { el.classList.remove("djdt-active"); } }, ensureHandleVisibility() { - const handle = document.getElementById("djDebugToolbarHandle"); + const djDebug = getDebugElement(); + const handle = djDebug.querySelector("#djDebugToolbarHandle"); // set handle position const handleTop = Math.min( localStorage.getItem("djdt.top") || 265, @@ -258,11 +256,12 @@ const djdt = { handle.style.top = `${handleTop}px`; }, hideToolbar() { + const djDebug = getDebugElement(); djdt.hidePanels(); - $$.hide(document.getElementById("djDebugToolbar")); + $$.hide(djDebug.querySelector("#djDebugToolbar")); - const handle = document.getElementById("djDebugToolbarHandle"); + const handle = djDebug.querySelector("#djDebugToolbarHandle"); $$.show(handle); djdt.ensureHandleVisibility(); window.addEventListener("resize", djdt.ensureHandleVisibility); @@ -271,11 +270,12 @@ const djdt = { localStorage.setItem("djdt.show", "false"); }, hideOneLevel() { - const win = document.getElementById("djDebugWindow"); + const djDebug = getDebugElement(); + const win = djDebug.querySelector("#djDebugWindow"); if ($$.visible(win)) { $$.hide(win); } else { - const toolbar = document.getElementById("djDebugToolbar"); + const toolbar = djDebug.querySelector("#djDebugToolbar"); if (toolbar.querySelector("li.djdt-active")) { djdt.hidePanels(); } else { @@ -284,16 +284,16 @@ const djdt = { } }, showToolbar() { + const djDebug = getDebugElement(); document.addEventListener("keydown", onKeyDown); - $$.show(document.getElementById("djDebug")); - $$.hide(document.getElementById("djDebugToolbarHandle")); - $$.show(document.getElementById("djDebugToolbar")); + $$.show(djDebug); + $$.hide(djDebug.querySelector("#djDebugToolbarHandle")); + $$.show(djDebug.querySelector("#djDebugToolbar")); localStorage.setItem("djdt.show", "true"); window.removeEventListener("resize", djdt.ensureHandleVisibility); }, updateOnAjax() { - const sidebarUrl = - document.getElementById("djDebug").dataset.sidebarUrl; + const sidebarUrl = getDebugElement().dataset.sidebarUrl; const slowjax = debounce(ajax, 200); function handleAjaxResponse(requestId) { diff --git a/debug_toolbar/static/debug_toolbar/js/utils.js b/debug_toolbar/static/debug_toolbar/js/utils.js index 9b34f86f8..6a32db892 100644 --- a/debug_toolbar/static/debug_toolbar/js/utils.js +++ b/debug_toolbar/static/debug_toolbar/js/utils.js @@ -70,6 +70,16 @@ const $$ = { }, }; +function getDebugElement() { + // Fetch the debug element from the DOM. + // This is used to avoid writing the element's id + // everywhere the element is being selected. A fixed reference + // to the element should be avoided because the entire DOM could + // be reloaded such as via HTMX boosting. + const root = document.getElementById("djDebugRoot").shadowRoot; + return root.querySelector("#djDebug"); +} + function ajax(url, init) { return fetch(url, Object.assign({ credentials: "same-origin" }, init)) .then((response) => { @@ -89,7 +99,8 @@ function ajax(url, init) { ); }) .catch((error) => { - const win = document.getElementById("djDebugWindow"); + const djDebug = getDebugElement(); + const win = djDebug.querySelector("#djDebugWindow"); win.innerHTML = `

${error.message}

`; $$.show(win); throw error; @@ -110,14 +121,14 @@ function ajaxForm(element) { } function replaceToolbarState(newRequestId, data) { - const djDebug = document.getElementById("djDebug"); + const djDebug = getDebugElement(); djDebug.setAttribute("data-request-id", newRequestId); // Check if response is empty, it could be due to an expired requestId. for (const panelId of Object.keys(data)) { - const panel = document.getElementById(panelId); + const panel = djDebug.querySelector(`#${panelId}`); if (panel) { panel.outerHTML = data[panelId].content; - document.getElementById(`djdt-${panelId}`).outerHTML = + djDebug.querySelector(`#djdt-${panelId}`).outerHTML = data[panelId].button; } } @@ -141,4 +152,4 @@ function debounce(func, delay) { }; } -export { $$, ajax, ajaxForm, replaceToolbarState, debounce }; +export { $$, getDebugElement, ajax, ajaxForm, replaceToolbarState, debounce }; diff --git a/debug_toolbar/templates/debug_toolbar/base.html b/debug_toolbar/templates/debug_toolbar/base.html index b7562ecba..2c38ed68b 100644 --- a/debug_toolbar/templates/debug_toolbar/base.html +++ b/debug_toolbar/templates/debug_toolbar/base.html @@ -1,43 +1,46 @@ {% load i18n static %} -{% block css %} - - -{% endblock css %} -{% block js %} - -{% endblock js %} -
-
-
    -
  • {% translate "Hide" %} »
    • -
  • - - {% translate "Toggle Theme" %} {% include "debug_toolbar/includes/theme_selector.html" %} - -
    • +
    +
    diff --git a/docs/configuration.rst b/docs/configuration.rst index 2ff363888..a7be8934d 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -439,7 +439,7 @@ could add a **debug_toolbar/base.html** template override to your project: {% block css %}{{ block.super }} diff --git a/docs/panels.rst b/docs/panels.rst index 65024e3c8..ac4ee681f 100644 --- a/docs/panels.rst +++ b/docs/panels.rst @@ -444,14 +444,14 @@ Events .. code-block:: javascript - import { $$ } from "./utils.js"; + import { $$, getDebugElement } from "./utils.js"; function addCustomMetrics() { // Logic to process/add custom metrics here. // Be sure to cover the case of this function being called twice // due to file being loaded asynchronously. } - const djDebug = document.getElementById("djDebug"); + const djDebug = getDebugElement(); $$.onPanelRender(djDebug, "CustomPanel", addCustomMetrics); // Since a panel's scripts are loaded asynchronously, it's possible that // the above statement would occur after the djdt.panel.render event has From dd8351a07e0efb9ebad44670e1c3de5731e296b4 Mon Sep 17 00:00:00 2001 From: Tim Schilling Date: Tue, 2 Dec 2025 21:15:07 -0600 Subject: [PATCH 2/3] Change shadow root element ID for fetching debug element --- debug_toolbar/static/debug_toolbar/js/utils.js | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/debug_toolbar/static/debug_toolbar/js/utils.js b/debug_toolbar/static/debug_toolbar/js/utils.js index 6a32db892..92254f6e3 100644 --- a/debug_toolbar/static/debug_toolbar/js/utils.js +++ b/debug_toolbar/static/debug_toolbar/js/utils.js @@ -76,7 +76,9 @@ function getDebugElement() { // everywhere the element is being selected. A fixed reference // to the element should be avoided because the entire DOM could // be reloaded such as via HTMX boosting. - const root = document.getElementById("djDebugRoot").shadowRoot; + const root = document.getElementById( + "djDebugShadowRootContainer" + ).shadowRoot; return root.querySelector("#djDebug"); } From 23a51b780160ffe8a9600f8636a6d026a021e4ee Mon Sep 17 00:00:00 2001 From: Federico Bond Date: Wed, 10 Dec 2025 17:52:52 +1100 Subject: [PATCH 3/3] Add USE_SHADOW_DOM setting to opt-in to shadow DOM toolbar rendering --- debug_toolbar/settings.py | 1 + debug_toolbar/static/debug_toolbar/css/toolbar.css | 4 ++-- debug_toolbar/static/debug_toolbar/js/utils.js | 7 ++++--- debug_toolbar/templates/debug_toolbar/base.html | 6 +++--- debug_toolbar/toolbar.py | 5 ++++- docs/changes.rst | 2 ++ 6 files changed, 16 insertions(+), 9 deletions(-) diff --git a/debug_toolbar/settings.py b/debug_toolbar/settings.py index ba64c8273..8ba65234b 100644 --- a/debug_toolbar/settings.py +++ b/debug_toolbar/settings.py @@ -30,6 +30,7 @@ def _is_running_tests(): "ROOT_TAG_EXTRA_ATTRS": "", "SHOW_COLLAPSED": False, "SHOW_TOOLBAR_CALLBACK": "debug_toolbar.middleware.show_toolbar", + "USE_SHADOW_DOM": False, "TOOLBAR_LANGUAGE": None, "TOOLBAR_STORE_CLASS": "debug_toolbar.store.MemoryStore", "UPDATE_ON_FETCH": False, diff --git a/debug_toolbar/static/debug_toolbar/css/toolbar.css b/debug_toolbar/static/debug_toolbar/css/toolbar.css index 13b88f5c2..13e591492 100644 --- a/debug_toolbar/static/debug_toolbar/css/toolbar.css +++ b/debug_toolbar/static/debug_toolbar/css/toolbar.css @@ -1,5 +1,5 @@ /* Variable definitions */ -:host { +#djDebug { /* Font families are the same as in Django admin/css/base.css */ --djdt-font-family-primary: "Segoe UI", system-ui, Roboto, "Helvetica Neue", Arial, sans-serif, @@ -13,7 +13,7 @@ "Noto Color Emoji"; } -:host, +#djDebug, #djDebug[data-theme="light"] { --djdt-font-color: black; --djdt-background-color: white; diff --git a/debug_toolbar/static/debug_toolbar/js/utils.js b/debug_toolbar/static/debug_toolbar/js/utils.js index 92254f6e3..0940c8295 100644 --- a/debug_toolbar/static/debug_toolbar/js/utils.js +++ b/debug_toolbar/static/debug_toolbar/js/utils.js @@ -76,9 +76,10 @@ function getDebugElement() { // everywhere the element is being selected. A fixed reference // to the element should be avoided because the entire DOM could // be reloaded such as via HTMX boosting. - const root = document.getElementById( - "djDebugShadowRootContainer" - ).shadowRoot; + let root = document.getElementById("djDebugRoot"); + if (root.shadowRoot) { + root = root.shadowRoot; + } return root.querySelector("#djDebug"); } diff --git a/debug_toolbar/templates/debug_toolbar/base.html b/debug_toolbar/templates/debug_toolbar/base.html index 2c38ed68b..1cd392287 100644 --- a/debug_toolbar/templates/debug_toolbar/base.html +++ b/debug_toolbar/templates/debug_toolbar/base.html @@ -1,6 +1,6 @@ {% load i18n static %} -
    - {% endif %}
    diff --git a/debug_toolbar/toolbar.py b/debug_toolbar/toolbar.py index 0e22c8f06..ce096b78a 100644 --- a/debug_toolbar/toolbar.py +++ b/debug_toolbar/toolbar.py @@ -97,7 +97,10 @@ def render_toolbar(self) -> str: if not self.should_render_panels(): self.init_store() try: - context = {"toolbar": self} + context = { + "toolbar": self, + "use_shadow_dom": self.config["USE_SHADOW_DOM"], + } lang = self.config["TOOLBAR_LANGUAGE"] or get_language() with lang_override(lang): return render_to_string("debug_toolbar/base.html", context) diff --git a/docs/changes.rst b/docs/changes.rst index 948b90dec..7bab177da 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -18,6 +18,8 @@ Pending * Added test to confirm Django's ``TestCase.assertNumQueries`` works. * Fixed string representation of values in settings panel. * Declared support for Django 6.0. +* Added opt-in support for rendering the toolbar in a shadow DOM for better + isolation from the rest of the page. 6.1.0 (2025-10-30) ------------------