Přejít k obsahu

Vytvoření obrazovky aplikace pomocí UI dodávaných v balíčku

Většina projektů WordPress dříve či později potřebuje obrazovku, která je spíš aplikací než stránkou: seznam záznamů, tlačítko otevírající formulář a potvrzení po úspěšném uložení. Obvyklým řešením bývá framework JavaScript, sada kontrolerů REST a knihovna komponent, které se všechny udržují vedle šablony.

Blockstudio už všechny tyto části obsahuje. db.php poskytuje blokové úložiště, validaci a koncové body CRUD. rpc.php přidává vlastní akce na serveru. Dodávané komponenty UI poskytují dialog, pole formuláře, tlačítka, odznaky a oznámení. Store Interactivity API je propojuje. Tento průvodce vytvoří obrazovku od začátku do konce v jediné složce bloku:

  • Tabulka projektů vykreslená na serveru a průběžně synchronizovaná v klientovi.
  • Dialog Nový projekt s formulářem, který ověřuje data podle schématu.
  • Tlačítka Archivovat a Obnovit, která volají funkci RPC s optimistickou aktualizací a vrácením změn při chybě.
  • Tlačítka Odstranit, která používají přímo datové API.
  • Oznámení po úspěšném vytvoření a další, když se změnu nepodaří uložit.

Než začnete

Dodávané komponenty jsou ve výchozím stavu vypnuté. Povolte je v blockstudio.json:

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

Obrazovka se nachází v jediném bloku:

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

Krok 1: Datový 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á operace vyžaduje oprávnění edit_posts, takže koncové body odpovídají na odhlášené požadavky stavem 401 a data mohou měnit pouze editoři a uživatelé s vyššími oprávněními. Úložiště SQLite uchovává záznamy v projects/db/default.sqlite vedle kódu.

status má typ required, místo aby neslo default. Při použití SQLite a tabulkového úložiště schéma při vytvoření nedoplní chybějící hodnotu, takže záznam vytvořený bez status se uloží s prázdnou hodnotou. Povinné pole a jeho odeslání z formuláře zajistí, že budou platné všechny řádky.

Přidejte několik úvodních záznamů z příkazového řádku:

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

Seznam se vrací seřazený od nejnovějšího, stejně jako tabulka.

Krok 2: Akce na serveru

Archivace není z pohledu uživatele pouhou změnou pole, proto pro ni vytvoříme pojmenovanou funkci:

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() ověřuje data podle schématu, takže enum v db.php stále hlídá hodnotu. Volání funkce s neznámým stavem vrátí stejný formát chyby jako datové API:

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

Funkci lze volat také z příkazového řádku:

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: Definice 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 zajistí, že WordPress zpracuje direktivy šablony na serveru, díky čemuž se řádky tabulky vykreslí ještě před spuštěním JavaScript.

Krok 4: Šablona

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>

Pozornost si zaslouží čtyři části této šablony.

Stav na serveru připraví první vykreslení. wp_interactivity_state() předá záznamy procesoru direktiv na serveru i úložišti klienta. Šablona data-wp-each se na serveru rozbalí do skutečných řádků, jednoho tr pro každý záznam. isArchived je uzávěr: WordPress jej při zpracování na serveru vyhodnotí pro každý řádek a wp_interactivity_get_context() vrátí kontext daného řádku, takže archivované řádky mají správný odznak a tlačítko ještě před hydratací. V prohlížeči převezme řízení getter stejného jména v úložišti. Ze stejného důvodu je hasProjects obyčejná hodnota: bez ní by server nevěděl, zda skrýt odstavec pro prázdný stav.

Dialog a formulář jsou systémové komponenty. trigger_label se předává do bsui/button uvnitř spouštěče, jak popisuje skládání komponent UI. bsui/form s block="acme/projects" serializuje pole pomocí FormData a odešle je na koncový bod pro vytváření tohoto bloku. Každé bsui/field nese název svého vstupního pole, takže chyby schématu pro jednotlivá pole se zobrazí u správného ovládacího prvku. Po odeslání prázdného formuláře se pod položkou Name zobrazí „Musí mít alespoň 2 znaky.“ a pod položkou Owner email „Zadejte platnou e-mailovou adresu.“; ve spodní části formuláře se navíc zobrazí „Ověření se nezdařilo.“. Skrytý vstup status se odešle spolu s daty formuláře, díky čemuž nové projekty splňují požadavek na povinné pole.

Tabulka používá vaše vlastní značky. bsui/table se hodí pro řádky vytvořené v šabloně: buňky záhlaví řadí řádky přesouváním již existujících prvků tr, což by kolidovalo s data-wp-each, který řádky vlastní. Před verzí Blockstudio 7.7 navíc její části vkládaly div přímo do table, thead, tbody a tr, odkud ho prohlížeče přesouvají mimo tabulku. U řádků načítaných z úložiště vytvořte prvek table sami a systémové komponenty ponechte uvnitř buněk. Odznaky a tlačítka v šabloně řádku jsou běžné značky bsui/badge a bsui/button. Každé tlačítko je uvnitř prvku span s direktivou kliknutí, takže tlačítko zůstává systémové a akce náleží vašemu úložišti.

Oznámení slouží k prezentaci. bsui/toast-provider vykreslí zdvořilou živou oblast a bsui/toast vykreslí stavovou zprávu s tlačítkem pro zavření. Poskytovatel se na obrazovce sám neumístí a jeho tlačítko pro zavření neskryje oznámení vykreslené ze značení. Obrazovka proto zajišťuje obojí: obal s position: fixed umístí oblast a každé oznámení je uvnitř div, jehož vazbu hidden i obsluhu kliknutí řídí úložiště obrazovky. Kliknutí na tlačítko pro zavření probublá až k div.

Krok 5: Úložiště

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

Reakce na formulář. Po úspěšném uložení bsui/form odešle událost formsuccess, která se šíří, lze ji zrušit a která nese vytvořený záznam v event.detail. Při neúspěšném uložení odešle formerror s tělem chyby. Posluchač je na dokumentu (data-wp-on-document--formsuccess), nikoli na kořenovém prvku obrazovky, protože vyskakovací okno otevřeného dialogu se přesouvá do document.body a jeho události už proto neprobublají přes blok. Kontrola owner přeskočí události z ostatních formulářů na stejné stránce.

Volání event.preventDefault() zabrání formuláři, aby nahradil svá pole zprávou o úspěchu; formulář se přesto resetuje. Akce pak přidá záznam na začátek, zavře dialog pomocí akce close úložiště bsui/dialog a zobrazí oznámení. close zavře nejvýše položený otevřený dialog a vrátí fokus na jeho spouštěč, takže se po vytvoření vrátí na Nový projekt.

Vrácení změn při chybách. bs.mutate() okamžitě provede optimistickou změnu a při zamítnutí příslibu z fn obnoví předchozí hodnoty. bs.fn() ani bs.db() při chybách HTTP příslib nezamítnou: RPC vrátí z WP_Error funkce, při neúspěšné validaci nebo chybějícím záznamu se vyřeší příslib s tělem chyby. Pomocná funkce ok() změní výsledek obsahující code na zamítnutý příslib, takže se řádek vrátí do původního stavu a zobrazí se oznámení o chybě. Bez ní by se tělo chyby sloučilo s řádkem při neúspěšné aktualizaci a při neúspěšném odstranění by řádek zůstal smazaný.

Pojmenování bloku. Blockstudio vypisuje vložené skripty jako <script type="module"> a modulové skripty nemají document.currentScript, takže bs.fn() nedokáže zjistit, který blok volá. Název bloku předejte jako třetí argument, jak to úložiště dělá pomocí BLOCK.

Krok 6: Umístění obrazovky na stránku

Stránka založená na souboru umístí blok pomocí 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 převede značku na nativní blok:

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

Stránku vytvoříte příkazem wp bs pages sync. postStatus: "private" zabrání přístupu anonymních návštěvníků, kteří by stejně viděli jen zprávu s výzvou k přihlášení.

Chování obrazovky za běhu

Otevřete stránku jako editor:

  1. Tabulka se zobrazí s oběma řádky; archivovaný řádek má odznak Archivováno a tlačítko Obnovit.
  2. Kliknutím na Nový projekt otevřete dialog. Vyskakovací okno a pozadí se přesunou do document.body, fokus se přesune do pole Name a klávesa Escape nebo tlačítko Zrušit dialog zavřou.
  3. Odesláním platných hodnot se odešle jedno POST do /wp-json/blockstudio/v1/db/acme-projects/default. Dialog se zavře, nový řádek se objeví nahoře a v rohu se na čtyři sekundy zobrazí „Projekt byl vytvořen.“.
  4. Tlačítko Archivovat okamžitě změní odznak a odešle set_status prostřednictvím /wp-json/blockstudio/v1/fn/acme/projects/set_status. Pokud byl záznam mezitím odstraněn jinde, funkce vrátí chybu 404, řádek se změní zpět na Aktivní a zobrazí se „Tuto změnu se nepodařilo uložit.“.
  5. Tlačítko Odstranit ihned odstraní řádek. Po odstranění posledního se zobrazí „Zatím žádné projekty.“

Styly

Vlastní CSS obrazovky využívá tokeny knihovny, takže tabulka ladí s okolními komponentami a řídí se případným přepsáním vlastností --bs-ui-* motivu:

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 v 40 udržuje oblast oznámení pod pozadím dialogu, které je na úrovni 50. Chcete-li změnit motiv celé obrazovky, přepište tokeny podle pokynů v části styly; komponenty i tabulka se tomu přizpůsobí.

Další kroky

  • Komponenty UI: návrhový systém, tokeny a kompletní sada komponent.
  • Skládání komponent UI: složené skupiny, předávání vlastností spouštěči a vrstvení dialogu.
  • Databáze: režimy ukládání, řízení přístupu, bs.db() a bs.mutate().
  • RPC: řízení přístupu, metody HTTP a volání mezi bloky.
  • Full-Stack bloky: stejné stavební prvky v aplikaci pro úkoly a při přihlašování k odběru newsletteru.