Gå til indhold

Byg en appskærm med det medfølgende UI

De fleste WordPress-projekter får før eller siden brug for en skærm, der minder mere om en applikation end en side: en liste over poster, en knap, der åbner en formular, og feedback, når en lagring lykkes. Den sædvanlige løsning er et JavaScript-framework, et sæt REST-controllere og et komponentbibliotek, som alle vedligeholdes sammen med temaet.

Blockstudio leverer allerede alle disse dele. db.php giver en blok til lagring, validering og CRUD-endpoints. rpc.php tilføjer brugerdefinerede serverhandlinger. De medfølgende UI-komponenter leverer dialogen, formularfelterne, knapperne, badges og toastbeskeden. Et Interactivity API--lager forbinder dem. Denne guide bygger en hel skærm fra start til slut i én blokmappe:

  • En projekttabel, der rendres på serveren og holdes synkroniseret på klienten.
  • En dialog med titlen Nyt projekt og en formular, der validerer mod skemaet.
  • Knapperne Arkivér og Gendan, som kalder en RPC-funktion med en optimistisk opdatering og tilbagerulning.
  • Slet-knapper, der bruger data-API direkte.
  • En toastbesked efter oprettelse og endnu en, når en ændring ikke gemmes.

Før du begynder

De medfølgende komponenter er valgfrie. Aktivér dem i blockstudio.json:

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

Skærmen ligger i én blok:

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

Trin 1: Datamodellen

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

Hver handling kræver rettigheden edit_posts, så endpoints svarer med 401 på en anmodning fra en udlogget bruger, og kun redaktører og brugere med højere adgang kan ændre data. SQLite-lagring gemmer posterne i projects/db/default.sqlite sammen med koden.

status er required i stedet for at have en default. Med SQLite og tabelbaseret lagring udfylder skemaet ikke en manglende værdi ved oprettelse, så en post, der oprettes uden status, gemmes med en tom værdi. Hvis feltet er påkrævet og sendes fra formularen, forbliver alle rækker gyldige.

Opret et par poster fra kommandolinjen:

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

Listen vises med de nyeste øverst, som i tabellen.

Trin 2: En serverhandling

Arkivering er ikke en almindelig feltredigering set fra brugerens side, så den får sin egen navngivne funktion:

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() validerer mod skemaet, så enum i db.php stadig kontrollerer værdien. Hvis funktionen kaldes med en ukendt status, returnerer den samme fejlformat som data-API:

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

Funktionen kan også kaldes fra kommandolinjen:

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

Trin 3: Blokdefinitionen

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 får WordPress til at behandle skabelonens direktiver på serveren, så tabelrækkerne rendres, før nogen JavaScript kører.

Trin 4: Skabelonen

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>

Fire dele af denne skabelon fortjener et nærmere kig.

Servert tilstand lægger grunden til første visning. wp_interactivity_state() giver posterne til både direktivprocessoren på serveren og klientlageret. Skabelonen data-wp-each udfoldes til rigtige rækker på serveren, én tr pr. post. isArchived er en closure: WordPress evaluerer den for hver række under serverbehandlingen, og wp_interactivity_get_context() returnerer rækkens kontekst, så arkiverede rækker viser det rigtige badge og den rigtige knap før hydrering. I browseren overtager lagerets getter med samme navn. hasProjects er en almindelig værdi af samme grund: uden den ved serveren ikke, om afsnittet med tom tilstand skal skjules.

Dialogen og formularen er systemkomponenter. trigger_label videresendes til bsui/button i udløseren, som beskrevet i UI-sammensætning. bsui/form med block="acme/projects" serialiserer formularens felter med FormData og sender dem til blokkens oprettelsesendpoint. Hver bsui/field indeholder navnet på sit inputfelt, så skemafejl for hvert felt vises under den rigtige kontrol. Hvis formularen indsendes tom, vises “Skal være på mindst 2 tegn.” under Navn og “Skal være en gyldig e-mailadresse.” under Ejerens e-mail samt “Validering mislykkedes.” nederst i formularen. Det skjulte status-input sendes med formulardataene, så nye projekter opfylder det påkrævede felt.

Tabellen er din egen markup. bsui/table passer til rækker, der skrives i skabelonen: overskriftscellerne sorterer ved at flytte de eksisterende tr-elementer rundt, hvilket ville kollidere med data-wp-each om ejerskabet over rækkerne. Før Blockstudio 7.7 placerede dens dele også et div direkte i table, thead, tbody og tr, som browserne flytter ud af tabellen. For rækker fra et lager skal du selv skrive elementet table og holde systemkomponenterne inde i cellerne. Badges og knapper i rækkeskabelonen er almindelige bsui/badge– og bsui/button-tags. Hver knap ligger i en span, der har klikdirektivet, så knappen forbliver systemknappen, mens handlingen tilhører dit lager.

Toastbeskeden er præsentation. bsui/toast-provider rendrer et høfligt liveområde, og bsui/toast rendrer en statusmeddelelse med en lukknap. Udbyderen placerer ikke sig selv på skærmen, og lukknappen skjuler ikke en toastbesked, der er rendret fra markup. Skærmen gør derfor begge dele: En wrapper med position: fixed placerer området, og hver toastbesked ligger i en div, hvis hidden-binding og klikhåndtering tilhører skærmens lager. Klik på lukknappen bobler op til denne div.

Trin 5: Lageret

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

Reaktion på formularen. Når lagringen lykkes, udsender bsui/form en formsuccess-hændelse, der bobler op, kan annulleres og indeholder den oprettede post i event.detail. Hvis lagringen mislykkes, udsendes formerror med fejlindholdet. Lytteren sidder på dokumentet (data-wp-on-document--formsuccess) og ikke på skærmens rodelement, fordi en åben dialogpopup flyttes til document.body, så dens hændelser ikke længere bobler gennem blokken. Kontrollen owner springer hændelser fra andre formularer på samme side over.

Kald af event.preventDefault() forhindrer formularen i at erstatte felterne med succesmeddelelsen; formularen nulstiller stadig sig selv. Handlingen føjer derefter posten først i listen, lukker dialogen med handlingen close fra lageret bsui/dialog og viser toastbeskeden. close lukker den øverste åbne dialog og flytter fokus tilbage til udløseren, så tastaturfokus efter oprettelsen er tilbage på Nyt projekt.

Tilbagerulning ved fejl. bs.mutate() anvender straks den optimistiske ændring og gendanner de forrige værdier, hvis løftet fra fn afvises. bs.fn() og bs.db() afvises ikke ved HTTP-fejl: En WP_Error fra funktionen RPC, en valideringsfejl eller en manglende post løses alle med fejlindholdet. Hjælpefunktionen ok() afviser et resultat med en code, så rækken går tilbage, og fejltoastbeskeden vises. Uden den ville en mislykket opdatering flette fejlindholdet ind i rækken, og en mislykket sletning ville lade rækken forblive slettet.

Navngivning af blokken. Blockstudio udskriver inline-scripts som <script type="module">, og modulscripts har ingen document.currentScript, så bs.fn() kan ikke registrere, hvilken blok der kalder. Angiv bloknavnet som tredje argument, sådan som lageret gør med BLOCK.

Trin 6: Placér skærmen på en side

En filbaseret side placerer blokken med sit tag:

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

Parseren omdanner tagget til en indbygget blok:

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

Kør wp bs pages sync for at oprette siden. postStatus: "private" holder den væk fra anonyme besøgende, som alligevel kun ville se loginmeddelelsen.

Sådan fungerer skærmen ved kørsel

Når siden er åbnet som redaktør:

  1. Tabellen vises med begge rækker rendret; den arkiverede række har badget Arkiveret og knappen Gendan.
  2. Nyt projekt åbner dialogen. Popup’en og baggrundslaget flyttes til document.body, fokus lander i feltet Navn, og Escape eller Annuller lukker dialogen igen.
  3. Når gyldige værdier indsendes, sendes én POST til /wp-json/blockstudio/v1/db/acme-projects/default. Dialogen lukkes, den nye række vises øverst, og "Projekt oprettet." vises i hjørnet i fire sekunder.
  4. Arkivér ændrer straks badget og sender set_status via /wp-json/blockstudio/v1/fn/acme/projects/set_status. Hvis posten er blevet slettet et andet sted imens, returnerer funktionen fejlen 404, rækken går tilbage til Aktiv, og "Ændringen blev ikke gemt." vises.
  5. Slet fjerner rækken med det samme. Når den sidste række slettes, vises "Der er ingen projekter endnu."

Styling

Skærmens eget CSS læser bibliotekets tokens, så tabellen passer til de omgivende komponenter og følger temaets eventuelle tilsidesættelser af egenskaberne --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;
}

40s z-index holder toastområdet under dialogens baggrundslag, som ligger ved 50. Hvis du vil ændre temaet for hele skærmen, kan du tilsidesætte tokens som beskrevet under styling; det følger både komponenterne og tabellen.

Næste trin

  • UI-komponenter: designsystemet, tokens og hele komponentsættet.
  • UI-sammensætning: sammensatte komponentfamilier, videresendelse fra udløsere og lagdelingsmodellen bag dialogen.
  • Database: lagringstilstande, adgangskontrol, bs.db() og bs.mutate().
  • RPC: adgangskontrol, HTTP-metoder og kald på tværs af blokke.
  • Full-Stack-blokke: de samme byggesten i en todo-app og en tilmelding til et nyhedsbrev.