Перейти до вмісту

Створення екрана застосунку з вбудованими UI

Більшості проєктів WordPress зрештою потрібен екран, що більше схожий на застосунок, ніж на сторінку: список записів, кнопка для відкриття форми, сповіщення про успішне збереження. Зазвичай для цього використовують фреймворк JavaScript, набір контролерів REST і бібліотеку компонентів, які підтримують поруч із темою.

Blockstudio уже містить усі ці компоненти. db.php забезпечує сховище для блоку, перевірку даних і CRUD-ендпоїнти. rpc.php додає власні серверні дії. вбудовані UI компоненти надають діалогове вікно, поля форми, кнопки, значки та сповіщення. Сховище Interactivity API з’єднує їх. У цьому посібнику крок за кроком створюється один екран в одній папці блоку:

  • Таблиця проєктів, відрендерена на сервері й синхронізована з клієнтом.
  • Діалогове вікно Новий проєкт із формою, що перевіряється за схемою.
  • Кнопки Архівувати й Відновити, які викликають функцію RPC з оптимістичним оновленням і відкатом.
  • Кнопки Видалити, які безпосередньо використовують API даних.
  • Сповіщення після успішного створення та ще одне, якщо зміни не вдалося зберегти.

Перш ніж почати

Вбудовані компоненти не ввімкнені за замовчуванням. Увімкніть їх у blockstudio.json:

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
<?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
<?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 даних:

JSON
{"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: визначення блоку

JSON
{
  "$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
<?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() повертає контекст цього рядка, тож архівні рядки мають правильні значок і кнопку ще до гідратації. У браузері керування перебирає гетер сховища з тією самою назвою. 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: сховище

JavaScript
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() одразу застосовує оптимістичну зміну й відновлює попередні значення, якщо проміс від fn відхиляється. bs.fn() та bs.db() не відхиляють проміс у разі помилок HTTP: WP_Error від функції RPC, помилка перевірки чи відсутність запису — все завершується поверненням тіла помилки. Допоміжна функція ok() перетворює результат із code на відхилений проміс, тож рядок повертається до попереднього стану й з’являється сповіщення про помилку. Без неї помилка оновлення потрапила б у рядок, а після невдалого видалення рядок і далі був би відсутній.

Назва блоку. Blockstudio виводить вбудовані скрипти як <script type="module">, а модульні скрипти не мають document.currentScript, тому bs.fn() не може визначити, який блок викликає функцію. Передайте назву блоку третім аргументом, як це робить сховище з BLOCK.

Крок 6: розміщення екрана на сторінці

Тег блоку розміщують на сторінці з файловою структурою:

JSON
{
  "$schema": "https://blockstudio.dev/schema/page",
  "name": "projects",
  "title": "Projects",
  "slug": "projects",
  "postStatus": "private"
}
PHP
<h1>Projects</h1>
<bs:acme-projects />

Парсер перетворює тег на нативний блок:

HTML
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->

Виконайте wp bs pages sync, щоб створити сторінку. postStatus: "private" приховує її від анонімних відвідувачів, які інакше бачили б лише повідомлення про вхід.

Як екран працює під час виконання

Відкрийте сторінку як редактор:

  1. Таблиця завантажується з обома рядками; в архівного рядка є значок В архіві та кнопка Відновити.
  2. Кнопка Новий проєкт відкриває діалогове вікно. Спливне вікно й тло переміщуються до document.body, фокус переходить у поле «Ім’я», а клавіша Escape або кнопка Скасувати закриває вікно.
  3. Надсилання коректних даних виконує один запит POST до /wp-json/blockstudio/v1/db/acme-projects/default. Діалогове вікно закривається, новий рядок з’являється на початку списку, а в кутку на чотири секунди відображається повідомлення «Проєкт створено.»
  4. Натискання Архівувати одразу змінює значок і надсилає set_status через /wp-json/blockstudio/v1/fn/acme/projects/set_status. Якщо тим часом запис було видалено в іншому місці, функція повертає помилку 404, рядок повертається до стану Активний, а на екрані з’являється повідомлення «Не вдалося зберегти зміни.»
  5. Кнопка Видалити одразу прибирає рядок. Після видалення останнього з’являється повідомлення «Проєктів поки немає.»

Стилізація

У власному файлі CSS екрана використовуються токени бібліотеки, тому таблиця пасує до сусідніх компонентів і враховує перевизначення властивостей --bs-ui-* у темі:

CSS
.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 та виклики між блоками.
  • Повнофункціональні блоки: ті самі будівельні блоки в застосунку зі списком справ і формі підписки на розсилку.