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!

[stevepiercy]

Suggested change

	When sending an AJAX request to normal browser views in Plone, Plone will respond with an HTML page which normally is also transformed via the Diazo theming engine.
	In some cases this is an unnecessary overhead, if you only want to inject a small snippet of HTML into the page.
	When sending an AJAX request to normal browser views in Plone, Plone prepares a response as an HTML page, then normally transforms it via the Diazo theming engine.
	In some cases this is unnecessary overhead, such as when you want to inject a small snippet of HTML only into the page.

[stevepiercy]

Suggested change

	````{versionadded} plonetheme.barceloneta 3.3.0
	In Plone's standard theme plonetheme.barceloneta 3.3.0 the `ajax_load` theme parameter to disable Diazo was added.
	If you use this theme, the next steps are obsolete.
	````
	```{versionadded} plonetheme.barceloneta 3.3.0
	In Plone Classic UI's standard theme, `plonetheme.barceloneta` version 3.3.0, the `ajax_load` theme parameter to disable Diazo was added.
	If you use this theme version 3.3.0 or later, then the next steps are obsolete.
	```

[stevepiercy]

@thet I'd say everyone uses this theme in Classic UI, so let's qualify it with the version number. I think this revision is correct, but please verify. Thank you!

[stevepiercy]

Suggested change

	- For a programmatical way, see [(Re)Introduce the ajax_load theme parameter and skip diazo theming, if set. `plone/plonetheme.barceloneta` #404](https://github.com/plone/plonetheme.barceloneta/pull/404).
	- For a programmatic way, see [(Re)Introduce the ajax_load theme parameter and skip diazo theming, if set. `plone/plonetheme.barceloneta` #404](https://github.com/plone/plonetheme.barceloneta/pull/404).

[stevepiercy]

Suggested change

	You can fully disable Diazo and plone.app.theming based themes by setting the `plone.app.theming.interfaces.IThemeSettings.enabled` registry entry to `False`.
	You can fully disable Diazo and `plone.app.theming` based themes by setting the `plone.app.theming.interfaces.IThemeSettings.enabled` registry entry to `False`.

[petschki]

technically 👍