Block Bindings

Mit Block Bindings zeigt ein Standardblock einen Wert, den ein anderer Ort liefert. Ein Absatz zeigt dann die Telefonnummer des Vereins, ein Knopf seine Beitrittsseite. Der Wert steht nur einmal in den Vereinsdaten und erscheint überall, wo er gebunden ist, auch im Editor.

Das ist der Weg für Patterns im Child oder in einem Add-on. Du baust Header, Fußzeile oder eine Kontaktzeile aus Kernblöcken, und die Daten kommen vom Verein. Du brauchst dafür keinen eigenen Block.

Die Quelle wpce/club

Das Plugin registriert die Quelle wpce/club (im Editor: „Vereinsdaten“). Ein gebundenes Attribut nennt den Schlüssel in args.key:

<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"wpce/club","args":{"key":"contact:phone"}}}}} -->
<p>+49 1234 56789</p>
<!-- /wp:paragraph -->

Der Text im Block (+49 1234 56789) ist nur der Platzhalter. Hat der Verein keinen Wert, bleibt er stehen. Welche Attribute sich binden lassen, bestimmt WordPress. Ein Absatz und eine Überschrift binden content, ein Knopf text und url, ein Bild id, url und alt.

Alle Schlüssel

Die Beschriftungen stammen vom Editor in deutscher Sprache. Die Beispielwerte stehen auf einer laufenden Website mit dem Demoverein.

Schlüssel	Beschriftung	Wert
name	Vereinsname	TSV Musterstadt 1899 e.V.
short_name	Vereinsname (kurz)	der Kurzname, ohne ihn der volle Name
logo_url	Logo (Bild)	Adresse des Logos in voller Größe
logo_alt	Logo (Alternativtext)	der Vereinsname
logo_id	Logo (Kennung des Bildes)	die ID des Bildes in der Mediathek
address	Adresse (einzeilig)	Mühlbachweg 5, 12345 Musterstadt, Bayern, Deutschland
street	Straße und Hausnummer	Mühlbachweg 5
address_line_2	Adresszusatz
postal_code	Postleitzahl	12345
city	Ort	Musterstadt
postal_city	PLZ und Ort	12345 Musterstadt
country	Land	Deutschland
contact:<typ>	der Wert eines Kontakts, zum Beispiel contact:phone	+49 1234 567890
contact_href:<typ>	der Link dazu, zum Beispiel contact_href:phone	tel:+491234567890
account_holder	Kontoinhaber	erste Bankverbindung
iban	IBAN	erste Bankverbindung
bic	BIC	erste Bankverbindung
bank_name	Bank	erste Bankverbindung
representatives	Vertreten durch	die Zeilen des Impressums, mit Komma verbunden
register	Registereintrag	Registergericht und Nummer
vat_id	Umsatzsteuer-ID
content_responsible	Verantwortlich für den Inhalt	die Zeilen des Impressums, mit Komma verbunden
main_action_label	Hauptknopf (Beschriftung)	Mitglied werden
main_action_url	Hauptknopf (Link)	die Adresse der gewählten Seite

Kontakte. <typ> ist einer von email, phone, fax, whatsapp, url, linkedin, instagram, facebook, xing, youtube. Den Wert und den Link gibt es nur für Typen, die der Verein eingetragen hat, und für den ersten Eintrag des Typs. Der Link ist mailto:…, tel:…, ein wa.me-Link oder die Adresse selbst:

Schlüssel	Wert
contact:email	info@tsv1899.example
contact_href:email	mailto:info@tsv1899.example
contact_href:whatsapp	https://wa.me/491701234567
contact_href:instagram	https://www.instagram.com/tsv_musterstadt/

Das Logo gehört an einen Bildblock. Alle drei Attribute zusammen:

<!-- wp:image {"metadata":{"bindings":{
  "id":{"source":"wpce/club","args":{"key":"logo_id"}},
  "url":{"source":"wpce/club","args":{"key":"logo_url"}},
  "alt":{"source":"wpce/club","args":{"key":"logo_alt"}}}}} -->
<figure class="wp-block-image"><img src="" alt=""/></figure>
<!-- /wp:image -->

Das ist das Logo, das die Vereins-Blöcke zeigen, in voller Größe. Der Alternativtext ist der Vereinsname. Ein Verein ohne Logo liefert nichts. Ein Bildblock mit leerem src druckt dann gar nichts, und das will ein Header.

Regeln

• Ein leerer Wert lässt den Block, wie er gespeichert ist. Der Text im Block bleibt. Geprüft: Ein Schlüssel, den es nicht gibt (gibt-es-nicht), ergibt den eigenen Text des Blocks.
• Text kommt HTML-maskiert zurück. WordPress setzt einen gebundenen Wert als HTML in den Block. Ein < im Namen bleibt darum Text. Links und die Logo-Schlüssel kommen unmaskiert zurück, das Ersetzen des Attributs maskiert sie selbst.
• E-Mail-Adressen werden auf der Website verschleiert (antispambot). Im Editor stehen sie im Klartext.
• Mehrere Zeilen (Vertreter, Verantwortlicher im Impressum) kommen mit Kommas in einer Zeile.
• Nur die erste Bankverbindung ist gebunden.

Ein Beispiel-Pattern

Eine Kontaktzeile aus Kernblöcken: Name, Anschrift und zwei Knöpfe. Als patterns/kontaktzeile.php im Child (der Kopf macht daraus ein Pattern, den Rest bildet Block-Markup):

<?php
/**
 * Title: Kontaktzeile
 * Slug: wpce-tsvms/kontaktzeile
 * Categories: text
 */
?>
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:heading {"level":3,"metadata":{"bindings":{"content":{"source":"wpce/club","args":{"key":"name"}}}}} -->
  <h3 class="wp-block-heading">Name des Vereins</h3>
  <!-- /wp:heading -->

  <!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"wpce/club","args":{"key":"street"}}}}} -->
  <p>Straße und Hausnummer</p>
  <!-- /wp:paragraph -->

  <!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"wpce/club","args":{"key":"postal_city"}}}}} -->
  <p>PLZ Ort</p>
  <!-- /wp:paragraph -->

  <!-- wp:buttons -->
  <div class="wp-block-buttons">
    <!-- wp:button {"metadata":{"bindings":{"text":{"source":"wpce/club","args":{"key":"contact:phone"}},"url":{"source":"wpce/club","args":{"key":"contact_href:phone"}}}}} -->
    <div class="wp-block-button"><a class="wp-block-button__link wp-element-button">Telefon</a></div>
    <!-- /wp:button -->

    <!-- wp:button {"metadata":{"bindings":{"text":{"source":"wpce/club","args":{"key":"contact:email"}},"url":{"source":"wpce/club","args":{"key":"contact_href:email"}}}}} -->
    <div class="wp-block-button"><a class="wp-block-button__link wp-element-button">E-Mail</a></div>
    <!-- /wp:button -->
  </div>
  <!-- /wp:buttons -->
</div>
<!-- /wp:group -->

Geprüft: Das Markup rendert mit dem Demoverein zu

<h3 class="wp-block-heading">TSV Musterstadt 1899 e.V.</h3>
<p class="wp-block-paragraph">Mühlbachweg 5</p>
<p class="wp-block-paragraph">12345 Musterstadt</p>
<div class="wp-block-button"><a href="tel:+491234567890" class="wp-block-button__link wp-element-button">+49 1234 567890</a></div>
<div class="wp-block-button"><a href="mailto:info@tsv1899.example" class="wp-block-button__link wp-element-button">…</a></div>

Der Text des E-Mail-Knopfs steht im Quelltext als HTML-Zeichenreferenzen (info…). Der Browser zeigt info@tsv1899.example.

Der Slug trägt das Kürzel des Vereins als Präfix (wpce-tsvms/…), wie bei jedem Pattern eines Childs.

Der Hauptknopf im Kopf

Der Hauptknopf ist der eine Aufruf des Vereins: „Mitglied werden“, „Mitmachen“, „Spenden“. Beschriftung und Ziel stehen in den Einstellungen, auf dem Reiter „Website“ unter Hauptknopf. Ein Theme bindet seinen Knopf an die beiden Schlüssel, die Namen sind eine Schnittstelle:

<!-- wp:button {"metadata":{"bindings":{
  "text":{"source":"wpce/club","args":{"key":"main_action_label"}},
  "url":{"source":"wpce/club","args":{"key":"main_action_url"}}}}} -->
<div class="wp-block-button"><a class="wp-block-button__link wp-element-button">Mitglied werden</a></div>
<!-- /wp:button -->

So steht der Knopf in den Patterns header, header-overlay, cta-band und cta-panel von wpce-theme. Du bindest ihn in einem eigenen Pattern genauso.

Beschriftung und Ziel gehören zusammen: entweder beide oder keines. Eine Beschriftung ohne Ziel wäre ein toter Knopf, ein Ziel ohne Beschriftung ein leerer. Das Ziel ist eine Seite der Website, gespeichert als ID, damit der Link eine umbenannte Seite überlebt, oder eine beliebige Adresse mit http, https, mailto oder tel. Eine Seite, die es nicht mehr gibt, im Papierkorb liegt oder nicht veröffentlicht ist, zählt als kein Ziel.

Hat der Verein keinen Hauptknopf, lässt das Plugin den gebundenen Knopf aus der Seite weg, und mit ihm die Zeile der Knöpfe um ihn, wenn nichts anderes darin steht. Eine Feuerwehr bittet ihre Besucher nicht, Mitglied zu werden. Jeder andere Knopf bleibt unberührt.

Geprüft: Ohne Beschriftung und Ziel (ClubData::main_action() ist null) rendert ein core/buttons mit dem gebundenen Knopf zu einem leeren String. Mit dem Hauptknopf des Demovereins steht <a href="…/mitglied-werden/" …>Mitglied werden</a> da.

Weitere Quellen

• wpce/field („Feld dieses Eintrags“): ein Absatz, eine Überschrift, ein Listenpunkt oder ein Knopf zeigt ein einfaches Feld des Eintrags, auf dem er steht (die Schleife in der Abfrage oder die Einzelseite). args.key ist der Meta-Key, zum Beispiel _wpce_person_first_name. Gebunden werden nur einfache Typen: Text, Textarea, Zahl und Select (er zeigt die Beschriftung der gewählten Option). Alles Strukturierte (Adresse, Kontakte, Zeiten, Medien) hat einen eigenen Feld-Block. core/post-meta kann das nicht, weil es geschützte Meta-Keys ablehnt, und jeder Key dieses Plugins beginnt mit _wpce_. Ohne Eintrag als Zusammenhang bleibt der Text des Blocks stehen.
• wpce-theme/copyright: ein Absatz zeigt „© Jahr Vereinsname“. Das Jahr kommt aus der aktuellen Zeit, darum bindet das Theme es und schreibt es nicht in die Vorlage. Der Absatz braucht kein args.

Was schiefgeht

• Ein Schlüssel mit Tippfehler. Es gibt keine Fehlermeldung, der Block zeigt seinen Platzhaltertext.
• Ein Kontakttyp, den der Verein nicht hat. contact:fax ohne Faxnummer ergibt nichts. Der Platzhalter bleibt. Wähle Typen, die jeder Verein hat (email, phone), oder rechne mit dem Platzhalter.
• Der Platzhalter ist ein Testtext. Nimm einen Text, der sichtbar falsch ist. Dann fällt ein toter Schlüssel auf, wo der Verein ihn nicht ausgefüllt hat.
• Ein gebundener Knopf, den nichts ersetzt. Ohne Hauptknopf verschwindet der Knopf. Plane die Zeile so, dass sie auch ohne ihn gut aussieht.