Ugrás a tartalomhoz

Alkalmazásképernyő készítése a mellékelt UI segítségével

A legtöbb WordPress projektnek előbb-utóbb szüksége van egy olyan képernyőre, amely inkább alkalmazás, mint oldal: rekordlista, űrlapot megnyitó gomb, visszajelzés a sikeres mentésről. Erre általában egy JavaScript keretrendszer, néhány REST vezérlő és egy komponenskönyvtár a válasz, amelyeket mind a sablon mellett kell karbantartani.

A Blockstudio már mindegyiket tartalmazza. A db.php blokk alapú tárolást, ellenőrzést és CRUD-végpontokat biztosít. A rpc.php egyéni szerverműveleteket ad hozzá. A mellékelt UI komponensek párbeszédablakot, űrlapmezőket, gombokat, jelvényeket és toast értesítést kínálnak. Az Interactivity API tároló kapcsolja össze ezeket. Ez az útmutató egy teljes képernyő elkészítését mutatja be egyetlen blokk könyvtárában:

  • Projekttáblázat, amely a szerveren renderelődik, és a kliensen szinkronban marad.
  • Új projekt párbeszédablak, amelynek űrlapja a séma alapján ellenőrzi az adatokat.
  • Archiválás és Visszaállítás gombok, amelyek egy RPC függvényt hívnak meg optimista frissítéssel és visszaállítással.
  • Törlés gombok, amelyek közvetlenül használják az adatok API elemét.
  • Toast értesítés sikeres létrehozás után, és egy másik, ha a módosítás mentése sikertelen.

Kezdés előtt

A mellékelt komponensek használata nem kötelező. Engedélyezze őket a blockstudio.json fájlban:

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

A képernyő egyetlen blokkban található:

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

1. lépés: Az adatmodell

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

Minden művelethez szükséges a edit_posts jogosultság, ezért a végpontok 401 választ adnak kijelentkezett kérésre, adatot pedig csak szerkesztők vagy magasabb jogosultságú felhasználók módosíthatnak. A SQLite tárolás a rekordokat a kóddal együtt a projects/db/default.sqlite helyezi el.

A status required, nem pedig default értéket hordoz. A SQLite és a táblatárolás használatakor a séma létrehozáskor nem tölti ki a hiányzó értéket, ezért ha egy rekord a status nélkül jön létre, üres értékkel tárolódik. Ha a mező kötelező, és az űrlap is elküldi, minden sor érvényes marad.

Töltsön fel néhány rekordot a parancssorból:

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

A lista a legújabbal kezdve jelenik meg, a táblázat is ebben a sorrendben mutatja az elemeket.

2. lépés: Szerverművelet

A felhasználó szemszögéből az archiválás nem egyszerű mezőmódosítás, ezért külön nevesített függvényt kap:

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

A Db::update() a séma alapján ellenőrzi az adatot, így az enum elem továbbra is védi az értéket a db.php fájlban. Ha a függvényt ismeretlen állapottal hívják meg, ugyanazt a hibaformát adja vissza, mint az adatok API eleme:

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

A függvény a parancssorból is meghívható:

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",
    ...
}

3. lépés: A blokk definíciója

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

A supports.interactivity hatására az WordPress a sablon direktíváit a szerveren dolgozza fel, így a táblázat sorai még bármely JavaScript futása előtt megjelennek.

4. lépés: A sablon

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>

A sablon négy része külön figyelmet érdemel.

A szerverállapot adja a kezdeti megjelenítést. A wp_interactivity_state() átadja a rekordokat a szerveroldali direktívafeldolgozónak és a kliensoldali tárolónak is. A data-wp-each sablon a szerveren valódi sorokra bővül: minden rekordhoz egy tr tartozik. A isArchived lezárás: a WordPress a szerveroldali feldolgozás során minden sorhoz kiértékeli, a wp_interactivity_get_context() pedig az adott sor környezetét adja vissza, így az archivált sorok már hidratálás előtt a megfelelő jelvényt és gombot jelenítik meg. A böngészőben ugyanezen nevű tároló gettere veszi át a szerepét. A hasProjects egyszerű érték ugyanezen okból: nélküle a szerver nem tudná eldönteni, elrejtse-e az üres állapotra figyelmeztető bekezdést.

A párbeszédablak és az űrlap rendszerkomponensek. A trigger_label továbbítódik a triggeren belüli bsui/button elemnek, a UI kompozíció leírása szerint. A bsui/form a block="acme/projects" segítségével a mezőket FormData formátumba szerializálja, majd elküldi az adott blokk létrehozási végpontjára. Minden bsui/field tartalmazza a hozzá tartozó bemeneti mező nevét, így a séma mezőnkénti hibái a megfelelő vezérlő alatt jelennek meg. Az üres űrlap elküldésekor a Name alatt „Legalább 2 karakter szükséges.”, az Owner email alatt „Érvényes e-mail-cím szükséges.”, az űrlap alján pedig „Az ellenőrzés sikertelen.” jelenik meg. Az elrejtett status mező az űrlap adataival együtt utazik, így az új projektek teljesítik a kötelező mező követelményét.

A táblázat jelöléseit Ön írja meg. A bsui/table azokhoz a sorokhoz való, amelyeket a sablonban határoztak meg: az oszlopfejlécek rendezése a meglévő tr elemek áthelyezésével történik, ami ütközne azzal, hogy a data-wp-each kezeli a sorokat. A 7.7-es Blockstudio előtti verzióiban az összetevői közvetlenül a table elembe is div elemet helyeztek a thead, tbody és tr alatt, amelyeket a böngészők kimozdítanak a táblázatból. Ha a sorok tárolóból származnak, a table elemet írja meg saját maga, a rendszerkomponenseket pedig tartsa a cellákon belül. A sor sablonjában lévő jelvények és gombok egyszerű bsui/badge és bsui/button címkék. Minden gomb egy span elemben található, amely a kattintási direktívát hordozza, így a gomb rendszerkomponens marad, a művelet viszont az Ön tárolójához tartozik.

A toast megjelenítőelem. A bsui/toast-provider udvarias élő régiót jelenít meg, a bsui/toast pedig állapotüzenetet bezárógombbal. A szolgáltató nem helyezi el magát a képernyőn, a bezárógomb pedig nem rejti el a jelölésből megjelenített toastot. Ezért a képernyő mindkettőről gondoskodik: a position: fixed elemet tartalmazó burkoló helyezi el a régiót, minden toast pedig egy div elemben található, amelynek hidden kötése és kattintáskezelője a képernyő tárolójához tartozik. A bezárógombra kattintás felfelé buborékol ehhez a div elemhez.

5. lépés: A tároló

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

Az űrlap eseményeinek kezelése. Sikeres mentéskor a bsui/form egy formsuccess eseményt küld ki, amely buborékol, megszakítható, és a létrehozott rekordot a event.detail elemben hordozza. Sikertelen mentéskor a hiba törzsével együtt a formerror esemény kerül kiküldésre. A figyelő a dokumentumon (data-wp-on-document--formsuccess) található, nem a képernyő gyökérelemén, mert a megnyitott párbeszédablak felugró eleme a document.body elembe kerül, így az eseményei már nem buborékolnak át a blokkon. A owner ellenőrzés kihagyja az oldal más űrlapjaiból érkező eseményeket.

A event.preventDefault() meghívásával az űrlap nem cseréli le mezőit a sikerüzenetre, de továbbra is alaphelyzetbe áll. A művelet ezután a lista elejére helyezi a rekordot, bezárja a párbeszédablakot az bsui/dialog tároló close műveletével, majd megjeleníti a toastot. A close bezárja a legfelső nyitott párbeszédablakot, és visszaadja a fókuszt a triggernek, így létrehozás után a billentyűzetfókusz az Új projekt gombra kerül.

Hibák utáni visszaállítás. A bs.mutate() azonnal alkalmazza az optimista módosítást, majd visszaállítja a korábbi értékeket, ha a fn által visszaadott promise elutasításra kerül. A bs.fn() és a bs.db() nem utasítja el a promise-t HTTP hibák esetén: az RPC függvény által visszaadott WP_Error, az ellenőrzés sikertelensége vagy a hiányzó rekord esetén is hibát tartalmazó törzzsel teljesül. A ok() segédfüggvény elutasítássá alakítja azt az eredményt, amelynek van code eleme, így a sor visszaáll, és megjelenik a hibaértesítő toast. Nélküle a sikertelen frissítés összeolvasztaná a hibatörzset a sorral, a sikertelen törlés pedig eltávolítaná a sort.

A blokk elnevezése. A Blockstudio a soron belüli szkripteket <script type="module"> formátumban írja ki, a modul-szkripteknek pedig nincs document.currentScript elemük, ezért a bs.fn() nem tudja felismerni, melyik blokk hívja. Adja meg harmadik argumentumként a blokk nevét, ahogy a tároló teszi a BLOCK segítségével.

6. lépés: Helyezze a képernyőt egy oldalra

A fájlalapú oldal a címkéjével helyezi el a blokkot:

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

Az elemző natív blokká alakítja a címkét:

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

Futtassa a wp bs pages sync parancsot az oldal létrehozásához. A postStatus: "private" elrejti a névtelen látogatók elől, akik úgyis csak a bejelentkezési üzenetet látnák.

A képernyő működése futás közben

Nyissa meg az oldalt szerkesztőként:

  1. A táblázat mindkét sorral együtt jelenik meg; az archivált soron Archivált jelvény és Visszaállítás gomb látható.
  2. Az Új projekt gomb megnyitja a párbeszédablakot. A felugró ablak és a háttér a document.body elembe kerül, a fókusz a Name mezőre ugrik, az Escape vagy a Mégse pedig bezárja.
  3. Az érvényes adatok elküldése egyetlen POST kérést küld a /wp-json/blockstudio/v1/db/acme-projects/default felé. A párbeszédablak bezárul, az új sor a lista elejére kerül, a sarokban pedig négy másodpercre megjelenik a „Projekt létrehozva.” üzenet.
  4. Az Archiválás azonnal átváltja a jelvényt, és a /wp-json/blockstudio/v1/fn/acme/projects/set_status segítségével elküldi a set_status kérést. Ha közben máshol törölték a rekordot, a függvény visszaadja a 404 hibát, a sor Aktív állapotúra vált vissza, és megjelenik „A módosítás mentése sikertelen.”
  5. A Törlés azonnal eltávolítja a sort. Az utolsó rekord törlésekor megjelenik a „Még nincsenek projektek.” üzenet.

Stílusozás

A képernyő saját CSS fájlja olvassa a könyvtár tokenjeit, így a táblázat illeszkedik a környező komponensekhez, és követi a --bs-ui-* tulajdonságok témabeállításait:

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

A 40 z-index-je a párbeszédablak háttere alatt tartja a toast régiót, amely a 50 szinten van. A teljes képernyő témájának módosításához írja felül a tokeneket a stílusozás részben leírtak szerint; a komponensek és a táblázat is követik a módosítást.

Következő lépések

  • UI komponensek: a dizájnrendszer, a tokenek és a teljes komponenskészlet.
  • UI kompozíció: összetett komponenscsaládok, trigger-továbbítás és a párbeszédablak rétegzési modellje.
  • Adatbázis: tárolási módok, hozzáférés-szabályozás, bs.db() és bs.mutate().
  • RPC: hozzáférés-szabályozás, HTTP metódusok és blokkok közötti hívások.
  • Teljes veremű blokkok: ugyanazok az építőelemek egy teendőalkalmazásban és egy hírlevél-feliratkozásnál.