Ein technischer Erfahrungsbericht aus der Praxis der Webentwicklung – für alle, die mit Neos CMS Websites programmieren und pflegen.
Ein scheinbar kleines Problem mit großer Wirkung
Wer regelmäßig Websites mit Neos CMS entwickelt, kennt die Flexibilität des Systems. Inhalte, Strukturen und Datenmodelle lassen sich extrem fein steuern – doch gerade diese Freiheit bringt auch Tücken mit sich. Eine davon ist das sogenannte „unsichtbare Boolean-Problem“: Ein neues Feld wird im NodeType definiert, aber Filter und Ausgaben verhalten sich inkonsistent.
In der täglichen Programmierung und Webentwicklung fällt dieses Problem meist erst dann auf, wenn Daten in einer Listenansicht oder über eine EEL-Abfrage gefiltert werden sollen – und plötzlich keine Ergebnisse erscheinen, obwohl Inhalte offensichtlich vorhanden sind.
Das typische Szenario in der Neos-Entwicklung
Ein Entwickler erweitert den NodeType eines Event-Dokuments um eine neue Checkbox, die steuern soll, ob ein Event auf einer bestimmten Website-Seite (zum Beispiel einer „Tanzplattform“) angezeigt wird:
showOnTanz:
type: boolean
defaultValue: false
ui:
label: 'Im Tanzplattform anzeigen'
Danach wird in einer EEL-Abfrage oder einem PHP-Helper gefiltert:
->filter('[showOnTanz=true]')Oder in Fusion:
q(site).find('[instanceof Vendor.Site:Document.Event]').filter('[showOnTanz=true]').get()Das Ergebnis: Keine Events werden angezeigt – obwohl die Checkbox aktiviert wurde. Neue Inhalte verhalten sich korrekt, alte Inhalte dagegen nicht. Ein Rätsel, das selbst erfahrene Entwickler zunächst in die Irre führt.
Die technische Ursache: Default-Werte sind nicht retroaktiv
Neos CMS speichert Properties erst dann in der Datenbank, wenn sie tatsächlich gesetzt werden. Der in der NodeTypes.yaml definierte defaultValue existiert nur auf logischer Ebene – nicht physisch in der Datenbank. Das bedeutet: Für bereits existierende Nodes wird dieses Feld nie angelegt, wenn es nachträglich eingeführt wird.
Bei neuen Nodes greift der Default korrekt. Bei bestehenden Inhalten jedoch ist das Feld showOnTanz schlicht nicht vorhanden in der Tabelle neos_contentrepository_domain_model_nodedata. Filter, die sich auf dieses Property beziehen, laufen ins Leere.
Das Ergebnis: Debug-Ausgaben zeigen zwar bool(true), aber die interne Filterlogik findet keinen Treffer – weil kein gespeicherter Wert existiert.
Typische Fehlversuche bei der Fehleranalyse
Viele Entwickler tappen in dieselben Fallen, bevor sie den wahren Grund finden:
- Verwendung von getProperty('showOnTanz') im Helper oder Template – scheinbar korrekt, aber kein persistenter Wert
- Anpassung des defaultValue in YAML – keine Auswirkung auf bestehende Nodes
- Direkte Abfragen in Fusion – keine Ergebnisse
- Neuerstellung von Caches oder Reindexing – ebenfalls ohne Wirkung
Diese Symptome führen leicht in die Irre, da alles danach aussieht, als würde das Property korrekt gesetzt werden – tatsächlich ist es aber im ContentRepository nie gespeichert worden.
Die Lösung: Eine Node-Migration für bestehende Inhalte
Die nachhaltige Lösung besteht darin, eine Migration auszuführen, die sicherstellt, dass alle bestehenden Nodes dieses Feld erhalten. Damit wird der neue Boolean-Wert auch für alte Inhalte physisch in der Datenbank angelegt.
up:
comments: 'Ensure all Event nodes have showOnTanz set'
filters:
- type: 'NodeType'
nodeType: 'Vendor.Site:Document.Event'
transformations:
- type: 'AddProperty'
property: 'showOnTanz'
value: false
Diese Datei wird in Packages/Sites/Vendor.Site/Migrations/ContentRepository/ abgelegt und per CLI ausgeführt:
./flow node:migrate --version 20251029Nach der Migration sollten folgende Befehle ausgeführt werden:
./flow node:repair
./flow cache:flush
Ab diesem Zeitpunkt steht das Property showOnTanz auch bei älteren Inhalten korrekt zur Verfügung – und Filterausdrücke funktionieren wieder zuverlässig.
Erweiterung der Lösung für komplexe Website-Projekte
In größeren Webentwicklungs-Projekten kann es sinnvoll sein, beim Hinzufügen neuer Properties automatisch eine Migration anzulegen. Das ist besonders wichtig, wenn Inhalte über viele Jahre wachsen oder wenn mehrere Entwickler an einer Website arbeiten. So wird sichergestellt, dass alle Content-Strukturen synchron bleiben.
Auch für künftige Erweiterungen gilt: YAML-Definitionen allein ändern nur die Konfiguration neuer Nodes. Wer bestehende Daten anpassen möchte, benötigt immer eine Migrationslogik – egal, ob Boolean, String oder Relation.
Fazit: Warum Neos CMS technische Präzision erfordert
Das Boolean-Problem zeigt, wie tief Neos CMS intern mit seinem ContentRepository arbeitet. Für Entwickler, Agenturen und Unternehmen bedeutet das: Wer Websites mit Neos programmiert, sollte verstehen, wie Daten gespeichert, interpretiert und gefiltert werden.
Der Fall ist ein Paradebeispiel für präzises Debugging und saubere Datenmodellierung in der Programmierung moderner Websites. Mit der richtigen Migration lässt sich das Problem dauerhaft beheben – stabil, versionssicher und updatefreundlich.
Tipp einer Neos-Agentur: Wenn Sie Ihre Website weiterentwickeln, neue Properties einführen oder komplexe Datenstrukturen in Neos CMS verwalten möchten, planen Sie Migrationen von Anfang an mit ein. Das spart Zeit, Aufwand und garantiert konsistente Inhalte über alle Sprach- und Site-Varianten hinweg.
Unsere Internetagentur München, Econcess, legt einen großen Wert auf ein aufgewecktes Design, um viele Kunden anzusprechen. Wenn Sie nun Interesse an einer Webseite für Ihre Firma haben, melden Sie sich gerne bei uns. Wir sind spezialisiert auf maßgeschneiderte Lösungen und bieten Ihnen professionelle Unterstützung bei der Realisierung Ihrer digitalen Projekte.
