WP-LIT-MCP/docs/guides/theme-builder.md

# Divi Theme Builder

Der Theme Builder legt fest, wie Kopfzeile, Inhalt und Fußzeile für bestimmte Seiten aussehen – z. B. für alle
Einträge eines eigenen Inhaltstyps. Eine **Vorlage** hat Bedingungen („gilt für alle Personen“) und bis zu drei
**Layouts** (Kopfzeile, Inhalt, Fußzeile). Die **Standardvorlage** gilt überall, wo keine andere greift; ihre
Kopf- und Fußzeile heißen „global“, weil andere Vorlagen sie mitbenutzen.

## Grundregel: nichts wird ohne Freigabe sichtbar

- Neue Vorlagen legt LIT MCP immer **deaktiviert** an – Besucher sehen nichts davon.
- Aktivieren und Deaktivieren gibt es nur mit `lit/tb-activate`, und immer so: Probelauf (Bedingungen, Layouts,
  andere aktive Vorlagen mit denselben oder verwandten Bedingungen unter `overlaps`/`possible_overlaps`) →
  Nutzer fragen → dieselbe Anfrage mit `confirm: true`.
- Auch alles andere, was Besucher sofort sähen, ist zuerst ein Probelauf (`confirm_required`) und braucht
  `confirm: true`: Bedingungen einer aktiven Vorlage ändern (`lit/tb-assign`) und ein Layout ändern, das eine
  aktive Vorlage zeigt (die `lit-divi-…`-Werkzeuge; die Antwort nennt die Vorlagen unter `templates`, solche
  ohne Berechtigung nur als Anzahl `hidden_templates`). Vor dem
  Speichern eines sichtbaren Layouts entsteht eine Revision (wiederherstellbar über `restore_url`, siehe
  „Rückgängig machen“); sind Revisionen abgeschaltet, eine Sicherungskopie im Papierkorb (`backup_id`).
- `lit/divi-replace-text` ändert sichtbare Layouts nicht; solche Änderungen mit `lit-divi-update` und
  `confirm: true` vornehmen.
- Die Standardvorlage ändert LIT MCP nicht (nur im Theme Builder).

## Werkzeuge (über `mcp-adapter-execute-ability`)

- `lit/tb-list`: alle Vorlagen mit `enabled`, `live` (für Besucher wirksam), `status`, Bedingungen (`use_on`,
  `exclude_from` und Beschriftungen), Layouts (`id`, Titel, `shared_with` = andere Vorlagen mit demselben
  Layout) und `template_rev`. `template_id`: nur diese Vorlage. `conditions: true` liefert alle Bedingungen,
  die Divi anbietet; eine ID, die auf „:“ endet, braucht ein Objekt am Ende, z. B.
  `singular:post_type:page:id:42`. `detached` zeigt Vorlagen, die ein Speichern im Theme Builder entfernt hat
  (siehe unten, höchstens 50 je Aufruf); `draft_pending` zeigt ungespeicherte Änderungen im Theme Builder. Eine
  aktive Vorlage, die nicht veröffentlicht ist (z. B. im Papierkorb), lässt sich nur deaktivieren.
- `lit/tb-create-template`: `title`, je Bereich (`header`, `body`, `footer`) `source`:
  `"new"` (neues Layout; optional `nodes` wie bei `lit-divi-insert` und `title`), `"global"` (Kopf-/Fußzeile
  der Standardvorlage mitbenutzen; nicht für `body`), `"default"` (nichts Eigenes, Standard bei fehlender
  Angabe) oder `"hidden"` (Bereich ausblenden). Optional `use_on`/`exclude_from`. Alles oder nichts: schlägt
  ein Schritt fehl, entfernt LIT MCP alles wieder. Antwort: `template_id`, `template_rev`, `enabled: false`,
  `layouts`.
- `lit/tb-assign`: Bedingungen ersetzen (`template_id`, `template_rev`, `use_on`). Fehlt `exclude_from`,
  bleiben die bisherigen Ausnahmen; `[]` entfernt sie. Der Probelauf einer aktiven Vorlage zeigt vorher/nachher
  (`before`, `after`) und Überschneidungen. Die Antwort nennt die bisherigen Bedingungen unter `previous`.
- `lit/tb-activate`: `enabled: true` oder `false` (`template_id`, `template_rev`). Deaktivieren ist der
  schnelle Weg zurück. Zum Aktivieren müssen alle Layouts der Vorlage noch aktiv sein.
- Layouts bearbeiten: `lit-divi-outline`, `lit-divi-node-get`, `lit-divi-insert`, `lit-divi-update`,
  `lit-divi-move`, `lit-divi-delete` … mit der Layout-ID als `post_id` (aus `lit/tb-list`). Benutzt eine
  andere Vorlage dasselbe Layout (`shared_with`), wirkt die Änderung auch dort. Das Modul „Beitragsinhalt“
  (`post-content`) gibt es nur im Inhalt-Layout, nicht in Kopf- oder Fußzeile.

## Bedingungen

Erlaubt sind nur die Bedingungen, die Divi selbst anbietet (`lit/tb-list` mit `conditions: true`), höchstens 50
je Liste. Ein Objekt am Ende (Seite, Beitrag, Begriff, Person) muss existieren und für das Konto lesbar bzw.
zuweisbar sein; sonst lautet die Antwort wie bei einer unbekannten ID. Bedingungen für Autoren
(`archive:user:id:…`) verlangen das Recht, Benutzer aufzulisten (`list_users`) – strenger als Divi. Bedingungs-IDs
bestehen nur aus Buchstaben, Ziffern, `_`, `:` und `-`; eine Rolle, deren Kennung andere Zeichen enthält (manche
Rollen-Plugins), dann im Divi Theme Builder setzen.

## Felder im Inhalt-Layout (Dynamic Content)

Im Inhalt-Layout zeigen Platzhalter die Daten des jeweiligen Eintrags: `{{post:title}}`, `{{post:excerpt}}`,
`{{post:date}}` und Felder als `{{field:<Schlüssel>}}`. Welche Felder ein Inhaltstyp hat und welche Divi als Text
zeigt, liefert `lit/divi-dynamic-sources` mit `post_type`. Nur textartige Felder eignen sich: Bei Auswahlfeldern
zeigt Divi den gespeicherten Wert, nicht die Beschriftung; Beziehungs- und Dateifelder zeigen nur IDs, Pods mit
Tabellen-Speicherung gar nichts.

LIT MCP prüft die Felder eines geänderten Inhalt-Layouts gegen die Inhaltstypen aus den Bedingungen
(`singular:post_type:<typ>:…`) der Vorlagen, die das Layout benutzen, und warnt (`warnings`) – gespeichert wird
trotzdem. Das gilt für die Kurzform `{{field:…}}` und für Felder, die im Divi-Builder über „Benutzerdefiniertes
Feld“ gewählt wurden. Bei einem sichtbaren Layout stehen die Warnungen schon im Probelauf. Ohne solche Bedingung
bleiben die Felder ungeprüft (die Antwort sagt das). Kopf- und Fußzeile werden nicht geprüft.

## Wenn der Theme Builder gerade offen ist

- Hat der Theme Builder ungespeicherte Änderungen (Entwurf, `draft_pending`), lehnen `lit/tb-create-template`,
  `lit/tb-assign` und das Aktivieren ab: erst dort speichern oder verwerfen.
- Deaktivieren (`lit/tb-activate` mit `enabled: false`) geht immer – auch dann, und auch bei einer aktiven
  Vorlage im Papierkorb. Die Antwort warnt: Speichert jemand ein offenes Theme-Builder-Fenster, kann Divi
  seinen eigenen Stand wiederherstellen; danach mit `lit/tb-list` prüfen.
- Speichert jemand in einem Theme-Builder-Fenster, das vor dem Anlegen einer Vorlage geöffnet wurde, entfernt
  Divi die neue Vorlage wieder aus der Liste und löscht sie 7 Tage später. `lit/tb-list` zeigt sie dann unter
  `detached` (mit `marked_unused`). Nur auf ausdrücklichen Wunsch: `lit/tb-assign` mit `reattach: true` ordnet
  sie wieder zu – immer deaktiviert, nur Vorlagen unter `detached` (keine, die eine Theme-Builder-Vorlage der
  Divi-Bibliothek nutzt) und nur, wenn ihre Layouts noch aktiv sind.

## Rechte

- WordPress: „Beiträge anderer bearbeiten“ (`edit_others_posts`) und „Design bearbeiten“
  (`edit_theme_options`); je Vorlage und Layout das Recht, sie zu bearbeiten; zum Anlegen zusätzlich
  „veröffentlichen“ (Divi legt Vorlagen und Layouts sofort aktiv an).
- Divi → Rollen-Editor: „Theme Builder“ – standardmäßig nur für Administratoren.
- Fehlt eines davon, gibt es für dieses Konto keine Vorlagen und Layouts (`not_found` wie bei einer unbekannten
  ID bzw. `forbidden`). Vorlagen, die das Konto nicht bearbeiten darf, erscheinen nirgends; aktive davon nur als
  Anzahl (`hidden_live` in `lit/tb-list`, `hidden_overlaps` im Probelauf, `hidden_templates` beim Ändern eines
  Layouts).
- Einstellungen → LIT MCP → Tools: Gruppe „Divi Theme Builder“ auf „nur lesen“ sperrt jedes Schreiben, auch über
  die `lit-divi-…`-Werkzeuge und über globale Module in Layouts; deaktiviert gibt es keine Vorlagen und Layouts.
  Nur dieser Gruppenschalter hält die `lit-divi-…`-Werkzeuge von Theme-Builder-Layouts fern – einzelne
  `lit/tb-…`-Werkzeuge abzuschalten reicht dafür nicht.

## Globale Module im Theme Builder

`lit/library-make-global` wandelt keine Knoten in Theme-Builder-Layouts um. Stattdessen den Abschnitt mit
`lit/library-save` (`scope: "global"`) speichern und mit `lit-library-insert` (`mode: "global"`) einfügen
(`lit-guide` topic `divi-library`).

## Rückgängig machen

Vorlagen haben keine Revisionen: `lit/tb-assign` nennt die bisherigen Bedingungen (`previous`), `lit/tb-activate`
schaltet zurück; jede Änderung steht im Protokoll. Layouts erhalten wie Divi-Seiten eine Revision (`revision_id`),
aber `lit/revisions-list` und `lit/revision-restore` gelten nur für Seiten, Beiträge und andere Inhaltstypen,
nicht für Theme-Builder-Layouts: Die Antwort nennt deshalb `restore_url`, den Revisionsvergleich in WordPress,
in dem der Nutzer die Revision wiederherstellt. Schneller Weg zurück bei einem sichtbaren Layout: die Vorlage mit
`lit/tb-activate` (`enabled: false`) ausblenden. Neu angelegte Vorlagen im Divi Theme Builder löschen.

## Ablauf: Vorlage für einen Inhaltstyp (custom-post-type-vorlage)

1. Inhaltstyp und Felder klären: `lit-content-types`, dann `lit/divi-dynamic-sources` mit `post_type`.
2. `lit/tb-list` lesen: gibt es schon eine Vorlage für den Typ? Gibt es eine globale Kopf-/Fußzeile?
3. Mit dem Nutzer den Aufbau abstimmen (welche Felder, welche Reihenfolge, Kopf-/Fußzeile global oder eigen).
4. `lit/tb-create-template` mit `use_on: ["singular:post_type:<typ>:all"]`, `header`/`footer` meist
   `{"source": "global"}`, `body` mit `source: "new"` und `nodes` (Überschrift `{{post:title}}`, Texte mit
   `{{field:…}}`, das Modul `post-content`, wenn der Eintrag eigenen Inhalt hat). Warnungen zu Feldern beachten.
5. Das Inhalt-Layout bei Bedarf mit `lit-divi-outline`/`lit-divi-update` verfeinern (Layout-ID als `post_id`;
   solange die Vorlage deaktiviert ist, ohne Probelauf).
6. Den Nutzer bitten, die Vorlage im Theme Builder anzusehen (Vorschau eines Eintrags ist erst nach dem
   Aktivieren möglich).
7. Erst auf ausdrücklichen Wunsch: `lit/tb-activate` mit `enabled: true` – Probelauf zeigen, dann
   `confirm: true`.