Przejdź do treści

Tworzenie ekranu aplikacji z dołączonym UI

Większość projektów WordPress prędzej czy później potrzebuje ekranu, który bardziej przypomina aplikację niż stronę: listy rekordów, przycisku otwierającego formularz i informacji zwrotnej po zapisaniu. Typowym rozwiązaniem jest framework JavaScript, zestaw kontrolerów REST i biblioteka komponentów, utrzymywane obok motywu.

Blockstudio zawiera już wszystkie te elementy. db.php zapewnia przechowywanie bloków, walidację i punkty końcowe CRUD. rpc.php dodaje niestandardowe akcje serwera. Komponenty dołączonego UIbsui zapewniają okno dialogowe, pola formularza, przyciski, plakietki i powiadomienia toast. Magazyn Interactivity API łączy te elementy. W tym przewodniku zbudujemy kompletny ekran w jednym folderze bloku:

  • Tabela projektów renderowana na serwerze i synchronizowana po stronie klienta.
  • Okno dialogowe Nowy projekt z formularzem sprawdzanym względem schematu.
  • Przyciski Archiwizuj i Przywróć, które wywołują funkcję RPC z optymistyczną aktualizacją i wycofaniem zmian.
  • Przyciski Usuń, które bezpośrednio korzystają z danych API.
  • Powiadomienie toast po pomyślnym utworzeniu oraz kolejne, gdy zmiana nie zostanie zapisana.

Zanim zaczniesz

Dołączone komponenty są opcjonalne. Włącz je w blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

Ekran mieści się w jednym bloku:

Kod
acme/
└── blockstudio/
    └── projects/
        ├── block.json
        ├── db.php
        ├── rpc.php
        ├── index.php
        ├── script.inline.js
        └── style.inline.css

Krok 1: Model danych

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,
        ],
    ],
];

Każda operacja wymaga uprawnienia edit_posts, więc punkty końcowe zwracają 401 na żądanie wylogowanego użytkownika, a zmieniać dane mogą tylko redaktorzy i osoby o wyższych uprawnieniach. Przechowywanie SQLite trzyma rekordy w projects/db/default.sqlite, obok kodu.

status jest typu required, a nie przenosi wartości default. Przy SQLite i przechowywaniu w tabeli schemat nie uzupełnia brakującej wartości podczas tworzenia, więc rekord utworzony bez status zostaje zapisany z pustą wartością. Ustawienie tego pola jako wymaganego i przesyłanie go z formularza zapewnia poprawność każdego wiersza.

Dodaj kilka rekordów z wiersza poleceń:

Powłoka
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
Kod
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	...

Lista wraca w kolejności od najnowszych, zgodnie z kolejnością używaną w tabeli.

Krok 2: Akcja serwera

Z perspektywy użytkownika archiwizacja nie jest zwykłą zmianą pola, dlatego ma własną nazwaną funkcję:

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() sprawdza dane względem schematu, więc enum w db.php nadal pilnuje poprawności wartości. Wywołanie funkcji z nieznanym statusem zwraca taki sam format błędu jak dane API:

JSON
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}

Funkcję można też wywołać z wiersza poleceń:

Powłoka
wp bs rpc call acme/projects set_status --id=2 --status=active
Kod
{
    "id": 2,
    "name": "Q3 report",
    "owner": "ben@example.com",
    "status": "active",
    ...
}

Krok 3: Definicja bloku

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 sprawia, że WordPress przetwarza dyrektywy szablonu na serwerze, dzięki czemu wiersze tabeli są renderowane, zanim uruchomi się jakiekolwiek JavaScript.

Krok 4: Szablon

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>

Cztery elementy tego szablonu zasługują na bliższe omówienie.

Stan serwera przygotowuje pierwsze renderowanie. wp_interactivity_state() przekazuje rekordy zarówno procesorowi dyrektyw po stronie serwera, jak i magazynowi klienta. Szablon data-wp-each rozwija się na serwerze w rzeczywiste wiersze, po jednym tr na rekord. isArchived jest domknięciem: WordPress oblicza je dla każdego wiersza podczas przetwarzania na serwerze, a wp_interactivity_get_context() zwraca kontekst tego wiersza, dzięki czemu zarchiwizowane wiersze pokazują właściwą plakietkę i przycisk jeszcze przed nawodnieniem. W przeglądarce zastępuje je getter o tej samej nazwie z magazynu. hasProjects jest zwykłą wartością z tego samego powodu: bez niej serwer nie wiedziałby, czy ukryć akapit o pustym stanie.

Dialog i formularz są komponentami systemowymi. trigger_label jest przekazywany do bsui/button wewnątrz elementu wyzwalającego, jak opisano w UI Kompozycja. bsui/form z block="acme/projects" serializuje swoje pola za pomocą FormData i wysyła je do endpointu tworzenia tego bloku. Każdy bsui/field zawiera nazwę swojego pola wejściowego, dzięki czemu błędy dotyczące poszczególnych pól ze schematu trafiają pod właściwe kontrolki. Wysłanie pustego formularza wyświetla pod polem Name komunikat „Must be at least 2 characters.”, pod polem Owner email komunikat „Must be a valid email address.”, a na dole formularza „Validation failed.”. Ukryte pole wejściowe status jest przesyłane wraz z danymi formularza, co pozwala nowym projektom spełnić wymagania dotyczące obowiązkowego pola.

Tabela jest zdefiniowana w Twoim własnym znaczniku. bsui/table sprawdza się w przypadku wierszy zapisanych w szablonie: komórki nagłówka sortują dane, przesuwając istniejące elementy tr, co kolidowałoby z data-wp-each, który zarządza wierszami. Przed wersją Blockstudio 7.7 jego części umieszczały również element div bezpośrednio wewnątrz table, thead, tbody i tr, skąd przeglądarki przenoszą je poza tabelę. W przypadku wierszy pochodzących z magazynu danych utwórz samodzielnie element table i umieść komponenty systemowe wewnątrz komórek. Odznaki i przyciski w szablonie wiersza to zwykłe znaczniki bsui/badge i bsui/button. Każdy przycisk znajduje się w elemencie span zawierającym dyrektywę obsługi kliknięcia, dzięki czemu przycisk pozostaje przyciskiem systemowym, a akcja należy do Twojego magazynu danych.

Toast odpowiada za prezentację. bsui/toast-provider renderuje grzeczny obszar na żywo, a bsui/toast renderuje komunikat o stanie z przyciskiem zamykania. Dostawca nie pozycjonuje się na ekranie, a przycisk zamykania nie ukrywa toastu wyrenderowanego ze znacznika. Ekran robi więc obie rzeczy: kontener z position: fixed umieszcza obszar, a każdy toast znajduje się w div, którego powiązanie hidden i obsługa kliknięcia należą do magazynu ekranu. Kliknięcie przycisku zamykania propaguje się do tego div.

Krok 5: Magazyn

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');
            }
        },
    },
});

Reakcja na formularz. Po pomyślnym zapisie bsui/form wysyła zdarzenie formsuccess, które propaguje się dalej, można je anulować, a utworzony rekord zawiera w event.detail. Nieudany zapis wysyła formerror z treścią błędu. Nasłuchiwanie odbywa się na dokumencie (data-wp-on-document--formsuccess), a nie na elemencie głównym ekranu, ponieważ wyskakujące okno otwartego dialogu jest przenoszone do document.body, więc jego zdarzenia nie propagują się już przez blok. Sprawdzenie owner pomija zdarzenia pochodzące z innych formularzy na tej samej stronie.

Wywołanie event.preventDefault() powstrzymuje formularz przed zastąpieniem pól komunikatem o powodzeniu; formularz nadal sam się resetuje. Następnie akcja dodaje rekord na początku listy, zamyka okno dialogowe akcją close magazynu bsui/dialog i wyświetla toast. close zamyka najwyżej położone otwarte okno dialogowe i przywraca fokus na jego wyzwalacz, więc po utworzeniu projektu fokus klawiatury wraca do Nowy projekt.

Wycofywanie zmian po błędach. bs.mutate() natychmiast stosuje optymistyczną zmianę i przywraca poprzednie wartości, gdy obietnica z fn zostaje odrzucona. bs.fn() i bs.db() nie odrzucają obietnicy w przypadku błędów HTTP: WP_Error z funkcji RPC, błędu walidacji lub braku rekordu. Zwracają wtedy treść błędu. Pomocnicza funkcja ok() zamienia wynik zawierający code na odrzucenie obietnicy, dzięki czemu wiersz wraca do poprzedniego stanu i pojawia się toast o niepowodzeniu. Bez niej nieudana aktualizacja włączyłaby treść błędu do wiersza, a po nieudanym usunięciu wiersz pozostałby usunięty.

Nadawanie nazwy blokowi. Blockstudio wyświetla skrypty wbudowane jako <script type="module">, a skrypty modułów nie mają document.currentScript, więc bs.fn() nie może wykryć, który blok je wywołuje. Przekaż nazwę bloku jako trzeci argument, tak jak magazyn robi to za pomocą BLOCK.

Krok 6: Umieszczenie ekranu na stronie

Strona oparta na plikach umieszcza blok za pomocą jego znacznika:

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

Parser przekształca ten znacznik w natywny blok:

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

Uruchom wp bs pages sync, aby utworzyć stronę. postStatus: "private" ukrywa ją przed anonimowymi odwiedzającymi, którzy i tak zobaczyliby jedynie komunikat logowania.

Działanie ekranu w czasie wykonywania

Po otwarciu strony jako redaktor:

  1. Tabela wyświetla oba wiersze; zarchiwizowany wiersz ma plakietkę Zarchiwizowano i przycisk Przywróć.
  2. Kliknięcie Nowy projekt otwiera okno dialogowe. Wyskakujące okno i przyciemnione tło są przenoszone do document.body, fokus trafia do pola Nazwa, a klawisz Escape lub przycisk Anuluj zamyka okno.
  3. Wysłanie poprawnych wartości wysyła jedno POST do /wp-json/blockstudio/v1/db/acme-projects/default. Okno dialogowe się zamyka, nowy wiersz pojawia się na górze, a w rogu przez cztery sekundy wyświetla się komunikat „Utworzono projekt”.
  4. Kliknięcie Archiwizuj natychmiast zmienia plakietkę i wysyła set_status przez /wp-json/blockstudio/v1/fn/acme/projects/set_status. Jeśli rekord został w międzyczasie usunięty, funkcja zwraca błąd 404, wiersz wraca do stanu Aktywny, a na ekranie pojawia się komunikat „Nie zapisano tej zmiany”.
  5. Kliknięcie Usuń natychmiast usuwa wiersz. Usunięcie ostatniego wyświetla komunikat „Nie ma jeszcze żadnych projektów”.

Stylowanie

Własny arkusz CSS ekranu korzysta z tokenów biblioteki, dzięki czemu tabela pasuje do otaczających ją komponentów i uwzględnia nadpisania właściwości --bs-ui-* w motywie:

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 warstwy 40 utrzymuje obszar toastów pod przyciemnionym tłem okna dialogowego, które znajduje się na poziomie 50. Aby zmienić motyw całego ekranu, nadpisz tokeny zgodnie z opisem w sekcji stylowanie; zmiana obejmie komponenty i tabelę.

Następne kroki

  • UIKomponenty: system projektowy, tokeny i pełny zestaw komponentów.
  • UIKompozycja: rodziny złożonych komponentów, przekazywanie właściwości wyzwalaczy i model warstw okna dialogowego.
  • Baza danych: tryby przechowywania, kontrola dostępu, bs.db() i bs.mutate().
  • RPC: kontrola dostępu, metody HTTP i wywołania między blokami.
  • Bloki pełnego stosu: te same elementy składowe w aplikacji listy zadań i formularzu zapisu do newslettera.