Създаване на екран на приложение с включения UI
Повечето проекти с WordPress рано или късно имат нужда от екран, който прилича повече на приложение, отколкото на страница: списък със записи, бутон за отваряне на формуляр и потвърждение при успешно записване. Обичайното решение е рамка за JavaScript, набор от контролери REST и библиотека от компоненти, поддържани заедно с темата.
Blockstudio вече включва всяка от тези части. db.php предоставя съхранение на блокове, проверка и CRUD крайни точки. rpc.php добавя персонализирани действия на сървъра. Включените компоненти UI предоставят диалоговия прозорец, полетата на формуляра, бутоните, значките и известията. Хранилище на Interactivity API свързва тези части. Това ръководство изгражда цял екран от начало до край в една папка на блок:
- Таблица с проекти, изобразена на сървъра и поддържана в синхрон с клиента.
- Диалогов прозорец Нов проект с формуляр, който проверява данните спрямо схемата.
- Бутони Архивиране и Възстановяване, които извикват функция RPC с оптимистично обновяване и връщане назад.
- Бутони Изтриване, които използват директно данните API.
- Известие след успешно създаване и друго, когато промените не се запишат.
Преди да започнете
Включените компоненти са опционални. Активирайте ги в blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
Екранът се намира в един блок:
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
Стъпка 1: Моделът на данните
<?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,
],
],
];
Всяка операция изисква възможността edit_posts, затова крайните точки връщат 401 при заявка от излязъл потребител и само редактори или потребители с по-високи права могат да променят данните. Съхранението SQLite пази записите в projects/db/default.sqlite, редом с кода.
status е required, вместо да съдържа default. При SQLite и съхранение в таблица схемата не запълва липсваща стойност при създаване, затова запис, създаден без status, се съхранява с празна стойност. Ако направите полето задължително и го изпращате от формуляра, всеки ред ще остане валиден.
Добавете няколко примерни записа от командния ред:
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 ...
Списъкът се връща с най-новите записи най-отгоре, както е подредена таблицата.
Стъпка 2: Действие на сървъра
Архивирането не е просто промяна на поле от гледна точка на потребителя, затова за него има отделна именувана функция:
<?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() проверява стойността спрямо схемата, така че enum в db.php продължава да я защитава. Извикването на функцията с неизвестен статус връща същия формат на грешка като данните API:
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
Функцията може да се извиква и от командния ред:
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
Стъпка 3: Дефиниция на блока
{
"$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 кара WordPress да обработва директивите на шаблона на сървъра, така че редовете в таблицата се изобразяват преди изпълнението на който и да е JavaScript.
Стъпка 4: Шаблонът
<?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>
Четири части от този шаблон заслужават по-внимателен преглед.
Състоянието на сървъра задава първоначалния изглед. wp_interactivity_state() предоставя записите както на процесора на директиви от страната на сървъра, така и на клиентското хранилище. Шаблонът data-wp-each се разгръща в реални редове на сървъра — по един tr за всеки запис. isArchived е затваряне: WordPress го изчислява за всеки ред при обработката на сървъра, а wp_interactivity_get_context() връща контекста на съответния ред, така че архивираните редове показват правилната значка и бутон още преди хидратацията. В браузъра getter-ът със същото име от хранилището поема тази роля. hasProjects е обикновена стойност по същата причина: без нея сървърът няма да знае дали да скрие абзаца за празно състояние.
Диалоговият прозорец и формулярът са системни компоненти. trigger_label се предава на bsui/button вътре в спусъка, както е описано в Композиция UI. bsui/form с block="acme/projects" сериализира полетата си с FormData и ги изпраща към крайната точка за създаване на този блок. Всеки bsui/field съдържа името на съответното поле, така че грешките за отделните полета от схемата се показват под правилния контрол. При изпращане на празен формуляр под „Име“ се показва „Трябва да е дълго поне 2 знака.“, под „Имейл на собственик“ — „Трябва да е валиден имейл адрес.“, а в долната част на формуляра — „Проверката не бе успешна.“. Скритото поле за въвеждане status се изпраща с данните на формуляра, за да отговарят новите проекти на задължителното поле.
Таблицата използва ваша маркировка. bsui/table е подходящ за редове, написани в шаблона: заглавните клетки сортират, като преместват съществуващите елементи tr, което би влязло в конфликт с data-wp-each за управлението на редовете. Преди Blockstudio 7.7 неговите части поставяха и div директно в table, thead, tbody и tr, откъдето браузърите го преместваха извън таблицата. За редове, идващи от хранилище, напишете сами елемента table и поставете системните компоненти в клетките. Значките и бутоните в шаблона на реда са обикновени тагове bsui/badge и bsui/button. Всеки бутон е в span, което съдържа директивата за щракване, така че бутонът остава системният бутон, а действието принадлежи на вашето хранилище.
Известието е само за представяне. bsui/toast-provider изобразява регион за учтиви съобщения, а bsui/toast изобразява съобщение за състояние с бутон за затваряне. Доставчикът не се позиционира на екрана, а бутонът за затваряне не скрива известие, изобразено от маркировка. Затова екранът прави и двете: обвивка с position: fixed позиционира региона, а всяко известие е в div, чието свързване hidden и манипулатор за щракване принадлежат на хранилището на екрана. Щракването върху бутона за затваряне се разпространява до това div.
Стъпка 5: Хранилището
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');
}
},
},
});
Обработка на формуляра. При успешно записване bsui/form изпраща събитие formsuccess, което се разпространява, може да бъде отменено и съдържа създадения запис в event.detail. При неуспешно записване се изпраща formerror с тялото на грешката. Слушателят е на документа (data-wp-on-document--formsuccess), а не на кореновия елемент на екрана, защото изскачащият диалогов прозорец се премества в document.body и събитията му вече не се разпространяват през блока. Проверка owner пропуска събития от други формуляри на същата страница.
Извикването на event.preventDefault() не позволява на формуляра да замени полетата си със съобщение за успех; формулярът все пак се нулира. След това действието добавя записа в началото, затваря диалоговия прозорец с действието close на хранилището bsui/dialog и показва известието. close затваря най-горния отворен диалогов прозорец и връща фокуса към неговия спусък, така че след създаване клавиатурният фокус е отново върху Нов проект.
Възстановяване при грешки. bs.mutate() прилага оптимистичната промяна незабавно и възстановява предишните стойности, ако Promise от fn бъде отхвърлен. bs.fn() и bs.db() не отхвърлят Promise при грешки HTTP: WP_Error от функцията RPC, грешка при проверката или липсващ запис; вместо това връщат тялото на грешката. Помощната функция ok() превръща резултат с code в отхвърлен Promise, така че редът се връща към предишното състояние и се показва известие за неуспех. Без нея неуспешното обновяване би сляло тялото на грешката с реда, а неуспешното изтриване би оставило реда премахнат.
Именуване на блока. Blockstudio отпечатва вградените скриптове като <script type="module">, а скриптовете на модулите нямат document.currentScript, така че bs.fn() не може да установи кой блок извършва извикването. Подайте името на блока като трети аргумент, както прави хранилището с BLOCK.
Стъпка 6: Поставяне на екрана в страница
Страница, базирана на файл, поставя блока чрез неговия таг:
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
Парсерът преобразува тага в нативен блок:
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Изпълнете wp bs pages sync, за да създадете страницата. postStatus: "private" не я показва на анонимните посетители, които иначе биха видели съобщението за влизане.
Какво прави екранът по време на изпълнение
При отворена страница като редактор:
- Таблицата се показва с двата изобразени реда; архивираният ред има значка Архивиран и бутон Възстановяване.
- Нов проект отваря диалоговия прозорец. Изскачащият прозорец и затъмненият фон се преместват в
document.body, фокусът попада в полето „Име“, а с Escape или Отказ прозорецът се затваря. - Изпращането на валидни данни изпраща едно
POSTкъм/wp-json/blockstudio/v1/db/acme-projects/default. Диалоговият прозорец се затваря, новият ред се появява най-отгоре и в ъгъла за четири секунди се показва „Проектът е създаден.“ - Архивиране незабавно променя значката и изпраща
set_statusчрез/wp-json/blockstudio/v1/fn/acme/projects/set_status. Ако междувременно записът е бил изтрит другаде, функцията връща своята грешка404, редът се връща към Активен и се показва „Промяната не бе запазена.“ - Изтриване незабавно премахва реда. Изтриването на последния ред показва „Все още няма проекти.“
Стилизиране
Собственият CSS на екрана чете токените на библиотеката, така че таблицата съответства на околните компоненти и следва всяка промяна на темата в свойствата --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 държи региона за известия под фона на диалоговия прозорец, който е на ниво 50. За да промените темата на целия екран, задайте токените както е описано в раздела стилизирането; това важи както за компонентите, така и за таблицата.
Следващи стъпки
- Компоненти UI: системата за дизайн, токените и пълният набор от компоненти.
- Композиция UI: съставни семейства, предаване на спусъка и моделът на слоевете зад диалоговия прозорец.
- База данни: режими на съхранение, контрол на достъпа,
bs.db()иbs.mutate(). - RPC: контрол на достъпа, методи HTTP и извиквания между блокове.
- Блокове с пълен стек: същите основни елементи в приложение за задачи и форма за записване за бюлетин.