From b98f45c4512e1201bcc98eeade84cfa7d71af080 Mon Sep 17 00:00:00 2001
From: falkgeist <falkvonfreigeist@gmail.com>
Date: Thu, 21 May 2026 12:09:20 +0200
Subject: [PATCH 1/2] Add guide for custom Stimulus controllers

---
 .../dev/guides/adding-stimulus-controllers.md | 91 +++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 docs/dev/guides/adding-stimulus-controllers.md

diff --git a/docs/dev/guides/adding-stimulus-controllers.md b/docs/dev/guides/adding-stimulus-controllers.md
new file mode 100644
index 000000000..a5b053d78
--- /dev/null
+++ b/docs/dev/guides/adding-stimulus-controllers.md
@@ -0,0 +1,91 @@
+---
+title: "Adding Stimulus Controllers"
+description: "How to add custom Stimulus controllers for the back end."
+aliases:
+  - /guides/adding-stimulus-controllers/
+---
+
+Since Contao 5 now uses Turbo and Stimulus for the backend, sometimes it might not be enough to register JS assets for the backend as described under [Adding Backend assets][AddingBackendAssets], especially when listening for the `DOMLoaded` event.
+
+In this case it might be necessary to add a custom Stimulus controller.
+
+The following example assumes:
+- You're using [Webpack Encore][SymfonyWebpackEncore] for asset management.
+- You want to add code for a custom widget.
+
+{{% notice info %}}
+This guide is meant for bundle development.
+{{% /notice %}}
+
+### Adding a custom Stimulus controller
+
+```js
+// assets/controllers/my-custom-widget-controller.js
+import { Controller } from "@hotwired/stimulus";
+
+export default class MyCustomWidgetController extends Controller {
+    connect() {
+        // do your stuff
+    }
+    
+    disconnect() {
+        this.#cleanup();
+    }
+    
+    beforeCache() {
+        this.#cleanup();
+    }
+    
+    #cleanup() {
+        // revert the markup before caching and when disconnecting
+    }
+    
+    
+}
+```
+
+### Adding your Stimulus application
+
+```js
+// assets/backend.js
+import { Application } from "@hotwired/stimulus";
+import MyCustomWidgetController from "./controllers/my-custom-widget-controller";
+
+const application = Application.start();
+application.register("my-vendor-prefix--my-custom-widget", MyCustomWidgetController);
+
+// Call the beforeCache() function on all controllers implementing it. This
+// allows controllers to tear down things before the page gets put into cache.
+// Note that Stimulus' disconnect() function will not fire at this point and
+// thus cannot be used for this task.
+document.documentElement.addEventListener('turbo:before-cache', (e) => {
+    for (const controller of application.controllers) {
+        if ('function' === typeof controller.beforeCache) {
+            controller.beforeCache(e);
+        }
+    }
+});
+```
+
+### Registering your Stimulus application
+
+```json
+// package.json
+{
+  …
+  "devDependencies": {
+    "@hotwired/stimulus": "^3.2",
+    // any other dependencies you need for your controller/application
+  },
+  …
+}
+```
+
+Read more about developing Stimulus controllers [here][StimulusControllers].
+
+Regarding `#cleanup()` and `beforeCache()`, also check the notes on idempotency under [Turbo-compatible Stimulus controllers][StimulusBackend]
+
+[AddingBackendAssets]: /guides/adding-back-end-assets
+[SymfonyWebpackEncore]: https://symfony.com/doc/current/frontend/encore
+[StimulusControllers]: https://stimulus.hotwired.dev/handbook/introduction
+[StimulusBackend]: /internals/_stimulus-backend
\ No newline at end of file

From e37823a39e8735ff73170806444665dab61f599a Mon Sep 17 00:00:00 2001
From: falkgeist <falkvonfreigeist@gmail.com>
Date: Thu, 21 May 2026 12:22:27 +0200
Subject: [PATCH 2/2] Wrong event name

---
 docs/dev/guides/adding-stimulus-controllers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/dev/guides/adding-stimulus-controllers.md b/docs/dev/guides/adding-stimulus-controllers.md
index a5b053d78..89f2703bb 100644
--- a/docs/dev/guides/adding-stimulus-controllers.md
+++ b/docs/dev/guides/adding-stimulus-controllers.md
@@ -5,7 +5,7 @@ aliases:
   - /guides/adding-stimulus-controllers/
 ---
 
-Since Contao 5 now uses Turbo and Stimulus for the backend, sometimes it might not be enough to register JS assets for the backend as described under [Adding Backend assets][AddingBackendAssets], especially when listening for the `DOMLoaded` event.
+Since Contao 5 now uses Turbo and Stimulus for the backend, sometimes it might not be enough to register JS assets for the backend as described under [Adding Backend assets][AddingBackendAssets], especially when listening for the `DOMContentLoaded` event.
 
 In this case it might be necessary to add a custom Stimulus controller.