Block-Stile

Ein Blockstil ist ein fertiges Aussehen, das ein Redakteur im Editor mit einem Klick wählt (Reiter „Stile“ der Seitenleiste). Technisch ist er eine Klasse am Block: is-style-<name>. Ein Theme stellt die Blöcke des Plugins über Token und Blockstile ein, nicht über Selektoren in ihr Inneres.

Diese Seite listet, welche Stile Plugin und Theme mitbringen und wie ein Child einen eigenen ergänzt.

Die Stile des Plugins

Das Plugin registriert Stile für den Listen-Block wpce/entries. Sie stehen in der block.json des Blocks und wirken darum mit jedem Theme.

Im Editor	Klasse	Layout
Karten: Rahmen	`is-style-bordered`	Karten (Standard)
Karten: flach	`is-style-flat`	Karten
Karten: Schatten	`is-style-shadow`	Karten
Karten: hervorgehoben	`is-style-featured`	Karten
Karten: nummerierte Schritte	`is-style-steps`	Karten
Liste: Linien	`is-style-lined`	Liste (Standard) und Tabelle (Standard)
Liste: ruhig	`is-style-calm`	Liste
Liste: Programm	`is-style-programme`	Liste
Tabelle: gestreift	`is-style-zebra`	Tabelle

programme setzt die Zeilen wie ein gedrucktes Programm: nur Linien zwischen den Zeilen, der Name als Überschrift, das Kennzeichen als Wort in Großbuchstaben, bei Terminen der Tag als große Ziffer mit dem Monat darunter. steps zeigt die Einträge als Stationen eines Wegs: eine Ziffer im Ring, eine Linie zur nächsten Station, ohne Bild und ohne Fläche; die Ziffern zählt ein CSS-Zähler in der Reihenfolge der Liste. Beide Stile lesen nur Token. Neu ist --wpce-font-heading, die Schriftfamilie der Überschriften, siehe Die Token –wpce-*.

Der Editor zeigt je Layout nur die passenden Stile. lined gehört zu zwei Layouts: Liste und Tabelle teilen sich den Namen und die Beschriftung.

Der Standard. Hat ein Block keinen Stil seines Layouts, zeichnet das Stylesheet den ersten der Reihe: bordered, lined, lined. Er braucht dafür keine Klasse.

Der Standard-Stil kommt vom Theme

Welcher Stil gilt, solange die Redaktion keinen gewählt hat, entscheidet das Theme je Layout. Niemand muss ihn an jedem Block einstellen:

{
  "version": 3,
  "settings": {
    "custom": {
      "wpce": {
        "entries": { "cardStyle": "shadow", "listStyle": "calm", "tableStyle": "zebra" }
      }
    }
  }
}

Das Plugin liest das auf dem Server. Ein Block ohne Stil seines Layouts bekommt die Klasse des Theme-Standards. Das gilt auch in der Vorschau im Editor. Die Regeln dafür:

Ein Block mit eigenem Stil bleibt unverändert, auch wenn er den ersten Stil des Layouts trägt (is-style-bordered). Gewählt ist gewählt.
Erlaubt sind die Stile des jeweiligen Layouts (Karten bordered, flat, shadow, featured, steps; Liste lined, calm, programme; Tabelle lined, zebra) und Stile, die das Theme selbst für wpce/entries registriert hat. Alles andere wird ignoriert: cardStyle: "lined" ändert nichts, weil lined kein Kartenstil ist.
cardStyle: "bordered" ändert ebenfalls nichts. Das ist der Standard.
Die Schlüssel stehen in camelCase, weil das Plugin sie im PHP liest.

Geprüft mit einem Listen-Block für Abteilungen als Karten:

Eintrag im Theme	Klasse am Block
`cardStyle: "shadow"`	`is-style-shadow`
`cardStyle: "eckig"` (ein selbst registrierter Stil)	`is-style-eckig`
`cardStyle: "lined"`	keine
Block mit eigenem `is-style-bordered` und `cardStyle: "shadow"`	`is-style-bordered`

Die Stile des Themes

wpce-theme registriert seine Stile in inc/block-styles.php und in styles/. So heißen sie im Editor, und so heißt die Klasse. Die Beschriftungen stammen von einer laufenden Website mit deutscher Sprache.

Im Editor	Klasse	Block	Was es ist
Abschnitt: ruhig	`is-style-wpce-section-1`	Gruppe, Spalten, Spalte	Fläche `base`
Abschnitt: Fläche	`is-style-wpce-section-2`	Gruppe, Spalten, Spalte	Fläche `neutral`
Abschnitt: Akzent	`is-style-wpce-section-3`	Gruppe, Spalten, Spalte	Fläche `secondary`
Abschnitt: kräftig	`is-style-wpce-section-4`	Gruppe, Spalten, Spalte	Fläche `primary`, heller Text
Abschnitt: dunkel	`is-style-wpce-section-5`	Gruppe, Spalten, Spalte	Fläche `contrast`, heller Text
Karte	`is-style-card`	Gruppe, Spalte	Fläche, Linie, Rundung und Abstand aus `custom.wpce.card`
Karte, flach	`is-style-card-flat`	Gruppe, Spalte	ohne Fläche, Linie und Abstand
Karte, Schatten	`is-style-card-shadow`	Gruppe, Spalte	Fläche mit Schatten `soft`
Kontur (Akzent)	`is-style-outline-accent`	Schaltfläche	Kontur in der Linkfarbe des Abschnitts
Mit Pfeil	`is-style-arrow`	Schaltfläche	gefüllt, mit Pfeil, der beim Darüberfahren vorrückt
Link mit Pfeil	`is-style-arrow-link`	Absatz, „Weiterlesen“	fetter Link ohne Unterstreichung, mit Pfeil
Kennzeichen	`is-style-wpce-badge`	Absatz	kleine Marke in `primary`
Kennzeichen, betont	`is-style-wpce-badge-accent`	Absatz	`contrast` auf `secondary`
Dachzeile	`is-style-wpce-kicker`	Absatz, Überschrift	kleine Zeile in Großbuchstaben über einer Überschrift
Einleitung	`is-style-wpce-lead`	Absatz	großer, gedämpfter Einleitungstext
Hinweis-Pille	`is-style-wpce-hint`	Absatz	kleine Pille für einen Hinweis
Schlagzeile	`is-style-wpce-display`	Überschrift, Absatz	sehr große Schrift (`display`)
Abgerundet	`is-style-rounded`	Bild	Rundung `custom.wpce.media.radius` statt Kreis
Randlos (Standard), Panel, Geteilt, Platte, Mittig	keine Klasse, `is-style-panel`, `is-style-split`, `is-style-plate`, `is-style-centered`	Bildfolge (`wpce-theme/slideshow`, der Seitenanfang mit Bildern)	das Layout des Seitenanfangs; „Mittig“ setzt den Text in die Mitte des Bildes, jede Zeile mittig
Erster Beitrag groß	`is-style-wpce-featured`	Beitragsliste	der erste Beitrag als große Karte

Die fünf Abschnittsstile ändern Fläche, Text und Abstand als Global Styles. Alles andere (Karten, Kennzeichen, Einleitung, Pfeile, und was auf einem Abschnitt steht) steckt einmal im Stylesheet des Themes, über die einfache Klasse is-style-*. Die Werte darin sind Token. Ein Child ändert die Token (settings.custom.wpce.card.*, die Palette) oder setzt eine --wpce-*-Eigenschaft auf der Klasse in seinem eigenen Stylesheet.

Die Stile card, card-flat und card-shadow gehören dem Theme und gelten für Gruppen und Spalten. Die Karten des Plugins sind etwas anderes: Das sind die Stile des Listen-Blocks oben. Beide lesen dieselben Token (--wpce-card-line, --wpce-card-line-width, --wpce-card-padding).

Einen eigenen Stil im Child ergänzen

Es gibt zwei Wege. Nimm den ersten, wenn der Stil aus theme.json-Werten besteht, den zweiten, wenn du CSS brauchst.

Weg 1: eine Datei in `styles/blocks/`

Lege im Child die Datei styles/blocks/band-gruen.json an. Der Dateiname ist frei. slug wird die Klasse, blockTypes nennt die Blöcke, für die der Stil gilt:

{
  "$schema": "https://schemas.wp.org/wp/7.0/theme.json",
  "version": 3,
  "title": "Band grün",
  "slug": "band-gruen",
  "blockTypes": [ "core/group" ],
  "styles": {
    "color": {
      "background": "var:preset|color|tertiary",
      "text": "var:preset|color|base"
    },
    "spacing": {
      "padding": {
        "top": "var:preset|spacing|50",
        "bottom": "var:preset|spacing|50"
      }
    }
  }
}

Im Editor erscheint für Gruppen der Stil „Band grün“. Die Klasse am Block heißt is-style-band-gruen.

Geprüft: WordPress liest die Datei aus dem Ordner styles/ eines Child-ähnlichen Themes, registriert den Stil für core/group und gibt beim Rendern einer Gruppe mit dieser Klasse die Regel aus:

:root :where(.wp-block-group.is-style-band-gruen--1){background-color: var(--wp--preset--color--tertiary);color: var(--wp--preset--color--base);}

Das --1 hängt WordPress an, damit mehrere Blöcke mit demselben Stil sich nicht in die Quere kommen.

Zwei Regeln:

Eine Datei ohne styles wird nicht registriert. Der Stil braucht mindestens einen Wert.
Gleicher Dateiname wie beim Parent. Dann gilt die Datei des Childs, die des Parents entfällt. Verglichen wird nur der Dateiname, nicht der Ordner. So ersetzt du einen Stil des Themes ganz, zum Beispiel section-4.json aus styles/sections/ des Parents durch eine Datei section-4.json im Child.

Weg 2: ein Stil für den Listen-Block

Auch für wpce/entries geht die Datei. Der Stil setzt Token auf dem Block. styles.css nimmt Regeln an, & meint den Block selbst:

{
  "$schema": "https://schemas.wp.org/wp/7.0/theme.json",
  "version": 3,
  "title": "Karten: eckig",
  "slug": "eckig",
  "blockTypes": [ "wpce/entries" ],
  "styles": {
    "css": "& { --wpce-card-radius: 0; --wpce-media-radius: 0; }"
  }
}

Geprüft: Ein Listen-Block für Abteilungen mit der Klasse is-style-eckig bekommt

:root :where(.wp-block-wpce-entries.is-style-eckig--2){--wpce-card-radius: 0; --wpce-media-radius: 0;}

Die Token gelten dann für den Block und alles darin. Der Stil erscheint im Editor unter den Stilen des Listen-Blocks. Wer ihn zum Standard machen will, trägt ihn unter entries.cardStyle ein (siehe oben).

Weg 3: mit PHP und CSS

Wer lieber CSS schreibt, registriert den Stil in der functions.php und schreibt die Regeln in assets/css/child.css:

add_action( 'init', static function (): void {
  register_block_style(
    'wpce/entries',
    array(
      'name'  => 'eckig',
      'label' => __( 'Karten: eckig', 'wpce-tsvms' ),
    )
  );
} );

.wp-block-wpce-entries.is-style-eckig {
  --wpce-card-radius: 0;
  --wpce-media-radius: 0;
}

Auch das setzt Token auf dem Block, kein Selektor geht in sein Inneres.

Was schiefgeht

Selektoren auf das Innere des Listen-Blocks. Ein Stil, der .wpce-card__title anspricht, bricht, sobald das Plugin sein Markup ändert. Das Innere gehört nicht zum Vertrag. Setze Token.
Ein Stilname, der schon vergeben ist. Für denselben Block gilt jeder Name einmal. Wähle ein Präfix, zum Beispiel das Kürzel des Vereins.
Ein Standard-Stil, der kein Stil des Layouts ist. listStyle: "shadow" wird ignoriert. shadow gehört zu den Karten.
Ein Stil in einer Datei ohne styles. Er erscheint nicht im Editor.
Kopierte Parent-Dateien. Eine Datei mit dem Namen der Datei des Parents ersetzt sie. Dann folgt sie dem Parent nicht mehr. Trag sie in die Liste „What is overridden“ ein.