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:

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

```json
{ "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:

```json
{ "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 alles darunter, egal welcher Art.
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, Alias 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 (Divi lässt es zu), antwortet aber mit einer Warnung: der Inhalt zeigt dort nichts oder falsche
   Daten. 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 ä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.
- 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.

## `$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.