Bygg en appskärm med det medföljande UI
De flesta WordPress-projekt behöver förr eller senare en skärm som fungerar mer som en applikation än en sida: en lista med poster, en knapp som öppnar ett formulär och återkoppling när en sparning lyckas. Den vanliga lösningen är ett JavaScript-ramverk, en uppsättning REST-kontroller och ett komponentbibliotek, allt underhållet bredvid temat.
Blockstudio innehåller redan alla dessa delar. db.php ger blocklagring, validering och CRUD-slutpunkter. rpc.php lägger till anpassade serveråtgärder. De medföljande UI-komponenterna tillhandahåller dialogrutan, formulärfälten, knapparna, märkena och toastmeddelandet. Ett Interactivity-lager API kopplar ihop dem. Den här guiden bygger en hel skärm från början till slut i en enda blockmapp:
- En projekttabell som renderas på servern och hålls synkroniserad på klienten.
- En dialogruta för Nytt projekt med ett formulär som valideras mot schemat.
- Knapparna Arkivera och Återställ anropar en funktion RPC med en optimistisk uppdatering och återställning.
- Knapparna Ta bort använder data-API direkt.
- Ett toastmeddelande efter att ett projekt har skapats och ett till när en ändring inte sparas.
Innan du börjar
De medföljande komponenterna är valfria. Aktivera dem i blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
Skärmen finns i ett enda block:
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
Steg 1: Datamodellen
<?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,
],
],
];
Varje åtgärd kräver behörigheten edit_posts, så slutpunkterna svarar med 401 på en utloggad begäran och endast redaktörer och högre roller kan ändra data. Lagring med SQLite sparar posterna i projects/db/default.sqlite, bredvid koden.
status är required i stället för att ha ett default. Med SQLite och tabellagring fyller schemat inte i ett saknat värde när en post skapas, så en post som skapas utan status lagras med ett tomt sådant. Om du gör fältet obligatoriskt och skickar det från formuläret förblir alla rader giltiga.
Lägg in några exempelposter från kommandoraden:
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 ...
Listan visas med den nyaste posten först, vilket är den ordning tabellen använder.
Steg 2: En serveråtgärd
Ur användarens perspektiv är arkivering inte en vanlig fältändring, så den får en namngiven 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() validerar mot schemat, så enum i db.php fortsätter att kontrollera värdet. Om funktionen anropas med en okänd status returneras samma felstruktur som för data-API:
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
Funktionen kan även anropas från kommandoraden:
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
Steg 3: Blockdefinitionen
{
"$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 gör att WordPress bearbetar mallens direktiv på servern, vilket gör att tabellraderna renderas innan någon JavaScript körs.
Steg 4: Mallen
<?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>
Fyra delar av mallen är värda att titta närmare på.
Serverns tillstånd ger den första visningen innehåll. wp_interactivity_state() skickar posterna till både direktivprocessorn på serversidan och klientlagret. Mallen data-wp-each byggs ut till riktiga rader på servern, en tr per post. isArchived är en closure: WordPress utvärderar den för varje rad under serverbearbetningen, och wp_interactivity_get_context() returnerar radens kontext. Därför visas rätt märke och knapp för arkiverade rader redan innan hydrering. I webbläsaren tar lagrets getter med samma namn över. hasProjects är ett vanligt värde av samma skäl: utan det skulle servern inte veta om stycket för tomt tillstånd ska döljas.
Dialogrutan och formuläret är systemkomponenter. trigger_label skickas vidare till bsui/button inuti utlösaren, som beskrivs i UIkomposition. bsui/form med block="acme/projects" serialiserar formulärets fält med FormData och skickar dem till blockets slutpunkt för att skapa poster. Varje bsui/field innehåller namnet på sitt inmatningsfält, så schemats fältfel visas under rätt kontroll. Om det tomma formuläret skickas visas “Måste innehålla minst 2 tecken.” under Namn och “Ange en giltig e-postadress.” under Ägarens e-post, samt “Valideringen misslyckades.” längst ned i formuläret. Det dolda inmatningsfältet status följer med formulärdatan, vilket gör att nya projekt får det obligatoriska fältet.
Tabellen är din egen markup. bsui/table passar för rader som skrivs i mallen: rubrikcellerna sorterar genom att flytta de befintliga elementen tr, vilket skulle konkurrera med data-wp-each om kontrollen över raderna. Före Blockstudio 7.7 placerade dess delar dessutom ett div direkt inuti table, thead, tbody och tr, vilket gör att webbläsare flyttar ut det ur tabellen. För rader som kommer från ett lager skriver du själv elementet table och placerar systemkomponenterna i cellerna. Märkena och knapparna i radmallen är vanliga taggar för bsui/badge och bsui/button. Varje knapp ligger i en span som har klickdirektivet, så knappen förblir systemknappen medan åtgärden tillhör ditt lager.
Toastmeddelandet är en presentationskomponent. bsui/toast-provider renderar ett artigt liveområde och bsui/toast renderar ett statusmeddelande med en avvisningsknapp. Leverantören placerar inte sig själv på skärmen, och avvisningsknappen döljer inte ett toastmeddelande som renderats från markup. Därför gör skärmen båda delarna: en omslutning med position: fixed placerar området, och varje toastmeddelande ligger i en div vars hidden-bindning och klickhanterare tillhör skärmens lager. Ett klick på avvisningsknappen bubblar upp till det lagret div.
Steg 5: Tillståndslagret
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');
}
},
},
});
Reagera på formuläret. När sparningen lyckas skickar bsui/form ut en händelse formsuccess som bubblar upp, kan avbrytas och innehåller den skapade posten i event.detail. Om sparningen misslyckas skickas formerror ut med felinnehållet. Lyssnaren sitter på dokumentet (data-wp-on-document--formsuccess), inte på skärmens rotelement, eftersom en öppen dialogruta flyttas till document.body och dess händelser därför inte längre bubblar genom blocket. Kontrollen owner hoppar över händelser från andra formulär på samma sida.
Anropet event.preventDefault() hindrar formuläret från att ersätta fälten med framgångsmeddelandet; formuläret återställer ändå sig självt. Åtgärden lägger sedan till posten först i listan, stänger dialogrutan med åtgärden close i lagret bsui/dialog och visar toastmeddelandet. close stänger den översta öppna dialogrutan och återför fokus till dess utlösare. Efter att en post har skapats ligger tangentbordsfokus därför tillbaka på Nytt projekt.
Återställ ändringar vid fel. bs.mutate() tillämpar den optimistiska ändringen omedelbart och återställer de tidigare värdena när löftet från fn avvisas. bs.fn() och bs.db() avvisas inte vid HTTP-fel: en WP_Error från funktionen RPC, ett valideringsfel eller en post som saknas returneras som ett resultat med felinnehåll. Hjälpfunktionen ok() omvandlar ett resultat med code till ett avvisat löfte, så raden återställs och felmeddelandet visas. Utan den skulle en misslyckad uppdatering slå ihop felinnehållet med raden, och en misslyckad borttagning lämna raden borttagen.
Namnge blocket. Blockstudio skriver ut infogade skript som <script type="module">, och modulskript har ingen document.currentScript. Därför kan bs.fn() inte upptäcka vilket block som anropar. Skicka blocknamnet som det tredje argumentet, vilket lagret gör med BLOCK.
Steg 6: Lägg till skärmen på en sida
En filbaserad sida placerar blocket med dess tagg:
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
Parsern omvandlar taggen till ett inbyggt block:
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Kör wp bs pages sync för att skapa sidan. postStatus: "private" håller den borta från anonyma besökare, som ändå bara skulle se inloggningsmeddelandet.
Så fungerar skärmen vid körning
När sidan är öppen i redigeringsläge:
- Tabellen visas med båda raderna renderade. Den arkiverade raden har märket Arkiverad och knappen Återställ.
- Nytt projekt öppnar dialogrutan. Popupen och bakgrunden flyttas till
document.body, fokus hamnar i fältet Namn och Escape eller Avbryt stänger dialogrutan igen. - När giltiga värden skickas skickas en
POSTtill/wp-json/blockstudio/v1/db/acme-projects/default. Dialogrutan stängs, den nya raden visas överst och "Projektet har skapats." visas i hörnet i fyra sekunder. - Arkivera ändrar genast märket och skickar
set_statusvia/wp-json/blockstudio/v1/fn/acme/projects/set_status. Om posten har tagits bort någon annanstans under tiden returnerar funktionen felet404, raden återgår till Aktiv och "Ändringen sparades inte." visas. - Ta bort tar genast bort raden. När den sista posten tas bort visas "Inga projekt än."
Formge
Skärmens egen CSS läser av bibliotekets token, så tabellen matchar de omgivande komponenterna och följer alla temaanpassningar av egenskaperna --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;
}
z-index för 40 placerar toastområdet under dialogrutans bakgrund, som ligger på 50. Om du vill formge om hela skärmen kan du åsidosätta token enligt beskrivningen under formgivning. Komponenterna och tabellen följer ändringen.
Nästa steg
- UIKomponenter: designsystemet, token och hela komponentuppsättningen.
- UIKomposition: sammansatta komponentfamiljer, vidarebefordran från utlösare och lagerhanteringen bakom dialogrutan.
- Databas: lagringslägen, åtkomstkontroll,
bs.db()ochbs.mutate(). - RPC: åtkomstkontroll, HTTP-metoder och anrop mellan block.
- Fullstackblock: samma byggstenar i en att-göra-app och ett nyhetsbrevsformulär.