Vytvorenie obrazovky aplikácie pomocou pribaleného UI
Väčšina projektov WordPress napokon potrebuje obrazovku, ktorá je viac aplikáciou než stránkou: zoznam záznamov, tlačidlo na otvorenie formulára a potvrdenie úspešného uloženia. Zvyčajným riešením je framework JavaScript, sada kontrolérov REST a knižnica komponentov, ktoré sa všetky udržiavajú vedľa témy.
Blockstudio už všetky tieto súčasti obsahuje. db.php poskytuje bloku úložisko, overovanie a koncové body CRUD. rpc.php pridáva vlastné akcie servera. Komponenty pribaleného UI ponúkajú dialógové okno, polia formulára, tlačidlá, odznaky a upozornenia. Úložisko Interactivity API ich prepája. V tomto sprievodcovi vytvoríte kompletnú obrazovku v jedinom priečinku bloku:
- Tabuľka projektov vykreslená na serveri a priebežne synchronizovaná v klientovi.
- Dialógové okno Nový projekt s formulárom, ktorý overuje údaje podľa schémy.
- Tlačidlá Archivovať a Obnoviť, ktoré volajú funkciu RPC s optimistickou aktualizáciou a obnovením pôvodných údajov.
- Tlačidlá Odstrániť, ktoré používajú dátovú API priamo.
- Upozornenie po úspešnom vytvorení a ďalšie v prípade, keď sa zmena neuloží.
Skôr než začnete
Pribalené komponenty sú štandardne vypnuté. Zapnite ich v blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
Obrazovka sa nachádza v jednom bloku:
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
Krok 1: Dátový model
<?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,
],
],
];
Každá operácia vyžaduje oprávnenie edit_posts, takže koncové body vracajú 401 pri požiadavke od odhláseného používateľa a údaje môžu meniť iba redaktori a používatelia s vyššími oprávneniami. Úložisko SQLite uchováva záznamy v projects/db/default.sqlite vedľa kódu.
status je typu required a namiesto hodnoty default nesie referenciu. Pri použití SQLite a tabuľkového úložiska schéma pri vytváraní nedoplní chýbajúcu hodnotu, takže záznam vytvorený bez status sa uloží s prázdnou hodnotou. Ak je pole povinné a odosiela ho formulár, každý riadok zostane platný.
Vytvorte niekoľko úvodných záznamov z príkazového riadka:
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 ...
Zoznam sa vracia zoradený od najnovších záznamov, rovnako ako tabuľka.
Krok 2: Akcia servera
Archivácia z pohľadu používateľa nie je obyčajná úprava poľa, preto má vlastnú pomenovanú funkciu:
<?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() overuje údaje podľa schémy, takže enum v db.php naďalej kontroluje hodnotu. Volanie funkcie s neznámym stavom vráti rovnaký tvar chyby ako dátová API:
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
Funkciu možno volať aj z príkazového riadka:
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
Krok 3: Definícia bloku
{
"$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 umožňuje, aby WordPress spracovalo direktívy šablóny na serveri. Vďaka tomu sa riadky tabuľky vykreslia ešte pred spustením akéhokoľvek JavaScript.
Krok 4: Šablóna
<?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>
Štyri časti tejto šablóny si zaslúžia bližší pohľad.
Stav servera pripraví úvodné vykreslenie. wp_interactivity_state() odovzdá záznamy spracovateľovi direktív na strane servera aj úložisku klienta. Šablóna data-wp-each sa na serveri rozbalí na skutočné riadky, po jednom tr pre každý záznam. isArchived je uzáver: WordPress ho počas spracovania servera vyhodnotí pre každý riadok a pomocou wp_interactivity_get_context() vráti kontext daného riadka, takže archivované riadky zobrazujú správny odznak a tlačidlo ešte pred hydratáciou. V prehliadači prevezme jeho úlohu prístupová funkcia úložiska s rovnakým názvom. hasProjects je z rovnakého dôvodu obyčajná hodnota: bez nej by server nevedel, či má skryť odsek informujúci o prázdnom stave.
Dialógové okno a formulár používajú systémové komponenty. trigger_label sa odovzdá komponentu bsui/button vo vnútri spúšťača, ako je opísané v časti ZloženieUI. Komponent bsui/form s block="acme/projects" serializuje polia pomocou FormData a odošle ich koncovému bodu na vytváranie v danom bloku. Každý bsui/field nesie názov svojho vstupného poľa, takže chyby schémy pre jednotlivé polia sa zobrazia pri správnom ovládacom prvku. Po odoslaní prázdneho formulára sa pod poľom Názov zobrazí „Musí obsahovať aspoň 2 znaky.“ a pod poľom E-mail vlastníka „Zadajte platnú e-mailovú adresu.“; na spodku formulára sa navyše zobrazí „Overenie zlyhalo.“. Skryté vstupné pole status sa odošle spolu s údajmi formulára, vďaka čomu nové projekty spĺňajú požiadavku na povinné pole.
Tabuľka používa vašu vlastnú značku HTML. bsui/table sa hodí pre riadky vytvorené v šablóne: jej bunky hlavičky triedia presúvaním existujúcich prvkov tr, čím by narúšali správu riadkov komponentom data-wp-each. Pred verziou Blockstudio 7.7 jej časti vkladali aj prvok div priamo do prvkov table, thead, tbody a tr, odkiaľ ho prehliadače presúvajú mimo tabuľky. Pri riadkoch pochádzajúcich z úložiska vytvorte prvok table sami a systémové komponenty umiestnite do buniek. Odznaky a tlačidlá v šablóne riadka sú obyčajné značky bsui/badge a bsui/button. Každé tlačidlo je v prvku span s direktívou kliknutia, takže zostáva systémovým tlačidlom a akcia patrí vášmu úložisku.
Upozornenie je prezentačná súčasť. bsui/toast-provider vykresľuje zdvorilú živú oblasť a bsui/toast vykresľuje stavovú správu s tlačidlom na zatvorenie. Poskytovateľ sám neurčuje svoju polohu na obrazovke a tlačidlo na zatvorenie neskrýva upozornenie vykreslené zo značky HTML. Obrazovka preto robí oboje: obal s position: fixed umiestni oblasť a každé upozornenie sa nachádza v prvku div, ktorého väzba hidden a obsluha kliknutia patria do úložiska obrazovky. Kliknutie na tlačidlo zatvorenia sa prenesie nahor až k div.
Krok 5: Úložisko
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');
}
},
},
});
Reakcia na formulár. Po úspešnom uložení bsui/form vyšle udalosť formsuccess, ktorá sa šíri, možno ju zrušiť a vytvorený záznam nesie v event.detail. Pri neúspešnom uložení vyšle formerror s telom chyby. Poslucháč je umiestnený na dokumente (data-wp-on-document--formsuccess), nie na koreňovom prvku obrazovky, pretože vyskakovacie okno otvoreného dialógového okna sa presunie do document.body a jeho udalosti sa už nešíria cez blok. Kontrola owner preskočí udalosti z iných formulárov na tej istej stránke.
Volanie event.preventDefault() zabráni tomu, aby formulár nahradil polia správou o úspechu; formulár sa napriek tomu sám obnoví. Akcia potom pridá záznam na začiatok, zatvorí dialógové okno pomocou akcie close úložiska bsui/dialog a zobrazí upozornenie. close zatvorí navrchu otvorené dialógové okno a vráti fokus na jeho spúšťač, takže po vytvorení sa klávesnicový fokus vráti na tlačidlo Nový projekt.
Obnovenie pri chybách. bs.mutate() okamžite vykoná optimistickú zmenu a obnoví predchádzajúce hodnoty, ak dôjde k zamietnutiu prísľubu z fn. bs.fn() ani bs.db() sa pri chybách HTTP nezamietnu: WP_Error z funkcie RPC, zlyhanie overenia alebo chýbajúci záznam vrátia vyriešený prísľub s telom chyby. Pomocná funkcia ok() zmení výsledok obsahujúci code na zamietnutý prísľub, takže sa riadok vráti do pôvodného stavu a zobrazí sa upozornenie na chybu. Bez nej by sa telo chyby po neúspešnej aktualizácii zlúčilo s riadkom a po neúspešnom odstránení by riadok zostal odstránený.
Pomenovanie bloku. Blockstudio vypisuje vložené skripty ako <script type="module"> a modulové skripty nemajú document.currentScript, takže bs.fn() nedokáže zistiť, ktorý blok volá funkciu. Názov bloku odovzdajte ako tretí argument, ako to robí úložisko pomocou BLOCK.
Krok 6: Pridanie obrazovky na stránku
Stránka vytvorená zo súboru umiestni blok pomocou jeho značky:
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
Parser zmení značku na natívny blok:
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Spustením wp bs pages sync vytvoríte stránku. postStatus: "private" ju skryje pred anonymnými návštevníkmi, ktorí by aj tak videli iba prihlasovaciu správu.
Čo sa deje s obrazovkou počas behu
Otvorte stránku ako redaktor:
- Tabuľka sa zobrazí s vykreslenými oboma riadkami; pri archivovanom riadku sa zobrazí odznak Archivované a tlačidlo Obnoviť.
- Tlačidlo Nový projekt otvorí dialógové okno. Vyskakovacie okno a pozadie sa presunú do
document.body, fokus sa presunie do poľa Názov a klávesom Escape alebo tlačidlom Zrušiť okno zatvoríte. - Odoslaním platných hodnôt sa odošle jedno
POSTdo/wp-json/blockstudio/v1/db/acme-projects/default. Dialógové okno sa zatvorí, nový riadok sa zobrazí navrchu a v rohu sa na štyri sekundy zobrazí „Projekt bol vytvorený.“. - Tlačidlo Archivovať okamžite zmení odznak a odošle
set_statuscez/wp-json/blockstudio/v1/fn/acme/projects/set_status. Ak bol záznam medzitým odstránený inde, funkcia vráti chybu404, riadok sa vráti do stavu Aktívne a zobrazí sa „Zmena sa neuložila.“. - Tlačidlo Odstrániť okamžite odstráni riadok. Po odstránení posledného sa zobrazí „Zatiaľ tu nie sú žiadne projekty.“.
Štýlovanie
Vlastný CSS obrazovky používa tokeny knižnice, takže tabuľka ladí s okolitými komponentmi a rešpektuje všetky zmeny témy pre vlastnosti --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 40 udržiava oblasť upozornení pod pozadím dialógového okna, ktorého úroveň je 50. Ak chcete zmeniť tému celej obrazovky, upravte tokeny podľa pokynov v časti štýlovanie; zmena sa prejaví na komponentoch aj tabuľke.
Ďalšie kroky
- KomponentyUI: dizajnový systém, tokeny a kompletná sada komponentov.
- UIZloženie: zložené skupiny, odovzdávanie spúšťačov a model vrstvenia dialógového okna.
- Databáza: režimy ukladania, riadenie prístupu,
bs.db()abs.mutate(). - RPC: riadenie prístupu, metódy HTTP a volania medzi blokmi.
- Bloky s plným zásobníkom: rovnaké stavebné prvky v aplikácii so zoznamom úloh a pri prihlásení na odber noviniek.