Перейти к содержимому

Создание экрана приложения с помощью встроенного 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 и вызовы между блоками.
  • Полнофункциональные блоки: те же строительные блоки в приложении со списком дел и форме подписки на рассылку.