Add backend hints for missing Turbo entries

Author: koertho

.docs/build/DECISIONS.md

@@ -449,3 +449,63 @@ Auch Feature 1 erfordert eine Schemaergänzung (FEATURES.md §0.6 ist entspreche
 Das neue Feld in `tl_content` wird durch Contaos reguläre Schema-Migration
 angelegt (Doctrine integer, unsigned, Default 0), wie im Feature-1-Prompt
 explizit verlangt. Keine eigene Migrationsklasse ist nötig.
+
+## D15: Backend-Hinweis bei fehlendem Turbo-Entry (17.09.2026)
+
+Drei `config.onload`-Callbacks prüfen Q&A-Inhaltselemente im Edit-Modus,
+Bühnenseiten im Edit-Modus sowie den Einstieg ins Q&A-Modul. Ein gemeinsamer
+Prüfservice erkennt beide Turbo-Entries über die Konstanten `DEFAULT` und
+`NO_DRIVER`; ein Meldungsservice übersetzt die Info und verhindert doppelte
+Meldungen pro Request. Die notwendige veränderliche Guard-Eigenschaft ist die
+begründete Ausnahme von `readonly`. Ein erfolgreicher Check verbraucht den
+Guard nicht, damit ein späterer fehlender Entry noch gemeldet werden kann.
+
+Alternative `onsubmit`: Ein Hinweis erst nach dem Speichern käme zu spät und
+würde den Moduleinstieg nicht abdecken. Andere Inhaltstypen verlassen den
+Callback vor jeder Modell- oder Schemaabfrage. Composer und Service-Konfiguration
+bleiben unverändert, das Encore-Bundle wird nicht als Klasse referenziert.
+
+### Nachgelesene Belege
+
+Die folgenden Encore-Pfade liegen ausdrücklich im **DDEV-Projekt** unter
+`/home/dev/Kunden/contao/contao_0507/vendor/heimrichhannot/contao-encore-bundle/`:
+
+| Fakt | Pfad |
+| --- | --- |
+| Feldname `encoreEntries` | `src/Dca/EncoreEntriesSelectField.php::NAME_DEFAULT` |
+| `blob NULL`, serialisierte Zeilen mit `entry` und optional `active` | `src/EventListener/DcaField/EncoreEntriesSelectFieldListener.php::onLoadDataContainer()` |
+| Aktiv-Checkbox für beide Tabellen | `contao/dca/tl_layout.php`, `contao/dca/tl_page.php` |
+| Fehlendes oder null `active` gilt als aktiv, sonst PHP-Truthy | `src/Asset/PageEntrypoints.php::generatePageEntrypoints()`; aktueller Nachfolger `src/EntryPoint/EntryPointsBuilder.php::build()` verwendet `active ?? true` |
+| Layout und Seitenkette werden gesammelt | `src/Asset/PageEntrypoints.php::collectPageEntries()`, `src/EntryPoint/EntryPointsBuilder.php::build()` |
+| `addEncore` ist Voraussetzung für die gesamte Seite | `src/Helper/ConfigurationHelper.php::isEnabledOnPage()`; `src/DataContainer/LayoutContainer.php::onLoadCallback()` |
+
+Im Bundle-Repository nachgelesen:
+
+| API | Pfad unter `vendor/` |
+| --- | --- |
+| Turbo-Konstanten | `heimrichhannot/contao-ux-turbo-encore/src/EncoreExtension.php` |
+| Info-Meldung und Adapter-Vorbild | `contao/core-bundle/contao/library/Contao/Message.php::addInfo()`, `contao/core-bundle/src/EventListener/DataContainer/LegacyTemplatesListener.php` |
+| Callback-Attribut, Request- und Record-Zugriff | `contao/core-bundle/src/DependencyInjection/Attribute/AsCallback.php`, `contao/core-bundle/src/EventListener/DataContainer/PreviewLinkListener.php` |
+| Record ist Array oder null | `contao/core-bundle/contao/classes/DataContainer.php::getCurrentRecord()`, `contao/core-bundle/contao/drivers/DC_Table.php::getCurrentRecord()` |
+| Vererbtes Layout und Trail | `contao/core-bundle/contao/models/PageModel.php::findWithDetails()` / `loadDetails()` |
+| Modelle, rohe optionale Felder, Deserialisierung | `contao/core-bundle/contao/models/ArticleModel.php`, `contao/core-bundle/contao/models/LayoutModel.php`, `contao/core-bundle/contao/library/Contao/Model.php::findById()` / `row()`, `contao/core-bundle/contao/library/Contao/StringUtil.php::deserialize()` |
+| Testbare Adapter | `contao/core-bundle/src/Framework/ContaoFramework.php::getAdapter()`, `contao/core-bundle/src/Framework/Adapter.php` |
+
+### Präzisierungen gegenüber dem Prompt
+
+* Ohne `addEncore` im effektiven Layout sind auch Seiten-Entries unwirksam:
+  Die Seitenprüfung gibt deshalb sofort false zurück, statt nur den Layout-Blob
+  zu überspringen. Die globale Prüfung bleibt die spezifizierte Suche nach
+  Konfiguration, ohne Zuordnung sämtlicher Seiten zu Layouts.
+* Der Session-Callback benötigt keinen Datensatz und keinen Edit-Modus; sonst
+  würde die gemeinsame Record-Regel des Prompts den ausdrücklich verlangten
+  Hinweis beim Moduleinstieg verhindern. Ohne Request tut er nichts.
+* `trail` enthält auch die Seite selbst und gegebenenfalls 0. Diese werden
+  übersprungen; die Seite wird zuletzt direkt geprüft.
+* Schema-Spalten werden einmal je globaler Prüfung für **beide** Tabellen
+  geprüft, einschließlich `addencore`. Optionale Modellfelder werden über
+  `row()` gelesen; fehlende Encore-Felder verursachen keine Fehler.
+* `PageEntrypoints` ist im installierten Vendor als deprecated markiert. Der
+  aktuelle `EntryPointsBuilder` bestätigt die verwendete Zeilen-Semantik.
+  Wie §3.3 vorgegeben prüft der Service das Vorhandensein aktiver Zeilen,
+  nicht den fertigen Build oder programmatische Encore-Event-Overrides.

.docs/build/SPEC.md

@@ -1020,3 +1020,13 @@ Die Bühne gruppiert unbeantwortete vor beantworteten Fragen und erhält die
 gewählte Sortierung je Gruppe. Teilnehmer behalten ihre Vote-Sortierung mit
 Text-Badge und ohne Vote-Button an beantworteten Fragen. Geschlossene Sessions
 zeigen Gruppen und Badges ohne Aktionen. Kein Antworttext oder Antwortzeitpunkt.
+
+## Backend-Hinweis zur Turbo-Konfiguration (Feature 3)
+
+Beim Bearbeiten von Q&A-Inhaltselementen und Bühnenseiten wird die wirksame
+Seite auf einen aktiven Turbo-Entry in Layout, Elternseiten oder Seite geprüft.
+Das wirksame Layout muss `addEncore` aktivieren. Im Q&A-Modul sowie bei nicht
+bestimmbarer Seite erfolgt die globale Konfigurationsprüfung. Fehlt ein Entry,
+erscheint höchstens eine übersetzte Info-Meldung pro Request. Andere Element-
+und Seitentypen lösen keine Prüfung aus. Es gibt weder automatische Aktivierung
+noch Frontend-Hinweis oder Build-Prüfung (FEATURES.md §3, Entscheidung D15).

README.md

@@ -32,6 +32,12 @@ head scripts exposing the instance as `window.Turbo`, which the Q&A entry
 reuses instead of bundling a second copy. If neither is active, the Q&A
 JavaScript logs an error to the browser console.
 
+The back end shows an informational hint when editing Q&A content elements or
+stage pages if no Turbo entry is active for that page. The Q&A module also
+checks whether a Turbo entry is configured anywhere in the project. Page-level
+entries require Encore to be enabled in the effective layout (`addEncore`).
+The hint checks configuration only, not the generated Encore build.
+
 Consequence: the host project needs an Encore build (`yarn`/`webpack`). See
 the Encore Bundle documentation for the project setup.
 

src/Asset/TurboEntryAvailability.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HeimrichHannot\QnaBundle\Asset;
+
+use Contao\CoreBundle\Framework\ContaoFramework;
+use Contao\LayoutModel;
+use Contao\PageModel;
+use Contao\StringUtil;
+use Doctrine\DBAL\Connection;
+use HeimrichHannot\ContaoUxTurboEncore\EncoreExtension as TurboEncoreExtension;
+
+final readonly class TurboEntryAvailability
+{
+    public function __construct(private ContaoFramework $framework, private Connection $connection)
+    {
+    }
+
+    public function isActiveForPage(PageModel $page): bool
+    {
+        $page->loadDetails();
+        $layout = $this->framework->getAdapter(LayoutModel::class)->findById($page->layout);
+
+        if (null === $layout || !($layout->row()['addEncore'] ?? false)) {
+            return false;
+        }
+
+        if ($this->containsActiveTurboEntry($layout->row()['encoreEntries'] ?? null)) {
+            return true;
+        }
+
+        foreach ($page->trail as $id) {
+            if ((!\is_int($id) && !\is_string($id)) || (int) $id <= 0 || (int) $id === (int) $page->id) {
+                continue;
+            }
+
+            $parent = $this->framework->getAdapter(PageModel::class)->findById($id);
+            if (null !== $parent && $this->containsActiveTurboEntry($parent->row()['encoreEntries'] ?? null)) {
+                return true;
+            }
+        }
+
+        return $this->containsActiveTurboEntry($page->row()['encoreEntries'] ?? null);
+    }
+
+    public function isActiveAnywhere(): bool
+    {
+        $schema = $this->connection->createSchemaManager();
+        $layoutColumns = $schema->listTableColumns('tl_layout');
+        $pageColumns = $schema->listTableColumns('tl_page');
+
+        if (!isset($layoutColumns['encoreentries'], $layoutColumns['addencore'], $pageColumns['encoreentries'])) {
+            return false;
+        }
+
+        foreach (["SELECT encoreEntries FROM tl_layout WHERE addEncore = '1'", 'SELECT encoreEntries FROM tl_page WHERE encoreEntries IS NOT NULL'] as $sql) {
+            foreach ($this->connection->iterateColumn($sql) as $blob) {
+                if ($this->containsActiveTurboEntry($blob)) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    private function containsActiveTurboEntry(mixed $blob): bool
+    {
+        foreach ($this->framework->getAdapter(StringUtil::class)->deserialize($blob, true) as $row) {
+            if (\is_array($row) && \in_array($row['entry'] ?? null, [TurboEncoreExtension::DEFAULT, TurboEncoreExtension::NO_DRIVER], true) && ($row['active'] ?? true)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}

src/Asset/TurboHintMessenger.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HeimrichHannot\QnaBundle\Asset;
+
+use Contao\CoreBundle\Framework\ContaoFramework;
+use Contao\Message;
+use Contao\PageModel;
+use Symfony\Contracts\Translation\TranslatorInterface;
+
+/** The mutable request guard prevents duplicate hints from multiple callbacks. */
+final class TurboHintMessenger
+{
+    private bool $warned = false;
+
+    public function __construct(private readonly TurboEntryAvailability $availability, private readonly ContaoFramework $framework, private readonly TranslatorInterface $translator)
+    {
+    }
+
+    public function warn(?PageModel $page): void
+    {
+        if ($this->warned) {
+            return;
+        }
+
+        if (null !== $page ? $this->availability->isActiveForPage($page) : $this->availability->isActiveAnywhere()) {
+            return;
+        }
+
+        $this->warned = true;
+        $key = null !== $page ? 'qna.backend.turbo_missing_page' : 'qna.backend.turbo_missing_global';
+        $this->framework->getAdapter(Message::class)->addInfo($this->translator->trans($key, [], 'contao_default'));
+    }
+}

src/EventListener/DataContainer/Content/ConfigOnloadListener.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HeimrichHannot\QnaBundle\EventListener\DataContainer\Content;
+
+use Contao\ArticleModel;
+use Contao\CoreBundle\DependencyInjection\Attribute\AsCallback;
+use Contao\CoreBundle\Framework\ContaoFramework;
+use Contao\DataContainer;
+use Contao\PageModel;
+use HeimrichHannot\QnaBundle\Asset\TurboHintMessenger;
+use Symfony\Component\HttpFoundation\RequestStack;
+
+#[AsCallback(table: 'tl_content', target: 'config.onload')]
+final readonly class ConfigOnloadListener
+{
+    public function __construct(private RequestStack $requestStack, private ContaoFramework $framework, private TurboHintMessenger $messenger)
+    {
+    }
+
+    public function __invoke(DataContainer $dataContainer): void
+    {
+        if ('edit' !== $this->requestStack->getCurrentRequest()?->query->get('act')) {
+            return;
+        }
+
+        $record = $dataContainer->getCurrentRecord();
+        if (null === $record || !\in_array($record['type'] ?? null, ['qna_session_list', 'qna_session_reader'], true)) {
+            return;
+        }
+
+        $page = null;
+        $pid = $record['pid'] ?? null;
+        if ('tl_article' === ($record['ptable'] ?? null) && (\is_int($pid) || \is_string($pid))) {
+            $article = $this->framework->getAdapter(ArticleModel::class)->findById($pid);
+            if (null !== $article) {
+                $page = $this->framework->getAdapter(PageModel::class)->findWithDetails($article->pid);
+            }
+        }
+
+        $this->messenger->warn($page);
+    }
+}

src/EventListener/DataContainer/Page/ConfigOnloadListener.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HeimrichHannot\QnaBundle\EventListener\DataContainer\Page;
+
+use Contao\CoreBundle\DependencyInjection\Attribute\AsCallback;
+use Contao\CoreBundle\Framework\ContaoFramework;
+use Contao\DataContainer;
+use Contao\PageModel;
+use HeimrichHannot\QnaBundle\Asset\TurboHintMessenger;
+use Symfony\Component\HttpFoundation\RequestStack;
+
+#[AsCallback(table: 'tl_page', target: 'config.onload')]
+final readonly class ConfigOnloadListener
+{
+    public function __construct(private RequestStack $requestStack, private ContaoFramework $framework, private TurboHintMessenger $messenger)
+    {
+    }
+
+    public function __invoke(DataContainer $dataContainer): void
+    {
+        if ('edit' !== $this->requestStack->getCurrentRequest()?->query->get('act')) {
+            return;
+        }
+
+        $record = $dataContainer->getCurrentRecord();
+        if (null === $record || 'qna_stage' !== ($record['type'] ?? null)) {
+            return;
+        }
+
+        $id = $record['id'] ?? null;
+        $page = \is_int($id) || \is_string($id) ? $this->framework->getAdapter(PageModel::class)->findWithDetails($id) : null;
+        $this->messenger->warn($page);
+    }
+}

src/EventListener/DataContainer/Session/ConfigOnloadListener.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HeimrichHannot\QnaBundle\EventListener\DataContainer\Session;
+
+use Contao\CoreBundle\DependencyInjection\Attribute\AsCallback;
+use Contao\DataContainer;
+use HeimrichHannot\QnaBundle\Asset\TurboHintMessenger;
+use Symfony\Component\HttpFoundation\RequestStack;
+
+#[AsCallback(table: 'tl_qna_session', target: 'config.onload')]
+final readonly class ConfigOnloadListener
+{
+    public function __construct(private RequestStack $requestStack, private TurboHintMessenger $messenger)
+    {
+    }
+
+    public function __invoke(DataContainer $dataContainer): void
+    {
+        if (null !== $this->requestStack->getCurrentRequest()) {
+            $this->messenger->warn(null);
+        }
+    }
+}