Izdelava zaslona aplikacije z vključenim UI
Večina projektov WordPress sčasoma potrebuje zaslon, ki je bolj podoben aplikaciji kot strani: seznam zapisov, gumb za odpiranje obrazca in obvestilo, ko je shranjevanje uspešno. Običajna rešitev je ogrodje JavaScript, nabor krmilnikov REST in knjižnica komponent, ki se vsi vzdržujejo ob temi.
Blockstudio že vključuje vse te dele. db.php poskrbi za hrambo blokov, preverjanje veljavnosti in končne točke CRUD. rpc.php doda dejanja po meri na strežniku. Komponente vključene knjižnice UI ponujajo pogovorno okno, polja obrazca, gumbe, značke in obvestila. Shrambni objekt Interactivity API jih povezuje. V tem vodniku od začetka do konca izdelamo en zaslon v eni sami mapi bloka:
- Tabela projektov, izrisana na strežniku in sproti usklajena v odjemalcu.
- Pogovorno okno Nov projekt z obrazcem, ki preverja podatke glede na shemo.
- Gumba Arhiviraj in Obnovi, ki pokličeta funkcijo RPC z optimističnim posodobljenjem in razveljavitvijo spremembe.
- Gumbi Izbriši, ki neposredno uporabljajo podatke API.
- Obvestilo po uspešni ustvaritvi in drugo, kadar spremembe ni mogoče shraniti.
Pred začetkom
Vključene komponente so neobvezne. Omogočite jih v blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
Zaslon je v enem bloku:
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
1. korak: Podatkovni 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,
],
],
];
Vsaka operacija zahteva zmogljivost edit_posts, zato se končne točke na zahtevo neprijavljenega uporabnika odzovejo z 401, podatke pa lahko spreminjajo samo uredniki in uporabniki z višjimi pravicami. Hramba SQLite shranjuje zapise v projects/db/default.sqlite, poleg kode.
status je required, namesto da bi vseboval default. Pri SQLite in hrambi v tabeli shema ob ustvarjanju ne zapolni manjkajoče vrednosti, zato se zapis, ustvarjen brez status, shrani s prazno vrednostjo. Če polje označimo kot obvezno in ga pošljemo iz obrazca, ostanejo vse vrstice veljavne.
V ukazni vrstici vnesite nekaj začetnih zapisov:
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 ...
Seznam se prikaže od najnovejšega do najstarejšega, tako kot je razvrščena tabela.
2. korak: Strežniško dejanje
Z vidika uporabnika arhiviranje ni navadno urejanje polja, zato zanj ustvarimo poimenovano funkcijo:
<?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() preverja podatke glede na shemo, zato enum v db.php še vedno varuje vrednost. Če funkcijo pokličemo z neznanim stanjem, vrne enako obliko napake kot podatki API:
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
Funkcijo lahko pokličete tudi iz ukazne vrstice:
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
3. korak: Definicija bloka
{
"$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 poskrbi, da WordPress na strežniku obdela direktive v predlogi, kar omogoči izris vrstic tabele še pred zagonom katerega koli JavaScript.
4. korak: Predloga
<?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>
Štiri dele te predloge si velja podrobneje ogledati.
Stanje strežnika pripravi začetni prikaz. wp_interactivity_state() posreduje zapise procesorju direktiv na strežniku in shrambnemu objektu odjemalca. Predloga data-wp-each se na strežniku razširi v dejanske vrstice, po eno tr za vsak zapis. isArchived je zaključek: WordPress ga ovrednoti za vsako vrstico med obdelavo na strežniku, pri čemer wp_interactivity_get_context() vrne kontekst te vrstice, zato arhivirane vrstice že pred hidracijo prikažejo pravo značko in gumb. V brskalniku njegovo vlogo prevzame getter z istim imenom iz shrambnega objekta. hasProjects je iz istega razloga navadna vrednost: brez nje strežnik ne bi vedel, ali naj skrije odstavek za prazno stanje.
Pogovorno okno in obrazec sta sistemski komponenti. trigger_label se posreduje v bsui/button znotraj sprožilca, kot je opisano v UI sestavljanju. bsui/form z block="acme/projects" serializira svoja polja z FormData in jih pošlje na končno točko za ustvarjanje tega bloka. Vsak bsui/field vsebuje ime svojega vnosa, zato se napake sheme za posamezna polja prikažejo pod ustreznim kontrolnikom. Če pošljete prazen obrazec, se pod poljem Ime prikaže »Vsebovati mora vsaj 2 znaka.«, pod poljem E-pošta lastnika pa »Vnesite veljaven e-poštni naslov.«; na dnu obrazca se prikaže tudi »Preverjanje veljavnosti ni uspelo.«. Skriti vnos status se pošlje skupaj s podatki obrazca, kar omogoča, da novi projekti izpolnijo zahtevano polje.
Tabela uporablja vašo označevalno kodo. bsui/table je primeren za vrstice, zapisane v predlogi: njegove celice glave razvrščajo tako, da premikajo obstoječe elemente tr, kar bi bilo v sporu s tem, da data-wp-each upravlja vrstice. Pred različico Blockstudio 7.7 so njegovi deli neposredno znotraj elementov table, thead, tbody in tr vsebovali tudi element div, ki ga brskalniki premaknejo iz tabele. Za vrstice iz shrambnega objekta element table napišite sami, sistemske komponente pa ohranite znotraj celic. Značke in gumbi v predlogi vrstice so običajne oznake bsui/badge in bsui/button. Vsak gumb je v elementu span z direktivo za klik, zato ostane sistemski gumb, dejanje pa pripada vašemu shrambnemu objektu.
Obvestilo skrbi za prikaz. bsui/toast-provider izriše vljuden element za sprotna obvestila, bsui/toast pa sporočilo stanja z gumbom za opustitev. Ponudnik se ne postavi na zaslon sam, gumb za opustitev pa ne skrije obvestila, izrisanega iz označevalne kode. Zaslon zato poskrbi za oboje: ovoj z position: fixed postavi območje, vsako obvestilo pa je v elementu div, katerega vezava hidden in obravnava klika pripadata shrambnemu objektu zaslona. Klik na gumb za opustitev se razširi navzgor do tega div.
5. korak: Shrambni objekt
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');
}
},
},
});
Odziv na obrazec. Ob uspešnem shranjevanju bsui/form sproži dogodek formsuccess, ki se razširi navzgor, ga je mogoče preklicati, ustvarjeni zapis pa vsebuje v event.detail. Ob neuspelem shranjevanju sproži formerror z vsebino napake. Poslušalnik je na dokumentu (data-wp-on-document--formsuccess), ne na korenskem elementu zaslona, ker se pojavno okno odprtega pogovornega okna premakne v document.body, zato se njegovi dogodki ne širijo več skozi blok. Preverjanje owner preskoči dogodke iz drugih obrazcev na isti strani.
Klic event.preventDefault() prepreči, da bi obrazec zamenjal polja s sporočilom o uspehu; obrazec se še vedno ponastavi. Dejanje nato doda zapis na začetek seznama, zapre pogovorno okno z dejanjem close shrambnega objekta bsui/dialog in prikaže obvestilo. close zapre najvišje odprto pogovorno okno in vrne fokus na njegov sprožilec, zato se po ustvarjanju fokus tipkovnice vrne na Nov projekt.
Razveljavitev sprememb ob napakah. bs.mutate() takoj uveljavi optimistično spremembo in obnovi prejšnje vrednosti, če je obljuba iz fn zavrnjena. bs.fn() in bs.db() pri napakah HTTP obljube ne zavrneta: WP_Error iz funkcije RPC, neuspešno preverjanje veljavnosti ali manjkajoči zapis se vedno vrnejo v telesu napake. Pomožna funkcija ok() rezultat z code pretvori v zavrnitev, zato se vrstica povrne v prejšnje stanje in prikaže se obvestilo o napaki. Brez nje bi se telo napake združilo z vrstico pri neuspešni posodobitvi, pri neuspešnem brisanju pa bi vrstica ostala odstranjena.
Poimenovanje bloka. Blockstudio izpiše vdelane skripte kot <script type="module">, skripte modulov pa nimajo document.currentScript, zato bs.fn() ne more zaznati, kateri blok kliče. Ime bloka podajte kot tretji argument, kot to stori shrambni objekt z BLOCK.
6. korak: Dodajte zaslon na stran
Stran na podlagi datoteke postavi blok z njegovo oznako:
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
Razčlenjevalnik pretvori oznako v izvorni blok:
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Za ustvarjanje strani zaženite wp bs pages sync. postStatus: "private" jo skrije pred anonimnimi obiskovalci, ki bi sicer videli le sporočilo za prijavo.
Delovanje zaslona med izvajanjem
Ko stran odprete kot urednik:
- Tabela se prikaže z obema izrisanima vrsticama; arhivirana vrstica ima značko Arhivirano in gumb Obnovi.
- Gumb Nov projekt odpre pogovorno okno. Pojavno okno in zatemnitev ozadja se premakneta v
document.body, fokus se pomakne v polje Ime, tipka Escape ali gumb Prekliči pa okno znova zapre. - Ob oddaji veljavnih vrednosti se pošlje en
POSTna/wp-json/blockstudio/v1/db/acme-projects/default. Pogovorno okno se zapre, nova vrstica se prikaže na vrhu, v kotu pa se za štiri sekunde prikaže »Projekt je ustvarjen.«. - Gumb Arhiviraj takoj spremeni značko in pošlje
set_statusprek/wp-json/blockstudio/v1/fn/acme/projects/set_status. Če je bil zapis medtem izbrisan drugje, funkcija vrne napako404, vrstica se vrne v stanje Aktivno, prikaže pa se »Sprememba ni bila shranjena.«. - Gumb Izbriši takoj odstrani vrstico. Ko izbrišete še zadnji projekt, se prikaže »Projektov še ni.«.
Slogi
Lastni CSS zaslona uporablja žetone knjižnice, zato se tabela ujema z okoliškimi komponentami in upošteva morebitne preglasitve teme za lastnosti --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 za 40 ohrani območje obvestil pod zatemnitvijo pogovornega okna, ki je na ravni 50. Če želite spremeniti videz celotnega zaslona, preglasite žetone, kot je opisano v razdelku slogi; spremembo prevzamejo komponente in tabela.
Naslednji koraki
- UIKomponente: sistem oblikovanja, žetoni in celoten nabor komponent.
- UISestavljanje: sestavljene družine, posredovanje sprožilcev in model plastenja v ozadju pogovornega okna.
- Baza podatkov: načini hrambe, nadzor dostopa,
bs.db()inbs.mutate(). - RPC: nadzor dostopa, metode HTTP in klici med bloki.
- Bloki za celoten sklad: isti gradniki v aplikaciji za opravila in prijavi na e-novice.