From 17af3b05dfd594a0f9227f2baf711e5e42db7948 Mon Sep 17 00:00:00 2001 From: Jan-Niclas Loosen Date: Sun, 18 Oct 2026 17:25:16 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20Guides=20zu=20Preset-Stapeln,=20Gruppen?= =?UTF-8?q?-Presets,=20=C3=9Cberdeckungen,=20Massenzuweisung=20und=20detac?= =?UTF-8?q?h?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 5.5 --- docs/guides/divi-design-system.md | 68 +++++++++++++++++++++++++++++-- docs/guides/divi-placeholders.md | 2 +- docs/guides/divi-shortform.md | 68 ++++++++++++++++++++++++++++--- docs/guides/divi-structure.md | 9 ++-- docs/guides/workflows.md | 18 ++++++++ 5 files changed, 152 insertions(+), 13 deletions(-) diff --git a/docs/guides/divi-design-system.md b/docs/guides/divi-design-system.md index 568989f..7146b45 100644 --- a/docs/guides/divi-design-system.md +++ b/docs/guides/divi-design-system.md @@ -40,9 +40,11 @@ Regeln: Preset zum Standard seines Moduls bzw. seiner Gruppe; - neue Gruppen-Presets brauchen das Modul, aus dem die Gruppe stammt: `source_module` oder `from_node`. - `lit/divi-presets-delete` – nur Presets, die nirgends ausdrücklich verwendet werden (Seiten, Bibliothek, Theme - Builder, verschachtelt in anderen Presets); sonst `in_use` mit den Fundstellen. Ein Standard-Preset darf gelöscht - werden, auch wenn Module es ohne eigenes Preset nutzen: der Probelauf listet diese Seiten, danach zeigen sie das - Divi-Standardaussehen. + Builder, verschachtelt in anderen Presets); sonst `in_use` mit den Fundstellen und dem Hinweis auf + `lit/divi-design-detach`. Ein Standard-Preset darf gelöscht werden, auch wenn Module es ohne eigenes Preset + nutzen: der Probelauf listet diese Seiten, danach zeigen sie das Divi-Standardaussehen. Das gilt auch für + Standard-Gruppen-Presets: gelistet werden die Seiten mit Modulen, die diese Gruppe haben, aber kein eigenes + Gruppen-Preset dafür. - `lit/divi-design-snapshots` / `lit/divi-design-restore` – vor jeder Änderung legt LIT MCP einen Snapshot an (je Bereich die letzten 20); wiederherstellen mit `snapshot_id`. @@ -56,3 +58,63 @@ Rechte: Presets ändern verlangt das Recht, das Design anzupassen, und in Divis Konten ohne das Recht `unfiltered_html` (z. B. Redakteure) werden abgewiesen (`forbidden`), wenn vorhandene Presets HTML oder CSS enthalten – Divi würde es beim Speichern entfernen; dann einen Administrator bitten. Das gilt auch für das Löschen und für `lit/divi-design-restore`. + +## Presets auf Seiten zuweisen und Verweise entfernen + +Einzelne Module bekommen Presets mit `lit-divi-insert`, `lit-divi-update` und `lit-content-create` (Stapel, +`group_presets`, `clear_overrides`: siehe `divi-shortform`). Für viele Seiten gibt es zwei Werkzeuge (über +`mcp-adapter-execute-ability`); beide ändern Seiteninhalt, nicht den Preset-Bestand. + +**`lit/divi-presets-assign`** – ein Preset oder einen Stapel (`preset`) und/oder Gruppen-Presets +(`group_presets`) allen Modulen eines Typs (`module`, z. B. `"button"`) zuweisen: + +- Filter: `post_ids` (1–50 Einträge; ohne die Angabe alle Fundstellen mit diesem Modultyp), + `only_without_preset: true` (nur Module ohne Preset) oder `only_with_preset: ""` (nur Module, die dieses + Preset schon tragen; nicht zusammen), `clear_overrides: true` (lokale Werte entfernen, die das Preset überdecken). +- `preset: null` und `null` als Wert in `group_presets` werden abgewiesen (`validation_failed`): site-weit entfernt + `lit/divi-design-detach` Verweise. +- Ablauf: erst ohne `confirm` aufrufen (Probelauf: `confirm_required` mit `pages` – je Seite `post_id`, `title`, + `status`, die betroffenen Knoten mit Pfad-ID, Modul und Label sowie `warnings` zu überdeckten Werten –, dazu + `pages_count`, `nodes_count`, `skipped` und gegebenenfalls `blocked_ids`). Dem Nutzer Seiten, Anzahl der Module + und Überdeckungen zeigen und **erst nach seiner Antwort** denselben Aufruf mit `confirm: true` senden. Ohne + `confirm` wird nie etwas geschrieben. Ist nichts zu ändern, antwortet der Probelauf normal mit „nichts zu tun“ + (kein `confirm_required`). +- Je Aufruf werden höchstens **50 Seiten** geschrieben. Die Antwort nennt `saved` (je Seite `post_id`, + `revision_id`, Anzahl Module) und `remaining`: Ist `remaining` größer als 0, denselben Aufruf wiederholen – bereits + umgestellte Module ändern sich nicht noch einmal. Jede Seite bekommt ihre eigene WordPress-Revision; einen + Snapshot gibt es für Seiteninhalte nicht. +- Blockaden: Ohne `post_ids` verweigert der Aufruf alles und schreibt nichts: mit `forbidden` (und `blocked_ids`), + wenn das Konto eine veröffentlichte Fundstelle nicht bearbeiten darf, mit `unsupported`, wenn es mehr als 2000 + veröffentlichte Fundstellen gibt. Mit `post_ids` können nur die genannten Seiten blockieren, die Obergrenze gilt nicht, und eine genannte + Seite ohne Bearbeitungsrecht steht unter `skipped` (nicht `blocked_ids`). Scheitert das Speichern mitten im Lauf, + meldet `partial_write` die bis dahin gespeicherten Seiten (`saved`); die übrigen mit einem neuen Probelauf + weiterführen. +- Globale Module und die Bibliothek: Eine globale Instanz (`[global ]` in `lit-divi-outline`) wird auf der Seite + nicht umgeschrieben, sondern unter `skipped` gemeldet – „globales Modul – im Bibliothekseintrag ändern“, + wenn das Konto Bibliotheks-IDs sehen darf, sonst „globales Modul – im Divi-Builder ändern“. Der + Bibliothekseintrag selbst ist eine eigene Fundstelle und wird wie eine Seite umgeschrieben (wirkt dann überall, + siehe `divi-library`). Seiten, die sich nicht ändern lassen (Divi 4, beschädigtes Markup), stehen mit dem Grund + unter `skipped`. +- Rechte wie bei den Presets (Recht, das Design anzupassen, und Visual Builder) plus `edit_post` für jede + Fundstelle; Theme-Builder-Layouts nach den Regeln des Theme Builders. + +**`lit/divi-design-detach`** – Verweise auf ein Preset überall entfernen, damit es sich löschen lässt: + +- Eingabe: `preset` ist ein Objekt `{"module": "button", "preset": ""}` bzw. + `{"group": "font", "preset": ""}`, optional `post_ids` (Filter wie oben, 1–50). +- Ablauf wie bei jeder Änderung des Bestands: Probelauf (`confirm_required` mit Seiten und, wenn andere Presets das + Gruppen-Preset verschachteln, `diff` und `design_rev`), dem Nutzer zeigen, dann `confirm: true` (mit + `design_rev`, wenn der Probelauf eine nannte; veraltet: `rev_mismatch`, dann wird weder am Bestand noch an Seiten + etwas geschrieben). Gibt es keine Verweise mehr, ist der Probelauf ein normales „nichts zu tun“. +- Ohne `post_ids` werden zuerst verschachtelte Verweise in **anderen Presets** entfernt (mit Snapshot, wie + `lit/divi-presets-set`), danach die Seiten (höchstens 50 je Aufruf, `remaining` wie oben; ein weiterer Aufruf + findet keine verschachtelten Verweise mehr und macht mit den Seiten weiter). Scheitert das Speichern der ersten + Seite nach diesem Presets-Schritt, nennt die Fehlermeldung Snapshot und `diff`: die Verweise in den Presets + sind dann schon entfernt. Mit `post_ids` werden nur diese Seiten geändert, Verweise in Presets bleiben. +- Die Module fallen auf das nächste Preset ihres Stapels zurück, sonst auf das Standard-Preset bzw. Divis + Standardaussehen. Ein **Standard-Preset** wird nicht „entkoppelt“, weil Divi es ohne Verweis anwendet; detach + entfernt dort nur ausdrückliche Verweise und sagt das in `warnings`. Zum Beenden der Standardwirkung das Preset + löschen (`lit/divi-presets-delete`) oder mit `make_default: false` den Standard aufheben. +- Variablen: `variable` wird noch nicht unterstützt (`unsupported`; Variablen folgen mit Etappe 4c). +- Danach `lit/divi-presets-delete` aufrufen (Probelauf, `confirm`, `design_rev`); es meldet kein `in_use` mehr, + solange niemand das Preset neu zugewiesen hat. diff --git a/docs/guides/divi-placeholders.md b/docs/guides/divi-placeholders.md index 9ec277d..6743cc2 100644 --- a/docs/guides/divi-placeholders.md +++ b/docs/guides/divi-placeholders.md @@ -13,7 +13,7 @@ sich auch der Button. | `{{post:title}}`, `excerpt`, `date`, `modified`, `author`, `url`, `featured_image`, `categories`, `tags` | dynamischer Inhalt des angezeigten Beitrags | | `{{field:}}` | dynamischer Inhalt aus einem Feld (Pods/Meta), z. B. `{{field:telefon}}` | | `{{link:}}` | 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": ""` | Modul-Preset (kein Platzhalter, sondern eigenes Feld) | +| `"preset": ""` oder `["", …]`, `"group_presets": {…}` | Modul-Preset bzw. Stapel und Gruppen-Presets (keine Platzhalter, sondern eigene Felder, siehe `divi-shortform`) | Beispiele: diff --git a/docs/guides/divi-shortform.md b/docs/guides/divi-shortform.md index f933779..4773474 100644 --- a/docs/guides/divi-shortform.md +++ b/docs/guides/divi-shortform.md @@ -2,9 +2,9 @@ Neue Divi-Inhalte beschreibt man als JSON-Knoten. `lit-divi-insert` (in `nodes`) und `lit-content-create` (in `divi`) nehmen dieselbe Form. Jeder Knoten hat einen `type`; dazu Kurzform-Felder, optional `label` -(Admin-Label), `preset` (Name eines Modul-Presets aus `lit-divi-design-system`) und `attrs` (Vollform, siehe -`divi-attrs`). Kurz- und Vollform lassen sich kombinieren, aber nicht für denselben Pfad (dann Fehler -`validation_failed` mit dem Pfad). +(Admin-Label), `preset` (Name oder Liste von Namen von Modul-Presets aus `lit-divi-design-system`), +`group_presets` (Gruppen-Presets, siehe „Presets zuweisen“) und `attrs` (Vollform, siehe `divi-attrs`). Kurz- und +Vollform lassen sich kombinieren, aber nicht für denselben Pfad (dann Fehler `validation_failed` mit dem Pfad). ## Aufbau @@ -71,13 +71,68 @@ ist dort das Admin-Label). Beim Einfügen über `attrs` (`fieldItem.advanced.typ `socialNetwork.innerContent` mit `label`) setzen, danach auch mit `lit-divi-update` über `set` (`{"set": {"type": "email"}}`). +## Presets zuweisen + +Presets (Namen aus `lit-divi-design-system`, Modul-Presets mit `kind: module`, Gruppen-Presets mit `kind: group`) +gehen in `lit-divi-insert` (je Knoten in `nodes`), `lit-content-create` (je Knoten in `divi`) und +`lit-divi-update` (je Eintrag in `changes`) in drei Feldern: + +- `preset` – ein Name **oder eine Liste von 1–10 Namen** (Stapel). Der Stapel wird in dieser Reihenfolge + gespeichert; bei gleicher Priorität gewinnt das letzte Preset im Stapel (Divi-Verhalten). `null` entfernt das + Preset. Eine leere Liste und doppelte Namen sind Fehler (`validation_failed`); wer das Preset entfernen will, + sendet `null`. +- `group_presets` – Objekt `{"": "" | ["", …] | null}`. Die Gruppe nennt man als Kurzname + (`font-body`), mit vollem Namen (`divi/font-body`) oder als Attributpfad (`content.decoration.bodyFont`). Hat + das Modul mehrere Gruppen mit demselben Namen (z. B. `spacing` für Modul und Button), ist der Kurzname ein + Fehler (`validation_failed`), der die Pfade zur Auswahl nennt – dann den Attributpfad als Schlüssel verwenden. + Gibt es die Gruppe am Modul nicht oder das Preset in dieser Gruppe nicht, kommt `validation_failed` mit dem + Eingabepfad. `null` entfernt den Eintrag dieser Gruppe. +- `clear_overrides` – `true` oder `false` (nichts anderes), siehe „Überdeckte Werte“. + +Gruppen-Presets und Namen kommen immer aus Divi; die Werkzeuge schreiben nie frei erfundene IDs. + +Einfügen mit Stapel und Gruppen-Preset: + +```json +{ "type": "button", "text": "Termin buchen", "url": "{{link:42}}", + "preset": ["CTA primär", "CTA groß"], + "group_presets": { "font": "Button-Schrift" } } +``` + +Ändern mit `lit-divi-update` (Stapel ersetzen, Gruppen-Preset einer anderen Gruppe entfernen): + +```json +{ "post_id": 12, "tree_rev": "…", + "changes": [ { "id": "s0.r0.c1.m2", + "preset": ["CTA primär"], + "group_presets": { "font": "Button-Schrift", "spacing": null } } ] } +``` + +### Überdeckte Werte + +Lokale Werte eines Moduls (`attrs`, `set`) haben Vorrang vor den Werten seiner Presets. Weist ein Aufruf +ausdrücklich Presets zu (oder liegen sie schon am Modul), prüft das Werkzeug Blatt für Blatt (Pfad, Breakpoint, +Zustand): weicht ein lokaler Wert von dem des Presets ab, steht in `warnings` je Preset eine Zeile wie + +> `s0.r0.c1.m2: lokale Werte überdecken „CTA primär“: button.decoration.background – clear_overrides: true entfernt sie.` + +Die Zeile nennt bis zu fünf Pfade und „und N weitere“. Das Preset wirkt dort nicht; dem Nutzer sagen und fragen, +ob die lokalen Werte weg sollen. Dann denselben Knoten mit `"clear_overrides": true` ändern (z. B. +`{"id": "s0.r0.c1.m2", "preset": "CTA primär", "clear_overrides": true}`): das entfernt genau die lokalen Werte, +die ein ausdrücklich zugewiesenes Preset überdecken, und sonst nichts. Beim Einfügen wirkt `clear_overrides` nach +`set` und `attrs` desselben Knotens, entfernt also auch Werte, die der Aufruf selbst gesetzt hat. Standard-Presets +zählen nicht (Divi wendet sie implizit an, ohne dass der Knoten sie nennt). + +Dasselbe Preset auf vielen Seiten oder Modulen setzen: `lit/divi-presets-assign` (siehe `divi-design-system`). + ## Einfügen, ändern, verschieben, löschen - `lit-divi-insert`: `nodes` + Position – `parent` (Pfad-ID, z. B. Spalte `s0.r0.c1`; optional `index`), `before` oder `after`; ohne Position ans Seitenende. Oben auf der Seite sind nur Abschnitte erlaubt, in Abschnitten Zeilen, in Spalten Module. - `lit-divi-update`: `changes` = `[{"id": "s0.r0.c1.m2", "set": {"text": "Jetzt buchen"}, "preset": "CTA - primär", "label": "Hero – Button"}]` – mehrere Knoten in einem Aufruf; `null` entfernt einen Wert. Denselben + primär", "label": "Hero – Button"}]` – mehrere Knoten in einem Aufruf; `null` entfernt einen Wert. Neben + `preset` nehmen die Einträge `group_presets` und `clear_overrides` (siehe „Presets zuweisen“). Denselben Pfad nicht zugleich über `set` und `attrs` ändern (dann zwei Änderungen senden). - `lit-divi-move`: `id` + Position (auch in andere Zeilen oder Abschnitte). - `lit-divi-delete`: `ids`, erst nach Rückfrage mit `confirm: true`. @@ -117,5 +172,6 @@ weiterarbeiten). ## Warnungen Neue oder geänderte Knoten werden geprüft: feste Farben/Schriften, obwohl eine passende globale existiert; -Bilder ohne Alt-Text; leere Module; Sprünge in der Überschriftenhierarchie; Code-Modul. Warnungen dem Nutzer -nennen und möglichst gleich beheben. +Bilder ohne Alt-Text; leere Module; Sprünge in der Überschriftenhierarchie; Code-Modul; lokale Werte, die ein +zugewiesenes Preset überdecken (siehe „Überdeckte Werte“). Warnungen dem Nutzer nennen und möglichst gleich +beheben. diff --git a/docs/guides/divi-structure.md b/docs/guides/divi-structure.md index 1a70324..adc8fba 100644 --- a/docs/guides/divi-structure.md +++ b/docs/guides/divi-structure.md @@ -7,13 +7,16 @@ Spalten (`column`), Spalten Module (`text`, `heading`, `button`, …). Manche Mo ## Seitenbaum - `lit-divi-outline` mit `post_id` liefert jeden Knoten mit **Pfad-ID**, Modultyp, Admin-Label, Textauszug, - Layout-Info (z. B. `Spalten 8_24+16_24`) und Preset-Namen – als kompakten Text (`outline`) und als Liste - (`nodes`). Mit `id` nur ein Teilbaum, mit `depth` begrenzte Tiefe. + Layout-Info (z. B. `Spalten 8_24+16_24`), Modul-Preset-Namen und Gruppen-Presets – als kompakten Text + (`outline`, z. B. `{Preset: CTA primär} {Gruppen-Presets: font: Button-Schrift; spacing: Abstand Karte}`) und + als Liste (`nodes`, dort `group_presets` mit Einträgen wie `"font: Button-Schrift"`). Mit `id` nur ein + Teilbaum, mit `depth` begrenzte Tiefe. - Pfad-IDs: `s0` = erster Abschnitt, `s0.r1` = zweite Zeile darin, `s0.r1.c0` = erste Spalte, `s0.r1.c0.m2` = drittes Modul, `…m2.m0` = erstes Kind-Modul. `g` = globales Modul, `x` = fremder Block (z. B. aus dem Block-Editor). Gezählt wird je Buchstabe innerhalb des Elternknotens. - `lit-divi-node-get` mit `post_id` und `id` liefert alle Einstellungen eines Knotens (siehe `divi-attrs`), - die aktuellen Kurzform-Werte (`shortform`) und die IDs der Kinder. + die aktuellen Kurzform-Werte (`shortform`), die Gruppen-Presets (`group_presets`: je Gruppe `group_id`, + `group` und die Presets mit `id` und `name`) und die IDs der Kinder. ## Stand und Sperre diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md index d13faf8..999623b 100644 --- a/docs/guides/workflows.md +++ b/docs/guides/workflows.md @@ -30,6 +30,24 @@ Abschnitte zwischen Seiten kopieren: `lit/divi-node-copy`. Wiederkehrende Abschn Modulen machen: `lit/library-find-similar`, `lit/library-make-global`. Globale Module ändern und neue vorschlagen: `lit-guide` topic `divi-library`. +## Design auf Seiten ausrollen + +Ein Preset soll auf vielen Seiten gelten oder ein altes Preset verschwinden (Presets anlegen: `divi-design-system`): + +1. `lit-divi-design-system` lesen (Presets je Modul) und das Preset bei Bedarf mit `lit/divi-presets-set` anlegen + (Probelauf, nach Rückfrage `confirm: true` mit `design_rev`). +2. Einzelne Module: `lit-divi-update` mit `preset` (auch Stapel) und `group_presets`; `warnings` zu überdeckten + lokalen Werten dem Nutzer nennen, auf Wunsch `clear_overrides: true`. +3. Viele Seiten: `lit/divi-presets-assign` mit `module`, `preset`/`group_presets` und Filter (`post_ids`, + `only_without_preset`, `only_with_preset`) zuerst ohne `confirm`. Dem Nutzer die Seiten, die Zahl der Module und + die Überdeckungen zeigen; nach seiner Antwort denselben Aufruf mit `confirm: true`. Bei `remaining` größer als 0 + wiederholen (höchstens 50 Seiten je Aufruf). Jede Seite bekommt eine Revision. +4. Ein Preset aufgeben: `lit/divi-design-detach` (Probelauf, nach Rückfrage `confirm: true`, mit `design_rev`, wenn + der Probelauf eine nennt; bei `remaining` wiederholen), danach `lit/divi-presets-delete` (ebenfalls Probelauf + und `confirm`). +5. Stichprobe: `lit-divi-outline` einer betroffenen Seite (zeigt Preset und Gruppen-Presets je Modul) und + `lit-page-render-summary`; dem Nutzer die Vorschau nennen. + ## Text auf vielen Seiten ersetzen `lit/divi-replace-text` zuerst mit `dry_run: true` (Standard): zeigt Treffer je Seite mit `tree_rev`. Nach