Attach handlers to djDebug instead of document

[scuml]

Attach click handlers to the debug element itself instead of document body. This fixes issues when using libraries that replace the body element without reloading the page like Hotwire Turbo, htmx, and Unpoly.

[tim-schilling]

Doesn't the debug element get dropped when one of these libraries replaces the content of body?

[scuml]

Great observation. There is a tag in Turbo that extract elements and replace them in the page after document is replaced. So adding the following setting makes things work:

DEBUG_TOOLBAR_CONFIG = {
    "ROOT_TAG_EXTRA_ATTRS": "data-turbo-permanent"
}

I tried a number of other approaches to work around this, but this change was the straightforward & reliable way to ensure the proper behavior.

[tim-schilling]

Let's step back.

This fixes issues when using libraries that replace the body element without reloading the page like Hotwire Turbo, htmx, and Unpoly.

Can you clarify these issues? I know what this change is doing, but the PR is lacking information on why we need it.

[scuml]

ScreenFlow.mp4

Best described with an example.

[tim-schilling]

I appreciate your efforts, but videos are not helpful when looking at the project historically. We can't search what's said in the video versus the text in comments / the issue itself.

[tim-schilling]

It may be more helpful to create an additional test page within the example app for turbo. I'm not sure why our current implementation works for htmx, but not turbo.

[scuml]

I can add that.

It looks like htmx may replace individual elements, and while Turbo does the same for form submissions and websocket data, it replaces the entire document element for a page transition. It will first extract elements with the attribute data-turbo-permanent, and reinsert them on the page. So if we use the setting I mentioned above, along with this change, it allows django-toolbar to operate as expected with this library.

[tim-schilling]

This unfortunately breaks the integration with htmx. I think we may need to rework our solution entirely to better support these types of libraries.

[scuml]

Verified the htmx integration was less than perfect even before - with the handle click events also getting lost when closing and reopening the toolbar.

I think I've got it solved with my latest changes to the branch. Both expect users of html-swapping libraries to add to the ROOT_TAG_EXTRA_ATTRS setting. hx-preserve for htmx, and data-turbo-permanent for Turbo. These will retain the toolbar and handle across page loads. Custom javascript listeners are no longer needed and have been removed from the htmx example. Docs have been updated with this information as well.

@tim-schilling Thanks for pushing back on this to make sure it works for as many users as possible.

[scuml]

@tim-schilling Could you give this a review this week?

[matthiask]

I didn't try it out, just commenting here for now.

[tim-schilling]

Thank you @scuml for working through this. I like how it ended up. I did one last update to the docs to start linking to various parts more.

[tim-schilling]

If you have time, can you rebase on main? Otherwise I'll try to get to it over the weekend.

[scuml]

Good to go. Had to remove the enchant install as it was causing CI to fail, however, it doesn't appear needed.

[tim-schilling]

@scuml it can be a little tricky rebasing on main. You need to make sure your version of main is up to date with the upstream's (https://github.com/jazzband/django-debug-toolbar/) before doing the rebase (or merge in your case).

I've gone ahead and squashed the commits in this PR and got it inline with main. Thank you for your work on this PR and advancing the toolbar!

[scuml]

You're welcome. Glad to contribute. Thanks for leading as maintainer.