Document how to disable diazo for ajax requests and completly.

[thet]

Documentation of a change introduced in plone/plonetheme.barceloneta#404

---

📚 Documentation preview 📚: https://plone6--1961.org.readthedocs.build/

[Copilot]

Pull Request Overview

Updates the Diazo theming documentation to explain how to:

• Disable Diazo transformations on AJAX requests via the ajax_load parameter and <notheme> rule.
• Completely disable Diazo by setting the X-Theme-Disabled header in a request event subscriber.

[stevepiercy]

@thet I read all the related PRs and issues to better understand the change, but I wasn't clear about current behavior. Now I have questions.

1. In Plone 6.0 and 6.1, was it possible to disable Diazo?
2. To which minor versions of Plone do these additions in Plone 6 documentation apply?

Please let me know, then I can start a review. Thank you!

[thet]

@stevepiercy the docs I added actually apply to all versions plone.app.theming - which uses Diazo. It even applies to Plone 5.

The changes in the Barceloneta PR only re-add Diazo disabling for ajax requests, which was present in Plone 5 but fell out somehow while migrating the codebase to Plone 6.
The documentation shows how to do the same change like in this PR for own themes where the ajax_load parameter is yet not used.

And the CMFPlone PR tries to guess if a AJAX request is present and sets the ajax_load parameter automatically - up until now we had to add it manually in links where we wanted Diazo being disabled and the ajax main template being used. But the idea in the PR is that almost all AJAX requests do not need a full page rendering and do not need Diazo. But I will document that behavior in another PR.

There is one bold claim though:

Also, in Plone 6.2 the ajax_load parameter will automatically be added to the request for all AJAX requests.

The PR is not yet merged and actually it tries to guess if there is a AJAX request and there is no guarantee that every AJAX request is detected as such.
Not sure, if I should remove a bit of confidence in this quoted statement above?

[stevepiercy]

The changes in the Barceloneta PR only re-add Diazo disabling for ajax requests, which was present in Plone 5 but fell out somehow while migrating the codebase to Plone 6.

I'm still having a hard time following the changes. Is this accurate?

• 6.0.0: Unintentionally dropped support to disable Diazo for AJAX requests.
• 6.0.16(?), 6.1.2(?), and 6.2.0 (when released): Restored support to disable Diazo for AJAX requests.

We'll need to add some MyST admonitions as appropriate.

```{versionadded} Plone 1.2.3
Explanation of the new feature.
```

```{versionchanged} Plone 1.2.3
Explanation of the change.
```

```{versionremoved} Plone 1.2.3
Explanation of the removal.
```

This gives readers the context they need to understand for which versions of Plone this new documentation applies.

And the plone/Products.CMFPlone#4169 tries to guess if a AJAX request is present and sets the ajax_load parameter automatically - up until now we had to add it manually in links where we wanted Diazo being disabled and the ajax main template being used.

What kind of parameter is ajax_load? HTTP request, Python function, or just a plain old parameter? The new docs don't make it clear.

There is one bold claim though:

That was another thing that confused me.

First, I think it's great that you were the first person to document a feature in Plone 6.x before it was released. That's never happened before.

The claim must be accurate, not bold or hopeful. Consider it as a contract with the reader. We could say that it covers scenarios X and Y, but there may be other unknown scenarios that it doesn't cover.

[thet]

@stevepiercy I think we do not need to annotate the docs I added with version compatibility notes. Just because it documents how to disable Diazo which was possible since I can remember.

The related change in barceloneta only re-adds the disabling diazo transforms for ajax requests to that specific theme.

But it's good to know how to do these version annotations.

I made another commit which hopefully makes some things clearer.

[stevepiercy]

@thet I reorganized and rewrote the content somewhat. Would you please take a look at it to make sure I didn't mess up anything? Thank you!

[stevepiercy]

Link to preview changed docs:

https://plone6--1961.org.readthedocs.build/classic-ui/theming/diazo.html#disabling-diazo-for-ajax-requests

[stevepiercy]

A few MyST syntax and grammar fixes. Please verify that I didn't mess up the qualification for which version the instructions apply. Thank you!

[petschki]

technically 👍

[davisagli]

@thet From what I can see, this is almost ready, but waiting for you to apply Steve's suggestions.

[thet]

@davisagli @stevepiercy tnx for the heads up and the corrections! This slipped out of my attention while being on vacation early August. I took over all suggestions and will merge as soon as the the tests go green.

[stevepiercy]

@thet thanks for wrapping this up. I really appreciate it.