Preskočiť na obsah

Vytvorenie obrazovky aplikácie pomocou pribaleného UI

Väčšina projektov WordPress napokon potrebuje obrazovku, ktorá je viac aplikáciou než stránkou: zoznam záznamov, tlačidlo na otvorenie formulára a potvrdenie úspešného uloženia. Zvyčajným riešením je framework JavaScript, sada kontrolérov REST a knižnica komponentov, ktoré sa všetky udržiavajú vedľa témy.

Blockstudio už všetky tieto súčasti obsahuje. db.php poskytuje bloku úložisko, overovanie a koncové body CRUD. rpc.php pridáva vlastné akcie servera. Komponenty pribaleného UI ponúkajú dialógové okno, polia formulára, tlačidlá, odznaky a upozornenia. Úložisko Interactivity API ich prepája. V tomto sprievodcovi vytvoríte kompletnú obrazovku v jedinom priečinku bloku:

  • Tabuľka projektov vykreslená na serveri a priebežne synchronizovaná v klientovi.
  • Dialógové okno Nový projekt s formulárom, ktorý overuje údaje podľa schémy.
  • Tlačidlá Archivovať a Obnoviť, ktoré volajú funkciu RPC s optimistickou aktualizáciou a obnovením pôvodných údajov.
  • Tlačidlá Odstrániť, ktoré používajú dátovú API priamo.
  • Upozornenie po úspešnom vytvorení a ďalšie v prípade, keď sa zmena neuloží.

Skôr než začnete

Pribalené komponenty sú štandardne vypnuté. Zapnite ich v blockstudio.json:

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

Obrazovka sa nachádza v jednom bloku:

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

Krok 1: Dátový model

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ždá operácia vyžaduje oprávnenie edit_posts, takže koncové body vracajú 401 pri požiadavke od odhláseného používateľa a údaje môžu meniť iba redaktori a používatelia s vyššími oprávneniami. Úložisko SQLite uchováva záznamy v projects/db/default.sqlite vedľa kódu.

status je typu required a namiesto hodnoty default nesie referenciu. Pri použití SQLite a tabuľkového úložiska schéma pri vytváraní nedoplní chýbajúcu hodnotu, takže záznam vytvorený bez status sa uloží s prázdnou hodnotou. Ak je pole povinné a odosiela ho formulár, každý riadok zostane platný.

Vytvorte niekoľko úvodných záznamov z príkazového riadka:

Shell
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
Kód
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	...

Zoznam sa vracia zoradený od najnovších záznamov, rovnako ako tabuľka.

Krok 2: Akcia servera

Archivácia z pohľadu používateľa nie je obyčajná úprava poľa, preto má vlastnú pomenovanú funkciu:

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() overuje údaje podľa schémy, takže enum v db.php naďalej kontroluje hodnotu. Volanie funkcie s neznámym stavom vráti rovnaký tvar chyby ako dátová API:

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

Funkciu možno volať aj z príkazového riadka:

Shell
wp bs rpc call acme/projects set_status --id=2 --status=active
Kód
{
    "id": 2,
    "name": "Q3 report",
    "owner": "ben@example.com",
    "status": "active",
    ...
}

Krok 3: Definícia 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 umožňuje, aby WordPress spracovalo direktívy šablóny na serveri. Vďaka tomu sa riadky tabuľky vykreslia ešte pred spustením akéhokoľvek JavaScript.

Krok 4: Šablóna

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>

Štyri časti tejto šablóny si zaslúžia bližší pohľad.

Stav servera pripraví úvodné vykreslenie. wp_interactivity_state() odovzdá záznamy spracovateľovi direktív na strane servera aj úložisku klienta. Šablóna data-wp-each sa na serveri rozbalí na skutočné riadky, po jednom tr pre každý záznam. isArchived je uzáver: WordPress ho počas spracovania servera vyhodnotí pre každý riadok a pomocou wp_interactivity_get_context() vráti kontext daného riadka, takže archivované riadky zobrazujú správny odznak a tlačidlo ešte pred hydratáciou. V prehliadači prevezme jeho úlohu prístupová funkcia úložiska s rovnakým názvom. hasProjects je z rovnakého dôvodu obyčajná hodnota: bez nej by server nevedel, či má skryť odsek informujúci o prázdnom stave.

Dialógové okno a formulár používajú systémové komponenty. trigger_label sa odovzdá komponentu bsui/button vo vnútri spúšťača, ako je opísané v časti ZloženieUI. Komponent bsui/form s block="acme/projects" serializuje polia pomocou FormData a odošle ich koncovému bodu na vytváranie v danom bloku. Každý bsui/field nesie názov svojho vstupného poľa, takže chyby schémy pre jednotlivé polia sa zobrazia pri správnom ovládacom prvku. Po odoslaní prázdneho formulára sa pod poľom Názov zobrazí „Musí obsahovať aspoň 2 znaky.“ a pod poľom E-mail vlastníka „Zadajte platnú e-mailovú adresu.“; na spodku formulára sa navyše zobrazí „Overenie zlyhalo.“. Skryté vstupné pole status sa odošle spolu s údajmi formulára, vďaka čomu nové projekty spĺňajú požiadavku na povinné pole.

Tabuľka používa vašu vlastnú značku HTML. bsui/table sa hodí pre riadky vytvorené v šablóne: jej bunky hlavičky triedia presúvaním existujúcich prvkov tr, čím by narúšali správu riadkov komponentom data-wp-each. Pred verziou Blockstudio 7.7 jej časti vkladali aj prvok div priamo do prvkov table, thead, tbody a tr, odkiaľ ho prehliadače presúvajú mimo tabuľky. Pri riadkoch pochádzajúcich z úložiska vytvorte prvok table sami a systémové komponenty umiestnite do buniek. Odznaky a tlačidlá v šablóne riadka sú obyčajné značky bsui/badge a bsui/button. Každé tlačidlo je v prvku span s direktívou kliknutia, takže zostáva systémovým tlačidlom a akcia patrí vášmu úložisku.

Upozornenie je prezentačná súčasť. bsui/toast-provider vykresľuje zdvorilú živú oblasť a bsui/toast vykresľuje stavovú správu s tlačidlom na zatvorenie. Poskytovateľ sám neurčuje svoju polohu na obrazovke a tlačidlo na zatvorenie neskrýva upozornenie vykreslené zo značky HTML. Obrazovka preto robí oboje: obal s position: fixed umiestni oblasť a každé upozornenie sa nachádza v prvku div, ktorého väzba hidden a obsluha kliknutia patria do úložiska obrazovky. Kliknutie na tlačidlo zatvorenia sa prenesie nahor až k div.

Krok 5: Úložisko

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

Reakcia na formulár. Po úspešnom uložení bsui/form vyšle udalosť formsuccess, ktorá sa šíri, možno ju zrušiť a vytvorený záznam nesie v event.detail. Pri neúspešnom uložení vyšle formerror s telom chyby. Poslucháč je umiestnený na dokumente (data-wp-on-document--formsuccess), nie na koreňovom prvku obrazovky, pretože vyskakovacie okno otvoreného dialógového okna sa presunie do document.body a jeho udalosti sa už nešíria cez blok. Kontrola owner preskočí udalosti z iných formulárov na tej istej stránke.

Volanie event.preventDefault() zabráni tomu, aby formulár nahradil polia správou o úspechu; formulár sa napriek tomu sám obnoví. Akcia potom pridá záznam na začiatok, zatvorí dialógové okno pomocou akcie close úložiska bsui/dialog a zobrazí upozornenie. close zatvorí navrchu otvorené dialógové okno a vráti fokus na jeho spúšťač, takže po vytvorení sa klávesnicový fokus vráti na tlačidlo Nový projekt.

Obnovenie pri chybách. bs.mutate() okamžite vykoná optimistickú zmenu a obnoví predchádzajúce hodnoty, ak dôjde k zamietnutiu prísľubu z fn. bs.fn() ani bs.db() sa pri chybách HTTP nezamietnu: WP_Error z funkcie RPC, zlyhanie overenia alebo chýbajúci záznam vrátia vyriešený prísľub s telom chyby. Pomocná funkcia ok() zmení výsledok obsahujúci code na zamietnutý prísľub, takže sa riadok vráti do pôvodného stavu a zobrazí sa upozornenie na chybu. Bez nej by sa telo chyby po neúspešnej aktualizácii zlúčilo s riadkom a po neúspešnom odstránení by riadok zostal odstránený.

Pomenovanie bloku. Blockstudio vypisuje vložené skripty ako <script type="module"> a modulové skripty nemajú document.currentScript, takže bs.fn() nedokáže zistiť, ktorý blok volá funkciu. Názov bloku odovzdajte ako tretí argument, ako to robí úložisko pomocou BLOCK.

Krok 6: Pridanie obrazovky na stránku

Stránka vytvorená zo súboru umiestni blok pomocou jeho značky:

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

Parser zmení značku na natívny blok:

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

Spustením wp bs pages sync vytvoríte stránku. postStatus: "private" ju skryje pred anonymnými návštevníkmi, ktorí by aj tak videli iba prihlasovaciu správu.

Čo sa deje s obrazovkou počas behu

Otvorte stránku ako redaktor:

  1. Tabuľka sa zobrazí s vykreslenými oboma riadkami; pri archivovanom riadku sa zobrazí odznak Archivované a tlačidlo Obnoviť.
  2. Tlačidlo Nový projekt otvorí dialógové okno. Vyskakovacie okno a pozadie sa presunú do document.body, fokus sa presunie do poľa Názov a klávesom Escape alebo tlačidlom Zrušiť okno zatvoríte.
  3. Odoslaním platných hodnôt sa odošle jedno POST do /wp-json/blockstudio/v1/db/acme-projects/default. Dialógové okno sa zatvorí, nový riadok sa zobrazí navrchu a v rohu sa na štyri sekundy zobrazí „Projekt bol vytvorený.“.
  4. Tlačidlo Archivovať okamžite zmení odznak a odošle set_status cez /wp-json/blockstudio/v1/fn/acme/projects/set_status. Ak bol záznam medzitým odstránený inde, funkcia vráti chybu 404, riadok sa vráti do stavu Aktívne a zobrazí sa „Zmena sa neuložila.“.
  5. Tlačidlo Odstrániť okamžite odstráni riadok. Po odstránení posledného sa zobrazí „Zatiaľ tu nie sú žiadne projekty.“.

Štýlovanie

Vlastný CSS obrazovky používa tokeny knižnice, takže tabuľka ladí s okolitými komponentmi a rešpektuje všetky zmeny témy pre vlastnosti --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 udržiava oblasť upozornení pod pozadím dialógového okna, ktorého úroveň je 50. Ak chcete zmeniť tému celej obrazovky, upravte tokeny podľa pokynov v časti štýlovanie; zmena sa prejaví na komponentoch aj tabuľke.

Ďalšie kroky

  • KomponentyUI: dizajnový systém, tokeny a kompletná sada komponentov.
  • UIZloženie: zložené skupiny, odovzdávanie spúšťačov a model vrstvenia dialógového okna.
  • Databáza: režimy ukladania, riadenie prístupu, bs.db() a bs.mutate().
  • RPC: riadenie prístupu, metódy HTTP a volania medzi blokmi.
  • Bloky s plným zásobníkom: rovnaké stavebné prvky v aplikácii so zoznamom úloh a pri prihlásení na odber noviniek.