Einen App-Bildschirm mit dem gebündelten UI erstellen
Die meisten WordPress-Projekte benötigen irgendwann einen Bildschirm, der eher einer Anwendung als einer Seite gleicht: eine Liste von Datensätzen, eine Schaltfläche zum Öffnen eines Formulars und eine Rückmeldung nach dem Speichern. Üblicherweise kommen dafür ein JavaScript-Framework, mehrere REST-Controller und eine Komponentenbibliothek zum Einsatz, die alle neben dem Theme gepflegt werden.
Blockstudio bringt all diese Bausteine bereits mit. db.php bietet Block-Speicherung, Validierung und CRUD-Endpunkte. rpc.php ergänzt benutzerdefinierte Serveraktionen. Die gebündelten UI-Komponenten stellen Dialog, Formularfelder, Schaltflächen, Badges und Toasts bereit. Ein Interactivity-API-Store verbindet sie. In dieser Anleitung erstellst du einen vollständigen Bildschirm in einem einzigen Blockordner:
- Eine Projekttabelle, die auf dem Server gerendert und auf dem Client synchron gehalten wird.
- Ein Dialog Neues Projekt mit einem Formular, das anhand des Schemas validiert wird.
- Schaltflächen für Archivieren und Wiederherstellen, die eine RPC-Funktion mit optimistischer Aktualisierung und Zurücksetzen aufrufen.
- Schaltflächen zum Löschen, die direkt die Daten-API verwenden.
- Ein Toast nach erfolgreicher Erstellung und ein weiterer, wenn eine Änderung nicht gespeichert wird.
Bevor du beginnst
Die gebündelten Komponenten sind optional. Aktiviere sie in blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
Der Bildschirm befindet sich in einem Block:
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
Schritt 1: Das Datenmodell
<?php
return [
'storage' => 'sqlite',
'capability' => [
'create' => 'edit_posts',
'read' => 'edit_posts',
'update' => 'edit_posts',
'delete' => 'edit_posts',
],
'fields' => [
'name' => [
'type' => 'string',
'required' => true,
'minLength' => 2,
'maxLength' => 80,
],
'owner' => [
'type' => 'string',
'format' => 'email',
'required' => true,
],
'status' => [
'type' => 'string',
'enum' => ['active', 'archived'],
'required' => true,
],
],
];
Für jeden Vorgang ist die Fähigkeit edit_posts erforderlich. Daher antworten die Endpunkte auf eine Anfrage von abgemeldeten Nutzern mit 401, und nur Redakteure und höher können Daten ändern. Bei SQLite-Speicherung liegen die Datensätze in projects/db/default.sqlite neben dem Code.
status ist required und führt daher kein default mit. Bei SQLite und Tabellenspeicherung ergänzt das Schema beim Erstellen keinen fehlenden Wert. Ein Datensatz ohne status wird also mit einem leeren Wert gespeichert. Wenn du das Feld verpflichtend machst und es aus dem Formular übermittelst, bleibt jede Zeile gültig.
Füge über die Befehlszeile einige Datensätze hinzu:
wp bs db create acme/projects --name="Website relaunch" --owner=ana@example.com --status=active
wp bs db create acme/projects --name="Q3 report" --owner=ben@example.com --status=archived
wp bs db list acme/projects
Success: Record created (ID: 1).
Success: Record created (ID: 2).
id name owner status created_at updated_at
2 Q3 report ben@example.com archived ...
1 Website relaunch ana@example.com active ...
Die Liste wird mit den neuesten Einträgen zuerst zurückgegeben. So ist auch die Reihenfolge in der Tabelle.
Schritt 2: Eine Serveraktion
Da das Archivieren aus Sicht der Nutzer keine einfache Feldänderung ist, bekommt es eine eigene Funktion:
<?php
use Blockstudio\Db;
return [
'set_status' => [
'callback' => function (array $params) {
$id = (int) ($params['id'] ?? 0);
$status = (string) ($params['status'] ?? '');
$db = Db::get('acme/projects');
if (!$db->get_record($id)) {
return new \WP_Error('not_found', 'Project not found.', ['status' => 404]);
}
return $db->update($id, ['status' => $status]);
},
'capability' => 'edit_posts',
],
];
Db::update() validiert anhand des Schemas, sodass enum in db.php den Wert weiterhin absichert. Wird die Funktion mit einem unbekannten Status aufgerufen, gibt sie dieselbe Fehlerstruktur wie die Daten-API zurück:
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
Die Funktion lässt sich auch über die Befehlszeile aufrufen:
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
Schritt 3: Die Blockdefinition
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/projects",
"title": "Projects",
"category": "widgets",
"icon": "list-view",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
supports.interactivity veranlasst WordPress dazu, die Direktiven der Vorlage auf dem Server zu verarbeiten. Dadurch werden die Tabellenzeilen gerendert, bevor ein JavaScript ausgeführt wird.
Schritt 4: Die Vorlage
<?php
$can_edit = current_user_can('edit_posts');
$projects = $can_edit ? \Blockstudio\Db::get('acme/projects')->list() : [];
wp_interactivity_state('acme/projects', [
'projects' => array_values($projects),
'hasProjects' => !empty($projects),
'notice' => '',
'isArchived' => function () {
$context = wp_interactivity_get_context();
return 'archived' === ($context['project']['status'] ?? '');
},
]);
?>
<div
useBlockProps
class="projects"
data-wp-interactive="acme/projects"
data-wp-on-document--formsuccess="actions.created"
>
<?php if (!$can_edit) : ?>
<p>Sign in with an editor account to manage projects.</p>
<?php else : ?>
<div class="projects__bar">
<bs:bsui-text content="Projects" variant="title" tag="h2" />
<bs:bsui-dialog>
<bs:bsui-dialog-trigger trigger_label="New project" />
<bs:bsui-dialog-backdrop />
<bs:bsui-dialog-popup>
<bs:bsui-dialog-header>
<bs:bsui-dialog-title content="New project" />
<bs:bsui-dialog-description content="Projects start out active." />
</bs:bsui-dialog-header>
<bs:bsui-dialog-content>
<bs:bsui-form block="acme/projects">
<bs:bsui-field name="name">
<bs:bsui-field-label text="Name" />
<bs:bsui-input name="name" placeholder="Spring campaign" required="true" />
<bs:bsui-field-error />
</bs:bsui-field>
<bs:bsui-field name="owner">
<bs:bsui-field-label text="Owner email" />
<bs:bsui-input name="owner" type="email" placeholder="owner@example.com" required="true" />
<bs:bsui-field-error />
</bs:bsui-field>
<input type="hidden" name="status" value="active" />
<bs:bsui-space size="2" />
<bs:bsui-button label="Create project" />
</bs:bsui-form>
</bs:bsui-dialog-content>
<bs:bsui-dialog-footer>
<bs:bsui-dialog-close label="Cancel" />
</bs:bsui-dialog-footer>
</bs:bsui-dialog-popup>
</bs:bsui-dialog>
</div>
<table class="projects__table">
<thead>
<tr>
<th scope="col">Name</th>
<th scope="col">Owner</th>
<th scope="col">Status</th>
<th scope="col">Actions</th>
</tr>
</thead>
<tbody>
<template data-wp-each--project="state.projects" data-wp-each-key="context.project.id">
<tr>
<td data-wp-text="context.project.name"></td>
<td data-wp-text="context.project.owner"></td>
<td>
<span data-wp-bind--hidden="state.isArchived"><bs:bsui-badge label="Active" variant="success" /></span>
<span data-wp-bind--hidden="!state.isArchived"><bs:bsui-badge label="Archived" variant="secondary" /></span>
</td>
<td class="projects__actions">
<span data-wp-on--click="actions.toggleArchived">
<span data-wp-bind--hidden="state.isArchived"><bs:bsui-button label="Archive" variant="outline" size="sm" /></span>
<span data-wp-bind--hidden="!state.isArchived"><bs:bsui-button label="Restore" variant="outline" size="sm" /></span>
</span>
<span data-wp-on--click="actions.remove"><bs:bsui-button label="Delete" variant="ghost" size="sm" /></span>
</td>
</tr>
</template>
</tbody>
</table>
<p class="projects__empty" data-wp-bind--hidden="state.hasProjects">No projects yet.</p>
<div class="projects__toasts">
<bs:bsui-toast-provider>
<div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isCreatedNotice" data-wp-on--click="actions.dismissNotice">
<bs:bsui-toast message="Project created." />
</div>
<div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isFailedNotice" data-wp-on--click="actions.dismissNotice">
<bs:bsui-toast message="That change was not saved." />
</div>
</bs:bsui-toast-provider>
</div>
<?php endif; ?>
</div>
Vier Teile dieser Vorlage verdienen einen genaueren Blick.
Der Serverstatus liefert die Ausgangsdaten für die erste Anzeige. wp_interactivity_state() übergibt die Datensätze sowohl an den serverseitigen Direktivenprozessor als auch an den Client-Store. Die Vorlage data-wp-each wird auf dem Server zu echten Zeilen erweitert, jeweils eine tr pro Datensatz. isArchived ist eine Closure: WordPress wertet sie bei der Serververarbeitung für jede Zeile aus, wobei wp_interactivity_get_context() den Kontext dieser Zeile zurückgibt. So zeigen archivierte Zeilen schon vor der Hydrierung das richtige Badge und die passende Schaltfläche. Im Browser übernimmt der Getter desselben Namens im Store. hasProjects ist aus demselben Grund ein einfacher Wert: Ohne ihn wüsste der Server nicht, ob der Absatz für den leeren Zustand ausgeblendet werden soll.
Dialog und Formular sind Systemkomponenten. trigger_label wird an den bsui/button innerhalb des Auslösers weitergegeben, wie unter UI Komposition beschrieben. bsui/form mit block="acme/projects" serialisiert seine Felder mit FormData und sendet sie an den Erstellungsendpunkt des Blocks. Jedes bsui/field enthält den Namen seines Eingabefelds, sodass die Schemafehler für einzelne Felder beim richtigen Steuerelement erscheinen. Beim Absenden des leeren Formulars erscheinen unter Name die Meldung „Mindestens 2 Zeichen erforderlich.“ und unter E-Mail des Verantwortlichen „Gib eine gültige E-Mail-Adresse ein.“. Unten im Formular erscheint außerdem „Validierung fehlgeschlagen.“. Das verborgene status-Eingabefeld wird mit den Formulardaten übermittelt. So erfüllen neue Projekte das Pflichtfeld.
Die Tabelle besteht aus eigenem Markup. bsui/table eignet sich für Zeilen, die in der Vorlage definiert sind: Die Headerzellen sortieren, indem sie vorhandene tr-Elemente verschieben. Damit würden sie mit data-wp-each um die Kontrolle über die Zeilen konkurrieren. Vor Blockstudio 7.7 fügten dessen Teile außerdem ein div direkt in table, thead, tbody und tr ein. Browser verschieben diese Elemente aus der Tabelle heraus. Wenn Zeilen aus einem Store kommen, schreibe das table-Element selbst und setze die Systemkomponenten in die Zellen. Badges und Schaltflächen in der Zeilenvorlage sind gewöhnliche bsui/badge– und bsui/button-Tags. Jede Schaltfläche befindet sich in einem span, das die Klickdirektive enthält. So bleibt die Schaltfläche eine Systemschaltfläche, während die Aktion zu deinem Store gehört.
Der Toast dient der Darstellung. bsui/toast-provider rendert eine höfliche Live-Region, bsui/toast eine Statusmeldung mit einer Schaltfläche zum Ausblenden. Der Provider positioniert die Region nicht auf dem Bildschirm, und die Ausblendschaltfläche blendet keinen Toast aus, der aus Markup gerendert wurde. Der Bildschirm übernimmt daher beides: Ein Wrapper mit position: fixed platziert die Region, und jeder Toast befindet sich in einem div, dessen hidden-Bindung und Klick-Handler zum Store des Bildschirms gehören. Ein Klick auf die Ausblendschaltfläche wird bis zu diesem div weitergereicht.
Schritt 5: Der Store
import { store, getContext } from '@wordpress/interactivity';
const BLOCK = 'acme/projects';
let noticeTimer;
// bs.fn() and bs.db() resolve with the error body on a failed request.
// Throwing here is what lets bs.mutate() roll the optimistic change back.
const ok = (request) =>
request.then((result) => {
if (result?.code) {
throw result;
}
return result;
});
const notify = (notice) => {
state.notice = notice;
clearTimeout(noticeTimer);
noticeTimer = setTimeout(() => {
state.notice = '';
}, 4000);
};
const { state } = store(BLOCK, {
state: {
get hasProjects() {
return state.projects.length > 0;
},
get isArchived() {
return getContext().project.status === 'archived';
},
get isCreatedNotice() {
return state.notice === 'created';
},
get isFailedNotice() {
return state.notice === 'failed';
},
},
actions: {
created(event) {
const record = event.detail;
if (!record?.id || !('owner' in record)) {
return;
}
event.preventDefault();
state.projects = [record, ...state.projects];
store('bsui/dialog').actions.close();
notify('created');
},
dismissNotice() {
state.notice = '';
},
*toggleArchived() {
const project = getContext().project;
const status = project.status === 'archived' ? 'active' : 'archived';
try {
yield bs.mutate({
fn: () => ok(bs.fn('set_status', { id: project.id, status }, BLOCK)),
state,
key: 'projects',
action: 'update',
id: project.id,
optimistic: { status },
});
} catch (error) {
notify('failed');
}
},
*remove() {
const project = getContext().project;
try {
yield bs.mutate({
fn: () => ok(bs.db(BLOCK).delete(project.id)),
state,
key: 'projects',
action: 'delete',
id: project.id,
});
} catch (error) {
notify('failed');
}
},
},
});
Auf das Formular reagieren. Bei erfolgreichem Speichern löst bsui/form ein formsuccess-Ereignis aus, das nach oben weitergegeben werden kann, abbrechbar ist und den erstellten Datensatz in event.detail enthält. Bei fehlgeschlagenem Speichern löst es formerror mit dem Fehlerinhalt aus. Der Listener sitzt auf dem Dokument (data-wp-on-document--formsuccess) und nicht auf dem Wurzelelement des Bildschirms, denn ein geöffnetes Dialog-Popup wird nach document.body verschoben. Seine Ereignisse werden daher nicht mehr durch den Block weitergegeben. Die Prüfung owner überspringt Ereignisse von anderen Formularen auf derselben Seite.
Mit event.preventDefault() verhinderst du, dass das Formular seine Felder durch die Erfolgsmeldung ersetzt; zurückgesetzt wird es trotzdem. Die Aktion setzt den Datensatz dann an den Anfang, schließt den Dialog mit der Aktion close des Stores bsui/dialog und zeigt den Toast an. close schließt den obersten geöffneten Dialog und setzt den Fokus auf dessen Auslöser zurück. Nach dem Erstellen liegt der Tastaturfokus also wieder auf Neues Projekt.
Bei Fehlern zurücksetzen. bs.mutate() wendet die optimistische Änderung sofort an und stellt die vorherigen Werte wieder her, wenn das Promise von fn abgelehnt wird. bs.fn() und bs.db() werden bei HTTP-Fehlern nicht abgelehnt: Ein WP_Error der RPC-Funktion, ein Validierungsfehler oder ein fehlender Datensatz führen jeweils dazu, dass der Fehlerinhalt zurückgegeben wird. Der Helfer ok() macht aus einem Ergebnis mit einem code eine Ablehnung. Dadurch wird die Zeile zurückgesetzt und der Fehler-Toast erscheint. Ohne diesen Helfer würde bei einer fehlgeschlagenen Aktualisierung der Fehlerinhalt mit der Zeile zusammengeführt und eine fehlgeschlagene Löschung die Zeile weiterhin entfernt lassen.
Den Block benennen. Blockstudio gibt Inline-Skripte als <script type="module"> aus, und Modulscripts haben kein document.currentScript. Daher kann bs.fn() nicht erkennen, welcher Block den Aufruf ausführt. Übergebe den Blocknamen als drittes Argument, wie der Store es mit BLOCK tut.
Schritt 6: Den Bildschirm auf eine Seite setzen
Eine dateibasierte Seite bindet den Block über sein Tag ein:
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
Der Parser wandelt das Tag in einen nativen Block um:
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Führe wp bs pages sync aus, um die Seite zu erstellen. postStatus: "private" hält sie von anonymen Besuchern fern, die ohnehin nur die Anmeldemeldung sehen würden.
Verhalten des Bildschirms zur Laufzeit
Wenn die Seite als Redakteur geöffnet ist:
- Die Tabelle wird mit beiden Zeilen angezeigt. Die archivierte Zeile trägt das Badge Archiviert und eine Schaltfläche Wiederherstellen.
- Neues Projekt öffnet den Dialog. Popup und Hintergrund werden nach
document.bodyverschoben, der Fokus landet im Feld Name, und mit Escape oder Abbrechen schließt du den Dialog. - Beim Absenden gültiger Werte wird ein
POSTan/wp-json/blockstudio/v1/db/acme-projects/defaultgesendet. Der Dialog schließt sich, die neue Zeile erscheint ganz oben, und vier Sekunden lang wird in der Ecke „Projekt erstellt.“ angezeigt. - Archivieren ändert das Badge sofort und sendet
set_statusüber/wp-json/blockstudio/v1/fn/acme/projects/set_status. Wurde der Datensatz inzwischen anderswo gelöscht, gibt die Funktion den Fehler404zurück. Die Zeile wechselt zurück zu Aktiv, und „Änderung nicht gespeichert.“ wird angezeigt. - Löschen entfernt die Zeile sofort. Beim Löschen des letzten Projekts erscheint „Noch keine Projekte.“
Gestaltung
Das eigene CSS des Bildschirms liest die Bibliothekstokens. So passt die Tabelle zu den umgebenden Komponenten und übernimmt alle Theme-Überschreibungen der Eigenschaften --bs-ui-*:
.projects__table {
width: 100%;
border-collapse: collapse;
font-size: var(--bs-ui-font-size);
}
.projects__table th,
.projects__table td {
padding: var(--bs-ui-space-2) var(--bs-ui-space-3);
border-bottom: 1px solid var(--bs-ui-border);
text-align: left;
}
/* ... */
.projects__toasts {
position: fixed;
right: var(--bs-ui-space-4);
bottom: var(--bs-ui-space-4);
z-index: 40;
}
Das z-index von 40 hält den Toast-Bereich unter dem Dialoghintergrund, der auf 50 liegt. Um den ganzen Bildschirm neu zu gestalten, überschreibe Tokens wie unter Gestaltung beschrieben. Das gilt sowohl für die Komponenten als auch für die Tabelle.
Nächste Schritte
- UI-Komponenten: das Designsystem, Tokens und alle Komponenten.
- UI Komposition: zusammengesetzte Komponentenfamilien, Weitergabe an Auslöser und das Ebenenmodell des Dialogs.
- Datenbank: Speichermodi, Zugriffskontrolle,
bs.db()undbs.mutate(). - RPC: Zugriffskontrolle, HTTP-Methoden und blockübergreifende Aufrufe.
- Full-Stack-Blöcke: dieselben Bausteine in einer Todo-App und einer Newsletter-Anmeldung.