WP-LIT-MCP/docs/guides/divi-placeholders.md

Platzhalter für Divi-Inhalte

Platzhalter stehen allein im Wert (nicht mitten im Text) und werden beim Speichern in Divis eigene Verweise übersetzt. So bleibt die Seite mit dem Designsystem verbunden: ändert sich die Primärfarbe, ändert sich auch der Button.

Platzhalter	Bedeutung
{{color:primary}}, secondary, heading, body, link	die fünf Theme-Farben
{{color:<Name>}}	eigene globale Farbe (Name wie in lit-divi-design-system); neue Farben legt lit/divi-colors-set an und sie gelten sofort als Platzhalter
{{var:<Name>}}	globale Variable (Zahl, Text, Bild, Link, Schrift); neue legt lit/divi-variables-set an
{{font:heading}}, {{font:body}}	Theme-Schrift für Überschriften bzw. Fließtext (die Theme-Optionen heading_font und body_font, siehe divi-design-system)
{{post:title}}, excerpt, date, modified, author, url, featured_image, categories, tags	dynamischer Inhalt des angezeigten Beitrags
{{field:<meta_key>}}	dynamischer Inhalt aus einem Feld (Pods/Meta), z. B. {{field:telefon}}
{{loop:<Option>}}, z. B. {{loop:post_date}}	Inhalt des aktuellen Treffers einer Divi-Schleife (Option ohne loop_); nur in Modulen innerhalb einer Schleife, siehe „Schleifen-Inhalte“
{{link:<ID>}}	Link auf einen anderen Eintrag (Seite, Beitrag …), z. B. {{link:42}} – nur in Link-Feldern; Divi setzt beim Anzeigen die aktuelle Adresse ein, also auch für Entwürfe, die erst später veröffentlicht werden
"preset": "<Name>" oder ["<Name>", …], "group_presets": {…}	Modul-Preset bzw. Stapel und Gruppen-Presets (keine Platzhalter, sondern eigene Felder, siehe divi-shortform)

Beispiele:

{ "type": "button", "text": "Anrufen", "url": "{{field:telefon_link}}",
  "attrs": { "button.decoration.background": { "desktop": { "color": "{{color:primary}}" },
                                               "hover":   { "color": "{{color:Nachtblau}}" } } } }

{ "type": "heading", "text": "{{post:title}}", "level": "h1" }

Unbekannte Namen lehnt das Werkzeug ab und nennt die vorhandenen; ist ein Name doppelt vergeben, statt des Namens die ID aus lit-divi-design-system angeben (z. B. {{color:gcid-…}}). Felder, deren Schlüssel mit _ beginnt (geschützte Meta-Daten), sind nicht erlaubt.

In Link-Feldern (url, button_url …) für interne Links immer {{link:<ID>}} verwenden statt fester Adressen wie /?page_id=…. Der Eintrag muss existieren und für das Konto lesbar sein; Einträge im Papierkorb, automatische Entwürfe, Einträge der Divi-Bibliothek und Medien (Anhänge – dafür die Adresse aus der Mediathek) lehnt das Werkzeug ab – wie eine unbekannte ID –, ebenso {{link:…}} außerhalb von Link-Feldern. Solange das Ziel ein Entwurf oder privat ist, zeigt Divi Besuchern nur die Adresse ?page_id=<ID> (kein Titel); nach dem Veröffentlichen die normale Adresse. Sonst nimmt ein Link-Feld jeden dynamischen Inhalt an; sinnvoll sind nur Werte, die eine Adresse ergeben ({{post:url}}, ein Feld mit einer URL, eine Link-Variable).

Dieselben Regeln gelten für die Vollform post_link_url_<Typ> mit post_id: das Ziel muss lesbar sein, darf nicht im Papierkorb liegen, kein Anhang und kein Bibliothekseintrag sein und muss genau den Typ im Namen haben (post_link_url_page nur für Seiten). {{link:<ID>}} wählt den passenden Namen selbst.

Welche dynamischen Quellen und Felder es für einen Inhaltstyp gibt, liefert lit/divi-dynamic-sources (über mcp-adapter-execute-ability): Divis Quellen mit Platzhalter und die Felder, die sich als {{field:…}} eignen. Gelistet werden nur textartige Felder; Beziehungs- und Dateifelder (Divi zeigt sie nur als IDs), Tabellen-Felder und Felder unbekannten Typs stehen mit Grund unter omitted. Bei Auswahlfeldern zeigt Divi den gespeicherten Wert, nicht die Beschriftung.

Schleifen-Inhalte

Ein Element mit eingeschalteter Divi-Schleife (Abschnitt, Zeile, Spalte, Gruppe oder Modul; im Divi-Builder unter „Schleife“) wiederholt sich je Treffer der Abfrage. Module darin zeigen mit loop_*-Inhalten Daten des jeweiligen Treffers, z. B. das Datum des Beitrags. LIT MCP legt keine Schleifen an und stellt ihre Abfrage nicht ein: das macht der Nutzer im Divi-Builder. Danach setzt der KI-Assistent die Inhalte:

{ "type": "text", "content": "{{loop:post_date}}" }

{{loop:<Option>}} nimmt den Namen der Option ohne loop_ ({{loop:post_date}} schreibt loop_post_date) und steht wie jeder Platzhalter allein im Wert. Einstellungen wie ein Datumsformat gibt es nur in der Vollform ($variable({…})$ mit settings, z. B. "date_format": "custom", "custom_date_format": "d.m.Y" – Divis Auswahl hat kein deutsches Format). Welche Optionen ein Element anbietet, liefert lit/divi-dynamic-sources mit post_id und node (siehe unten).

Die Art der Schleife bestimmt die Optionen:

Schleife (Abfrage)	Optionen
Beiträge (Beitragstypen, aktuelle Seite)	loop_post_*, z. B. Titel, Auszug, Datum, Autor, Beitragsbild, Link, Kategorien oder Schlagwörter (loop_post_terms); Feld eines Beitrags: loop_post_meta_key_manual_custom_field
Terme (Taxonomien)	loop_term_*, z. B. Name, Beschreibung, Anzahl, Link; Feld: loop_term_meta_key_manual_custom_field
Benutzer (Rollen)	loop_user_*, z. B. Name, E-Mail, Avatar, Beschreibung; Feld: loop_user_meta_key_manual_custom_field
Menü	loop_menu_*, z. B. Text, Link, Beschreibung

Regeln und Fehlermeldungen:

1. Der Schleifen-Kontext ergibt sich aus der Seite: das Modul selbst oder das nächste Element über ihm, dessen Schleife eingeschaltet ist (Desktop-Einstellung „Schleife ein“). Bei verschachtelten Schleifen gilt die innerste für alle Optionen außer den Feld-Optionen (loop_*_meta_key_manual_custom_field): Die müssen zur Art jeder eingeschalteten Schleife in der Kette passen, denn eine leere innere Schleife übergibt den Inhalt an die äußere, und die liest das Feld beim Objekt mit der ID ihres eigenen Eintrags. Ein Beitrags-Feld in einer Beitrags-Schleife innerhalb einer Term-Schleife ist deshalb abgelehnt. Die Abfrageart liest das Werkzeug wie Divi (Kleinschreibung, nur a-z 0-9 _ -; terms zählt als Terme, users als Benutzer).
2. Ohne Schleife lehnt das Werkzeug jeden loop_*-Inhalt ab: Schleifen-Inhalt "loop_post_date" braucht eine Divi-Schleife in diesem Modul oder einem übergeordneten Element (Abschnitt, Zeile, Spalte, Gruppe). Dann das Modul in das Schleifen-Element setzen (parent = die Spalte bzw. das Element mit der Schleife) oder den Nutzer bitten, die Schleife im Divi-Builder einzuschalten.
3. Passt die Option nicht zur Art der Schleife, steht in der Meldung: … passt nicht zur Schleife dieses Elements (Typ: Terme). (Typ: Beiträge, Terme, Benutzer oder Menü). Eine Option der passenden Art wählen. Das ist eine Sicherheitsgrenze, kein Schönheitsfehler: Divi liest die Feld-Optionen in einer Term-, Benutzer- oder Menü-Schleife sonst bei dem Objekt mit derselben ID und gäbe fremde Daten aus. Nie umgehen. Bei einer nicht unterstützten Schleife (ACF-Wiederholungsfeld oder leere Art) nennt die Meldung statt des Typs die rohe Abfrageart der Schleife; in solchen Schleifen ist jede loop_*-Option abgelehnt.
4. Die Feld-Optionen (loop_*_meta_key_manual_custom_field) gibt es nur in der Vollform; für den Schlüssel gelten dieselben Regeln wie bei {{field:<meta_key>}} (kein Schlüssel mit _ am Anfang).
5. Vor dem Setzen lesen: lit/divi-dynamic-sources mit post_type, post_id und node (Pfad-ID des Moduls aus lit-divi-outline) nennt zusätzlich die loop_*-Optionen, die zur Schleife dieses Knotens passen; liegt der Knoten in keiner Schleife, kommt stattdessen der Hinweis „kein Schleifen-Kontext“. Ohne post_id und node liefert das Werkzeug wie bisher keine Schleifen-Optionen.
6. lit-divi-move erlaubt das Verschieben von Schleifen-Inhalt aus der Schleife heraus oder in eine Schleife anderer Art oder unter eine äußere Schleife anderer Art (Divi lässt es zu), antwortet aber mit einer Warnung: der Inhalt zeigt dort nichts oder falsche Daten (bei einer nicht unterstützten Schleife: Daten eines anderen Objekts). Warnung dem Nutzer nennen, Modul zurückschieben oder den Inhalt neu setzen.
7. lit-divi-update warnt ebenso, wenn ein Update die Art der Schleife eines Elements oder einer äußeren Schleife ändert oder die Schleife ausschaltet (Art wird „keine“) und darunter unveränderte Schleifen-Inhalte stehen.
8. lit-divi-insert lehnt einen Aufruf ab, in dem irgendwo ein neues Element mit eigener Schleife und irgendwo Schleifen-Inhalt vorkommt (die Schleife gilt erst nach dem Speichern): erst das Element mit Schleife einfügen, dann die Inhalte mit parent = dieses Element in einem zweiten Aufruf.

Grenzen (bewusst nicht gelöst; dem Nutzer sagen, statt zu umgehen):

• Die Prüfung liest die Schleife aus den Attributen des Moduls und seiner Vorfahren. Eine Schleife, die nur über ein Preset eingeschaltet ist, erkennt sie nicht; dann Schleifen-Inhalte abgelehnt – der Nutzer schaltet die Schleife am Element selbst ein.
• Der Zwei-Aufruf-Weg wird nicht verhindert, nur gemeldet: Schleifen-Inhalte (z. B. ein Beitrags-Feld) in einer Beitrags-Schleife einfügen und danach die Art der Schleife ändern oder das Modul in eine Schleife anderer Art verschieben. Das Werkzeug antwortet nur mit einer Warnung (Divis eigener Builder erlaubt dasselbe), obwohl Divi dann Felder eines anderen Objekts mit derselben ID ausgeben kann; die Warnung dem Nutzer nennen und nicht ignorieren.
• Globale Module ([global <ID>]) haben keinen Schleifen-Kontext; loop_* dort ist abgelehnt.
• lit-content-create und Theme-Builder-Vorlagen kennen keinen Schleifen-Kontext: erst die Seite mit Schleife anlegen (Nutzer im Divi-Builder), dann die Inhalte mit lit-divi-insert setzen.
• Beim Kopieren von Schleifen-Containern samt Inhalt (lit/divi-node-copy, Bibliothek) bleiben Schleifen-Inhalte für Konten ohne unfiltered_html abgelehnt; ein Administrator oder der Divi-Builder erledigt das.
• Offene Grenze (Audit L3): Konten mit unfiltered_html kopieren Schleifen-Container samt Inhalt (lit/divi-node-copy, lit-library-insert mit Kopie) und globale Instanzen ohne Prüfung der Schleifen-Art; ein Meta-Schlüssel-Feld kann so unter eine Schleife anderer Art geraten und Daten eines anderen Objekts mit derselben ID zeigen (Folge wie beim Zwei-Aufruf-Weg oben). Nach einem Kopieren die Schleifen-Art prüfen und dem Nutzer nennen.
• Schleifen über ACF-Wiederholungsfelder (repeater_…) unterstützt LIT MCP nicht.
• Das Attribut module.advanced.loop lässt sich über attrs schreiben; Schleifen ein- oder auszuschalten ändert den Kontext aller Module darunter und geschieht nur auf ausdrücklichen Wunsch. Abfrage und Anzahl gehören in den Divi-Builder.
• Rechte-Grenze beim Schreiben von module.advanced.loop (auch beim Kopieren): eine eingeschaltete Benutzer-Schleife (user_roles) braucht list_users; eine Beitrags-Schleife ohne subTypes, mit any, attachment oder nur unbekannten Typen braucht read_private_posts, weil Divi dann auch private Beiträge abfragt. Fehlt das Recht, lehnt das Werkzeug ab: konkrete Beitragstypen (z. B. post) wählen oder den Nutzer die Schleife im Divi-Builder einstellen lassen. Geprüft wird nur die Desktop-Einstellung; eine über ein Preset eingeschaltete Schleife sieht die Prüfung nicht.

$variable-Werte

In lit-divi-node-get erscheinen die übersetzten Verweise als $variable({…})$. Diese Werte unverändert lassen oder wieder durch einen Platzhalter ersetzen. $variable-Verweise werden geparst, geprüft und vom Plugin neu erzeugt: erlaubt sind nur ganze Werte mit bekannten Farben, Variablen, Schriften und dynamischen Quellen; Zusatztexte davor/danach (before/after) werden bereinigt; alles andere (z. B. ein Verweis mitten im Text, eigenes HTML-Ausgeben von Feldern) lehnt das Werkzeug mit validation_failed ab.

Unberührte Teile der Seite bleiben dabei byte-identisch. Ausnahme: Divi selbst normalisiert Seiten mit eigenen HTML-/Attribut-Feldern beim Speichern – nur wenn die Seite noch nicht in Divis eigener gespeicherter Form vorliegt (z. B. importierter oder direkt in die Datenbank geschriebener Inhalt); über den Divi-Builder oder LIT MCP gespeicherte Seiten betrifft das praktisch nie; die Antwort warnt dann, dass der Inhalt beim Speichern verändert wurde, und die neue tree_rev gilt.