Treci la conținut

Construirea unui ecran de aplicație cu UI inclus

Majoritatea proiectelor WordPress au, în cele din urmă, nevoie de un ecran care seamănă mai mult cu o aplicație decât cu o pagină: o listă de înregistrări, un buton care deschide un formular și o confirmare după salvare. Soluția obișnuită este un framework JavaScript, un set de controllere REST și o bibliotecă de componente, toate întreținute alături de temă.

Blockstudio include deja fiecare dintre aceste componente. db.php oferă stocarea blocurilor, validare și endpoint-uri CRUD. rpc.php adaugă acțiuni personalizate pe server. Componentele UI incluse oferă dialogul, câmpurile formularului, butoanele, insignele și notificările toast. Un store Interactivity API le conectează. Acest ghid construiește un ecran complet, cap-coadă, într-un singur director de bloc:

  • Un tabel cu proiecte, randat pe server și menținut sincronizat pe client.
  • Un dialog Proiect nou cu un formular validat conform schemei.
  • Butoanele Arhivează și Restaurează, care apelează o funcție RPC cu o actualizare optimistă și o revenire la starea anterioară.
  • Butoanele Șterge, care folosesc direct datele API.
  • O notificare toast după crearea cu succes și alta când o modificare nu se salvează.

Înainte de a începe

Componentele incluse sunt opționale. Activați-le în blockstudio.json:

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

Ecranul se află într-un singur bloc:

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

Pasul 1: Modelul de date

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

Fiecare operație necesită capabilitatea edit_posts, așa că endpoint-urile răspund cu 401 la o cerere de la un utilizator neautentificat, iar doar editorii și rolurile superioare pot modifica datele. Stocarea SQLite păstrează înregistrările în projects/db/default.sqlite, alături de cod.

status este required în loc să conțină un default. Cu SQLite și stocarea în tabel, schema nu completează o valoare lipsă la creare, așa că o înregistrare creată fără status este stocată cu o valoare goală. Marcarea câmpului ca obligatoriu și trimiterea lui din formular asigură validitatea fiecărui rând.

Adăugați câteva înregistrări din linia de comandă:

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
Cod
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 este returnată de la cea mai nouă înregistrare la cea mai veche, în ordinea folosită de tabel.

Pasul 2: O acțiune pe server

Din perspectiva utilizatorului, arhivarea nu este o simplă modificare de câmp, așa că primește o funcție cu nume propriu:

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() validează conform schemei, astfel încât enum din db.php continuă să verifice valoarea. Apelarea funcției cu o stare necunoscută returnează aceeași structură de eroare ca datele API:

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

Funcția poate fi apelată și din linia de comandă:

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

Pasul 3: Definiția blocului

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 îi cere lui WordPress să proceseze directivele șablonului pe server, ceea ce permite randarea rândurilor tabelului înainte de rularea oricărui JavaScript.

Pasul 4: Șablonul

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>

Patru părți ale acestui șablon merită analizate mai îndeaproape.

Starea serverului furnizează datele pentru prima randare. wp_interactivity_state() transmite înregistrările atât procesorului de directive de pe server, cât și store-ului client. Șablonul data-wp-each se extinde în rânduri reale pe server, câte unul tr pentru fiecare înregistrare. isArchived este o închidere: WordPress o evaluează pentru fiecare rând în timpul procesării pe server, iar wp_interactivity_get_context() returnează contextul rândului respectiv, astfel încât rândurile arhivate să afișeze insigna și butonul corecte înainte de hidratare. În browser, getter-ul store-ului cu același nume preia controlul. hasProjects este o valoare simplă din același motiv: fără ea, serverul nu ar ști dacă trebuie să ascundă paragraful pentru starea goală.

Dialogul și formularul folosesc componente de sistem. trigger_label este transmis către bsui/button din interiorul declanșatorului, după cum este descris în compozițiaUI. bsui/form cu block="acme/projects" serializează câmpurile folosind FormData și le trimite către endpoint-ul de creare al blocului. Fiecare bsui/field poartă numele intrării sale, astfel încât erorile de validare pentru fiecare câmp din schemă să apară sub controlul corespunzător. Trimiterea formularului gol afișează „Trebuie să aibă cel puțin 2 caractere.” sub Nume și „Adresa de e-mail trebuie să fie validă.” sub E-mailul proprietarului, plus „Validarea a eșuat.” în partea de jos a formularului. Intrarea ascunsă status este trimisă împreună cu datele formularului, astfel încât proiectele noi să îndeplinească cerința câmpului obligatoriu.

Tabelul folosește markup-ul propriu. bsui/table este potrivit pentru rândurile scrise în șablon: celulele de antet sortează mutând elementele tr existente, ceea ce ar intra în conflict cu data-wp-each pentru controlul rândurilor. Înainte de Blockstudio 7.7, componentele sale inserau și un div direct în table, thead, tbody și tr, iar browserele îl mută în afara tabelului. Pentru rândurile provenite dintr-un store, scrieți singuri elementul table și păstrați componentele de sistem în interiorul celulelor. Insignele și butoanele din șablonul rândului sunt etichete obișnuite bsui/badge și bsui/button. Fiecare buton se află într-un span care conține directiva pentru clic, astfel încât butonul să rămână butonul de sistem, iar acțiunea să aparțină store-ului propriu.

Notificarea toast are rol de prezentare. bsui/toast-provider randează o regiune live politicoasă, iar bsui/toast randează un mesaj de stare cu un buton de închidere. Furnizorul nu își stabilește singur poziția pe ecran, iar butonul de închidere nu ascunde o notificare toast randată din markup. Prin urmare, ecranul le face pe amândouă: un container cu position: fixed poziționează regiunea, iar fiecare notificare toast se află într-un div, a cărui legare hidden și al cărui handler de clic aparțin store-ului ecranului. Clicul pe butonul de închidere se propagă până la acel div.

Pasul 5: Store-ul

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

Reacția la formular. La salvarea cu succes, bsui/form declanșează un eveniment formsuccess care se propagă, poate fi anulat și conține în event.detail înregistrarea creată. O salvare eșuată declanșează formerror cu corpul erorii. Ascultătorul este atașat la document (data-wp-on-document--formsuccess), nu la elementul rădăcină al ecranului, deoarece fereastra pop-up a unui dialog deschis este mutată în document.body, iar evenimentele sale nu se mai propagă prin bloc. Verificarea owner ignoră evenimentele provenite de la alte formulare de pe aceeași pagină.

Apelarea lui event.preventDefault() împiedică formularul să-și înlocuiască câmpurile cu mesajul de succes; formularul se resetează totuși. Apoi acțiunea adaugă înregistrarea la începutul listei, închide dialogul folosind acțiunea close a store-ului bsui/dialog și afișează notificarea toast. close închide dialogul deschis cel mai recent și redă focalizarea declanșatorului, astfel încât după creare focalizarea tastaturii revine la Proiect nou.

Revenirea după erori. bs.mutate() aplică imediat modificarea optimistă și restabilește valorile anterioare când promisiunea de la fn este respinsă. bs.fn() și bs.db() nu sunt respinse la erori HTTP: o eroare WP_Error de la funcția RPC, o eroare de validare sau o înregistrare inexistentă returnează rezultatul cu corpul erorii. Helper-ul ok() transformă un rezultat care conține code într-o respingere, astfel încât rândul revine la starea anterioară și apare notificarea de eroare. Fără acesta, o actualizare eșuată ar combina corpul erorii cu rândul, iar o ștergere eșuată ar lăsa rândul eliminat.

Denumirea blocului. Blockstudio afișează scripturile inline ca <script type="module">, iar scripturile modul nu au document.currentScript, așa că bs.fn() nu poate detecta blocul care face apelul. Transmiteți numele blocului ca al treilea argument, așa cum face store-ul cu BLOCK.

Pasul 6: Adăugarea ecranului pe o pagină

O pagină bazată pe fișiere adaugă blocul folosind eticheta sa:

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

Parserul transformă eticheta într-un bloc nativ:

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

Rulați wp bs pages sync pentru a crea pagina. postStatus: "private" o ascunde de vizitatorii anonimi, care oricum ar vedea doar mesajul de autentificare.

Ce face ecranul în timpul execuției

Cu pagina deschisă ca editor:

  1. Tabelul apare cu ambele rânduri randate, iar rândul arhivat afișează insigna Arhivat și butonul Restaurează.
  2. Proiect nou deschide dialogul. Fereastra pop-up și fundalul întunecat sunt mutate în document.body, focalizarea ajunge în câmpul Nume, iar Escape sau Anulează închide dialogul.
  3. Trimiterea unor valori valide trimite un singur POST către /wp-json/blockstudio/v1/db/acme-projects/default. Dialogul se închide, noul rând apare în partea de sus, iar mesajul „Proiect creat.” apare în colț timp de patru secunde.
  4. Arhivează schimbă imediat insigna și trimite set_status prin /wp-json/blockstudio/v1/fn/acme/projects/set_status. Dacă între timp înregistrarea a fost ștearsă din altă parte, funcția returnează eroarea 404, rândul revine la starea Activ, iar mesajul „Modificarea nu a fost salvată.” apare.
  5. Șterge elimină rândul imediat. Ștergerea ultimului rând afișează mesajul „Nu există încă proiecte.”

Stilizare

Propriul CSS al ecranului citește token-urile bibliotecii, astfel încât tabelul se potrivește cu componentele din jurul său și respectă orice suprascriere temei pentru proprietățile --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 din 40 menține regiunea notificărilor toast sub fundalul întunecat al dialogului, poziționat la 50. Pentru a schimba tema întregului ecran, suprascrieți token-urile conform secțiunii despre stilizare; componentele și tabelul se vor adapta.

Pașii următori

  • UIComponente: sistemul de design, token-urile și setul complet de componente.
  • UICompoziție: familii de componente compuse, transmiterea proprietăților către declanșator și modelul de stratificare din spatele dialogului.
  • Bază de date: moduri de stocare, controlul accesului, bs.db() și bs.mutate().
  • RPC: controlul accesului, metodele HTTP și apelurile între blocuri.
  • Blocuri full-stack: aceleași componente de bază într-o aplicație de tip listă de sarcini și într-un formular de abonare la newsletter.