Een appscherm bouwen met de meegeleverde UI
De meeste WordPress-projecten hebben uiteindelijk een scherm nodig dat meer op een applicatie lijkt dan op een pagina: een lijst met records, een knop die een formulier opent en feedback wanneer een wijziging is opgeslagen. De gebruikelijke oplossing is een JavaScript-framework, een set REST-controllers en een componentenbibliotheek, die allemaal naast het thema worden onderhouden.
Blockstudio levert deze onderdelen al mee. db.php biedt blockopslag, validatie en CRUD-eindpunten. rpc.php voegt aangepaste serveracties toe. De meegeleverde UI-componenten bieden het dialoogvenster, formuliervelden, knoppen, badges en meldingen. Een Interactivity API-store verbindt ze met elkaar. In deze handleiding bouwen we een volledig scherm in één blockmap:
- Een tabel met projecten, gerenderd op de server en gesynchroniseerd met de client.
- Een dialoogvenster Nieuw project met een formulier dat de schema-validatie uitvoert.
- Knoppen Archiveren en Herstellen die een RPC-functie aanroepen met een optimistische update en rollback.
- Knoppen Verwijderen die de data API rechtstreeks gebruiken.
- Een melding na een geslaagde aanmaak en nog een melding als een wijziging niet wordt opgeslagen.
Voordat u begint
De meegeleverde componenten zijn opt-in. Schakel ze in via blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
Het scherm staat in één block:
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
Stap 1: Het datamodel
<?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,
],
],
];
Voor elke bewerking is de edit_posts-mogelijkheid vereist. Daarom antwoorden de eindpunten met 401 op een verzoek van een uitgelogde gebruiker, en kunnen alleen editors en gebruikers met meer rechten gegevens wijzigen. SQLite-opslag bewaart de records in projects/db/default.sqlite, naast de code.
status is required in plaats van een default mee te dragen. Met SQLite en tabelopslag vult het schema een ontbrekende waarde niet in bij het aanmaken, dus wordt een record dat zonder status wordt aangemaakt, met een lege waarde opgeslagen. Door het veld verplicht te maken en het vanuit het formulier mee te sturen, blijven alle rijen geldig.
Voeg vanaf de opdrachtregel een paar records toe:
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 ...
De lijst wordt nieuwste eerst teruggegeven, wat overeenkomt met de volgorde van de tabel.
Stap 2: Een serveractie
Archiveren is vanuit het oogpunt van de gebruiker geen gewone veldwijziging, dus krijgt het een eigen functie:
<?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() valideert aan de hand van het schema, zodat de enum in db.php de waarde blijft bewaken. Als u de functie aanroept met een onbekende status, krijgt u dezelfde foutstructuur terug als bij de data API:
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
De functie is ook aan te roepen vanaf de opdrachtregel:
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
Stap 3: De blockdefinitie
{
"$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 zorgt ervoor dat WordPress de richtlijnen van de template op de server verwerkt. Daardoor worden de tabelrijen gerenderd voordat JavaScript wordt uitgevoerd.
Stap 4: De template
<?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 onderdelen van deze template verdienen extra aandacht.
De serverstatus bepaalt de eerste weergave. wp_interactivity_state() geeft de records door aan zowel de serverzijdige richtlijnverwerker als de clientstore. De template data-wp-each wordt op de server uitgewerkt tot echte rijen, één tr per record. isArchived is een closure: WordPress evalueert deze voor elke rij tijdens de serververwerking, waarbij wp_interactivity_get_context() de context van die rij teruggeeft. Zo tonen gearchiveerde rijen al vóór hydration de juiste badge en knop. In de browser neemt de getter met dezelfde naam uit de store het over. hasProjects is om dezelfde reden een gewone waarde: zonder deze waarde weet de server niet of de alinea met de lege status verborgen moet worden.
Het dialoogvenster en formulier zijn systeemcomponenten. trigger_label wordt doorgegeven aan de bsui/button in de trigger, zoals beschreven in UISamenstellen. bsui/form met block="acme/projects" serialiseert de velden met FormData en stuurt ze naar het create-eindpunt van dat block. Elk bsui/field bevat de naam van het invoerveld, zodat schemafouten per veld bij het juiste besturingselement terechtkomen. Als u het lege formulier indient, verschijnt onder Naam de melding “Must be at least 2 characters.” en onder E-mailadres eigenaar de melding “Must be a valid email address.” Onderaan het formulier staat ook “Validation failed.” Het verborgen status-veld wordt samen met de formuliergegevens meegestuurd; zo voldoen nieuwe projecten aan het verplichte veld.
De tabel gebruikt uw eigen markup. bsui/table is geschikt voor rijen die in de template zijn geschreven. De headercellen ervan sorteren door bestaande elementen tr te verplaatsen, wat zou botsen met het beheer van de rijen door data-wp-each. Vóór Blockstudio 7.7 plaatsten de onderdelen ervan ook rechtstreeks een div in table, thead, tbody en tr, waarna browsers deze buiten de tabel verplaatsen. Schrijf voor rijen die uit een store komen het element table zelf en plaats de systeemcomponenten in de cellen. De badges en knoppen in de rijtemplate zijn gewone tags bsui/badge en bsui/button. Elke knop staat in een span met de click-richtlijn, zodat de knop een systeemknop blijft en de actie bij uw store hoort.
De melding is presentatief. bsui/toast-provider rendert een beleefde live-regio en bsui/toast rendert een statusbericht met een knop om het te sluiten. De provider plaatst zichzelf niet op het scherm en de sluitknop verbergt geen melding die vanuit markup is gerenderd. Het scherm doet daarom beide: een wrapper met position: fixed plaatst de regio, en elke melding staat in een div waarvan de binding hidden en click-handler bij de store van het scherm horen. Een klik op de sluitknop wordt doorgegeven aan die div.
Stap 5: De 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');
}
},
},
});
Reageren op het formulier. Bij een geslaagde opslag verstuurt bsui/form een formsuccess-gebeurtenis die omhoog wordt doorgegeven, kan worden geannuleerd en het aangemaakte record bevat in event.detail. Bij een mislukte opslag verstuurt deze formerror met de foutinhoud. De listener staat op het document (data-wp-on-document--formsuccess) en niet op het root-element van het scherm, omdat een geopend dialoogvenster naar document.body wordt verplaatst. De gebeurtenissen ervan gaan dan niet meer omhoog via het block. De controle owner slaat gebeurtenissen van andere formulieren op dezelfde pagina over.
Door event.preventDefault() aan te roepen, wordt voorkomen dat het formulier de velden vervangt door de succesmelding; het formulier wordt nog steeds gereset. De actie voegt het record bovenaan toe, sluit het dialoogvenster met de bsui/dialog-storeactie close en toont de melding. close sluit het bovenste geopende dialoogvenster en verplaatst de focus terug naar de trigger. Na het aanmaken staat de toetsenbordfocus dus weer op Nieuw project.
Wijzigingen terugdraaien bij fouten. bs.mutate() voert de optimistische wijziging direct uit en herstelt de vorige waarden als de promise van fn wordt afgewezen. bs.fn() en bs.db() worden bij HTTP-fouten niet afgewezen: een WP_Error van de RPC-functie, een validatiefout of een ontbrekend record leidt allemaal tot een resultaat met de foutinhoud. De helper ok() zet een resultaat met een code om in een afwijzing, zodat de rij wordt hersteld en de foutmelding verschijnt. Zonder deze helper zou een mislukte update de foutinhoud met de rij samenvoegen en zou een mislukte verwijdering de rij verwijderd laten.
Het block benoemen. Blockstudio schrijft inline scripts uit als <script type="module">, en modulescripts hebben geen document.currentScript. Daarom kan bs.fn() niet vaststellen welk block de aanroep doet. Geef de blocknaam mee als derde argument, zoals de store doet met BLOCK.
Stap 6: Plaats het scherm op een pagina
Een paginabestand plaatst het block met zijn tag:
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
De parser zet de tag om in een native block:
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Voer wp bs pages sync uit om de pagina aan te maken. postStatus: "private" zorgt ervoor dat anonieme bezoekers de pagina niet zien, omdat zij anders alleen het aanmeldbericht zouden zien.
Wat het scherm tijdens runtime doet
Met de pagina geopend als editor:
- De tabel verschijnt met beide rijen gerenderd. De gearchiveerde rij toont de badge Gearchiveerd en een knop Herstellen.
- Nieuw project opent het dialoogvenster. De popup en achtergrond worden naar
document.bodyverplaatst, de focus komt in het veld Naam terecht en met Escape of Annuleren sluit u het venster weer. - Als u geldige waarden indient, wordt één
POSTnaar/wp-json/blockstudio/v1/db/acme-projects/defaultgestuurd. Het dialoogvenster sluit, de nieuwe rij verschijnt bovenaan en vier seconden lang verschijnt in de hoek de melding "Project created." - Archiveren wijzigt de badge direct en verstuurt
set_statusvia/wp-json/blockstudio/v1/fn/acme/projects/set_status. Als het record intussen ergens anders is verwijderd, retourneert de functie de fout404, wordt de rij weer Actief en verschijnt de melding "That change was not saved." - Verwijderen verwijdert de rij direct. Als u de laatste rij verwijdert, verschijnt "No projects yet."
Vormgeving
De eigen CSS van het scherm leest de tokens van de bibliotheek, zodat de tabel overeenkomt met de omliggende componenten en eventuele thema-aanpassingen van de eigenschappen --bs-ui-* volgt:
.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;
}
De z-index van 40 houdt de meldingenregio onder de achtergrond van het dialoogvenster, die op 50 staat. Als u het hele scherm een ander thema wilt geven, past u tokens aan zoals beschreven onder vormgeving; de componenten en tabel volgen die aanpassingen.
Volgende stappen
- UIComponenten: het designsysteem, de tokens en de volledige set componenten.
- UISamenstellen: samengestelde families, doorgeven van triggers en het laagmodel achter het dialoogvenster.
- Database: opslagmodi, toegangsbeheer,
bs.db()enbs.mutate(). - RPC: toegangsbeheer, HTTP-methoden en aanroepen tussen blocks.
- Full-Stack Blocks: dezelfde bouwstenen in een todo-app en een nieuwsbriefaanmelding.