Pereiti prie turinio

Programos ekrano kūrimas naudojant rinkinyje pateikiamą UI

Daugumoje WordPress projektų anksčiau ar vėliau prireikia ekrano, kuris labiau primena programą nei puslapį: įrašų sąrašo, mygtuko formai atverti ir pranešimo, kai įrašas išsaugomas. Įprastai naudojama JavaScript sistema, REST valdiklių rinkinys ir komponentų biblioteka, visa tai prižiūrint šalia temos.

Blockstudio jau pateikia visas šias dalis. db.php suteikia blokų saugyklą, tikrinimą ir CRUD galinius taškus. rpc.php suteikia galimybę kurti pasirinktinius serverio veiksmus. Rinkinyje pateikiami UI komponentai apima dialogo langą, formos laukus, mygtukus, žymas ir pranešimus. Juos sujungia Interactivity API saugykla. Šiame vadove viename bloko aplanke nuo pradžios iki pabaigos sukursime vieną ekraną:

  • Projektų lentelę, kurios eilutės sugeneruojamos serveryje ir sinchronizuojamos kliente.
  • Dialogo langą Naujas projektas su schema patvirtinama forma.
  • Mygtukus Archyvuoti ir Atkurti, kurie iškviečia RPC funkciją ir iškart atnaujina duomenis, o nesėkmės atveju pakeitimus atšaukia.
  • Mygtukus Ištrinti, kurie tiesiogiai naudoja duomenų API.
  • Pranešimą sėkmingai sukūrus įrašą ir kitą, kai pakeitimo nepavyksta išsaugoti.

Prieš pradedant

Rinkinyje pateikiami komponentai nėra įjungti pagal numatytuosius nustatymus. Įjunkite juos faile blockstudio.json:

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

Ekranas yra viename bloke:

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

1 žingsnis: duomenų modelis

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

Kiekvienai operacijai būtina edit_posts galimybė, todėl neprisijungusių naudotojų užklausoms galiniai taškai atsako 401, o duomenis gali keisti tik redaktoriai ir aukštesnio lygio naudotojai. SQLite saugykla laiko įrašus projects/db/default.sqlite, šalia kodo.

status yra required, o ne turi default. Naudojant SQLite ir lentelės saugyklą, kuriant įrašą schema neįrašo trūkstamos reikšmės, todėl be status sukurtame įraše šis laukas lieka tuščias. Nustačius lauką kaip privalomą ir siunčiant jį iš formos, visi įrašai išlieka galiojantys.

Komandų eilutėje pridėkite kelis pradinius įrašus:

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
Kodas
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	...

Sąrašas pateikiamas pradedant naujausiu įrašu – tokia pat tvarka kaip lentelėje.

2 žingsnis: serverio veiksmas

Naudotojui archyvavimas nėra paprastas lauko pakeitimas, todėl jam sukuriama atskira funkcija:

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() tikrina pagal schemą, todėl enum faile db.php vis tiek apsaugo reikšmę. Iškvietus funkciją su nežinoma būsena, grąžinama tokia pati klaidos struktūra kaip duomenų API:

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

Funkciją taip pat galima iškviesti komandų eilutėje:

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

3 žingsnis: bloko aprašas

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 leidžia WordPress serveryje apdoroti šablono direktyvas, todėl lentelės eilutės sugeneruojamos dar prieš vykdant bet kokį JavaScript.

4 žingsnis: šablonas

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>

Verta atidžiau panagrinėti keturias šio šablono dalis.

Pradinę būseną pateikia serveris. wp_interactivity_state() perduoda įrašus ir serverio direktyvų procesoriui, ir kliento saugyklai. Šablonas data-wp-each serveryje išplečiamas į tikras eilutes – po vieną tr kiekvienam įrašui. isArchived yra uždara funkcija: serverio apdorojimo metu WordPress ją įvertina kiekvienai eilutei, o wp_interactivity_get_context() grąžina tos eilutės kontekstą. Todėl po hidratavimo archyvuotos eilutės jau turi tinkamą žymą ir mygtuką. Naršyklėje ją perima tokio paties pavadinimo saugyklos gaviklis. hasProjects yra paprasta reikšmė dėl tos pačios priežasties: be jos serveris nežinotų, ar slėpti pranešimo pastraipą, rodomą, kai sąrašas tuščias.

Dialogo langas ir forma yra sistemos komponentai. trigger_label perduodamas viduje trigerio esančiam bsui/button, kaip aprašyta skyriuje UIKompozicija. bsui/form su block="acme/projects" serializuoja laukus naudodamas FormData ir siunčia juos to bloko kūrimo galiniam taškui. Kiekviename bsui/field nurodomas įvesties lauko pavadinimas, todėl schemos klaidos rodomos prie tinkamo lauko. Pateikus tuščią formą, po lauku „Vardas“ rodoma „Turi būti bent 2 simboliai.“, po lauku „Savininko el. paštas“ – „Įveskite galiojantį el. pašto adresą.“, o formos apačioje – „Tikrinimas nepavyko.“. Paslėptas status įvesties laukas perduodamas kartu su formos duomenimis, todėl nauji projektai atitinka privalomo lauko reikalavimą.

Lentelės žymėjimas yra jūsų pačių. bsui/table tinka eilutėms, aprašytoms šablone: antraštės langeliai rūšiuojami perkeliant esamus tr elementus, todėl data-wp-each konkuruotų dėl eilučių valdymo. Iki Blockstudio 7.7 jo dalys taip pat įterpdavo div tiesiai į table, thead, tbody ir tr, o naršyklės jį perkeldavo už lentelės ribų. Eilutėms, gaunamoms iš saugyklos, patys parašykite elementą table, o sistemos komponentus laikykite langeliuose. Ženkleliai ir mygtukai eilutės šablone yra įprastos bsui/badge ir bsui/button žymos. Kiekvienas mygtukas yra span, kuriame yra paspaudimo direktyva, todėl mygtukas lieka sistemos mygtuku, o veiksmas priklauso jūsų saugyklai.

Pranešimai atlieka tik pateikimo funkciją. bsui/toast-provider sukuria mandagų tiesioginio pranešimo regioną, o bsui/toast pateikia būsenos pranešimą su užvėrimo mygtuku. Teikėjas pats nenustato savo padėties ekrane, o užvėrimo mygtukas nepaslepia pranešimo, sugeneruoto iš žymėjimo. Todėl ekranas atlieka abu veiksmus: apvalkalas su position: fixed nustato regiono vietą, o kiekvienas pranešimas įdedamas į div, kurio hidden susiejimas ir paspaudimo apdorojimo funkcija priklauso ekrano saugyklai. Paspaudus užvėrimo mygtuką, įvykis perduodamas šiam div.

5 žingsnis: saugykla

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

Formos įvykių apdorojimas. Sėkmingai išsaugojus, bsui/form išsiunčia formsuccess įvykį, kuris perduodamas aukštyn, gali būti atšauktas ir turi sukurtą įrašą event.detail. Nepavykus išsaugoti, išsiunčiamas formerror su klaidos turiniu. Klausytojas prijungtas prie dokumento (data-wp-on-document--formsuccess), o ne prie pagrindinio ekrano elemento, nes atviro dialogo iššokantysis langas perkeliamas į document.body, tad jo įvykiai nebepasiekia bloko. Patikra owner praleidžia kitų tame pačiame puslapyje esančių formų įvykius.

Iškvietus event.preventDefault(), formos laukai nepakeičiami sėkmės pranešimu, tačiau forma vis tiek išvaloma. Tada veiksmas įrašo naują elementą sąrašo pradžioje, užveria dialogo langą naudodamas bsui/dialog saugyklos veiksmą close ir parodo pranešimą. close užveria viršuje esantį atvirą dialogo langą ir grąžina židinį į jį atvėrusį elementą, todėl sukūrus įrašą klaviatūros židinys grįžta į Naujas projektas.

Pakeitimų atšaukimas įvykus klaidai. bs.mutate() iškart pritaiko optimistinį pakeitimą, o atkuria ankstesnes reikšmes, jei atmetamas fn pažadas. bs.fn() ir bs.db() neatmeta pažado įvykus HTTP klaidoms: RPC funkcijos grąžinta WP_Error, tikrinimo klaida arba nerastas įrašas – visais atvejais grąžinamas klaidos turinys. Pagalbinė funkcija ok() rezultatą, kuriame yra code, paverčia atmetimu, todėl eilutė grįžta į ankstesnę būseną ir parodomas klaidos pranešimas. Be jos nepavykus atnaujinti įrašo, klaidos turinys būtų įtrauktas į eilutę, o nepavykus jo ištrinti, eilutė liktų pašalinta.

Bloko pavadinimo nurodymas. Blockstudio išveda tiesioginius scenarijus kaip <script type="module">, o modulio scenarijai neturi document.currentScript, todėl bs.fn() negali nustatyti, kuris blokas jį iškviečia. Perduokite bloko pavadinimą kaip trečią argumentą, kaip tai daro saugykla su BLOCK.

6 žingsnis: įdėkite ekraną į puslapį

puslapis iš failo įdeda bloką naudodamas jo žymą:

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

Analizatorius žymą paverčia vietiniu bloku:

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

Puslapiui sukurti paleiskite wp bs pages sync. postStatus: "private" neleidžia jo matyti neprisijungusiems lankytojams, kurie vis tiek matytų tik prisijungimo pranešimą.

Ekrano veikimas

Atvėrę puslapį kaip redaktorius:

  1. Lentelėje rodomos abi sugeneruotos eilutės, o archyvuota eilutė turi žymą Suarchyvuota ir mygtuką Atkurti.
  2. Paspaudus Naujas projektas, atveriamas dialogo langas. Iššokantysis langas ir fonas perkeliami į document.body, židinys nustatomas vardo lauke, o paspaudus Escape arba Atšaukti langas užveriamas.
  3. Pateikus tinkamas reikšmes, išsiunčiamas vienas POST į /wp-json/blockstudio/v1/db/acme-projects/default. Dialogo langas užveriamas, nauja eilutė atsiranda sąrašo viršuje, o kampe keturias sekundes rodomas pranešimas „Projektas sukurtas.“.
  4. Paspaudus Archyvuoti, žyma iškart pasikeičia ir set_status išsiunčiamas per /wp-json/blockstudio/v1/fn/acme/projects/set_status. Jei tuo metu įrašas jau ištrintas kitur, funkcija grąžina klaidą 404, eilutė vėl tampa Aktyvi, o pranešimas „Pakeitimas neišsaugotas.“.
  5. Paspaudus Ištrinti, eilutė iškart pašalinama. Ištrynus paskutinę, rodomas pranešimas „Projektų dar nėra.“.

Stiliai

Ekrano CSS skaito bibliotekos žetonus, todėl lentelė dera su aplinkiniais komponentais ir atsižvelgia į temos --bs-ui-* savybių pakeitimus:

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;
}

40 naudojamas z-index sluoksnis palieka pranešimų regioną po dialogo lango fonu, kurio sluoksnis yra 50. Norėdami pakeisti viso ekrano temą, perrašykite žetonus, kaip aprašyta skyriuje stilių nustatymas; pakeitimai taikomi ir komponentams, ir lentelei.

Tolesni veiksmai

  • UI komponentai: dizaino sistema, žetonai ir visas komponentų rinkinys.
  • UI Kompozicija: sudėtinės komponentų grupės, trigerio parametrų perdavimas ir dialogo lango sluoksniavimo modelis.
  • Duomenų bazė: saugojimo režimai, prieigos kontrolė, bs.db() ir bs.mutate().
  • RPC: prieigos kontrolė, HTTP metodai ir skirtingų blokų iškvietimai.
  • Viso steko blokai: tie patys pagrindiniai komponentai užduočių programoje ir naujienlaiškio prenumeratos formoje.