Liigu sisu juurde

Rakenduse vaate ehitamine komplektis oleva UI abil

Enamik WordPress projekte vajab varem või hiljem vaadet, mis meenutab rohkem rakendust kui lehte: kirjete loendit, nuppu vormi avamiseks ja tagasisidet salvestamise õnnestumise kohta. Tavaliselt kasutatakse selleks JavaScript raamistikku, REST kontrollerite komplekti ja komponenditeeki, mida kõike hallatakse teema kõrval.

Blockstudio sisaldab juba kõiki neid osi. db.php pakub ploki salvestusruumi, valideerimist ja CRUD-lõpp-punkte. rpc.php lisab kohandatud serveritoimingud. Komplekti kuuluvad UI komponendid pakuvad dialoogi, vormivälju, nuppe, märke ja teavitusi. Interactivity API olekuhoidla ühendab need. Selles juhendis ehitatakse terve vaade ühes plokikaustas algusest lõpuni:

  • Projektide tabel, mis renderdatakse serveris ja hoitakse kliendis sünkroonis.
  • Uue projekti dialoog vormiga, mis valideeritakse skeemi alusel.
  • Nupud Arhiveeri ja Taasta, mis kutsuvad välja RPC funktsiooni koos optimistliku uuenduse ja tagasipööramisega.
  • Nupud Kustuta, mis kasutavad otse andmete API-i.
  • Teavitus pärast edukat loomist ja teine siis, kui muudatuse salvestamine ebaõnnestub.

Enne alustamist

Komplektis olevad komponendid tuleb eraldi sisse lülitada. Lubage need failis blockstudio.json:

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

Vaade asub ühes plokis:

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

1. samm: andmemudel

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

Iga toiming nõuab võimekust edit_posts, seega vastavad lõpp-punktid sisselogimata päringule veaga 401 ja andmeid saavad muuta ainult toimetajad või kõrgema rolliga kasutajad. SQLite salvestusruum hoiab kirjeid asukohas projects/db/default.sqlite, koodi kõrval.

status on required ega sisalda default. Kui kasutatakse SQLite-tabelisalvestust, ei täida skeem loomisel puuduvat väärtust automaatselt. Seega salvestatakse ilma status-ta loodud kirje tühja väärtusega. Kui väli on kohustuslik ja vorm saadab selle väärtuse, jäävad kõik read korrektseks.

Lisage käsurealt paar näidiskirjet:

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

Loend tagastatakse uusimast vanimani, nagu tabelis kuvatakse.

2. samm: serveritoiming

Arhiveerimine pole kasutaja jaoks lihtsalt välja muutmine, seega saab see nimega funktsiooni:

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() valideerib väärtuse skeemi alusel, seega kontrollib db.php olev enum seda endiselt. Tundmatu olekuga funktsiooni väljakutse tagastab sama kujuga vea nagu andmete API:

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

Funktsiooni saab käivitada ka käsurealt:

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

3. samm: ploki määratlus

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 paneb WordPress serveris töötlema malli direktiive, mistõttu renderdatakse tabeli read enne mis tahes JavaScript käivitamist.

4. samm: mall

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>

Selle malli nelja osa tasub lähemalt vaadata.

Serveri olek loob esmase vaate. wp_interactivity_state() edastab kirjed nii serveripoolsele direktiivide töötlejale kui ka kliendi andmesalvele. Mall data-wp-each laieneb serveris tegelikeks ridadeks, üks tr iga kirje kohta. isArchived on sulund: WordPress hindab seda serveris iga rea jaoks, kusjuures wp_interactivity_get_context() tagastab selle rea konteksti. Nii kuvatakse arhiveeritud ridadel õiged märk ja nupp juba enne hüdratsiooni. Brauseris võtab üle sama nimega andmesalve getter. hasProjects on samal põhjusel lihtväärtus: ilma selleta ei teaks server, kas tühja oleku lõiku peita.

Dialoog ja vorm kasutavad süsteemikomponente. trigger_label edastatakse päästikus olevale bsui/button-ile, nagu kirjeldatakse juhendis UI kompositsioon. bsui/form koos block="acme/projects"-ga serialiseerib väljad FormData abil ja saadab need selle ploki loomise lõpp-punkti. Iga bsui/field sisaldab oma sisendi nime, nii et skeemi väljapõhised vead kuvatakse õige juhtelemendi all. Tühja vormi esitamisel kuvatakse välja Nimi all „Peab olema vähemalt 2 tähemärki.”, välja Omaniku e-post all „Sisestage kehtiv e-posti aadress.” ja vormi allservas „Valideerimine ebaõnnestus.” Peidetud status-sisend saadetakse koos vormiandmetega, nii et uued projektid saavad kohustusliku välja väärtuse.

Tabel kasutab teie enda märgistust. bsui/table sobib mallis määratud ridade jaoks: päiselahtreid klõpsates sorditakse ridu olemasolevaid tr-elemente ümber paigutades, mis läheks vastuollu sellega, et data-wp-each haldab ridu. Enne Blockstudio 7.7 käitusid selle osad ka nii, et paigutasid div otse elementide table, thead, tbody ja tr sisse; brauserid tõstavad need tabelist välja. Andmesalvest tulevate ridade korral kirjutage table-element ise ja hoidke süsteemikomponendid lahtrite sees. Reamalli märgid ja nupud on tavalised bsui/badge– ja bsui/button-sildid. Iga nupp paikneb elemendis span, millel on klõpsudirektiiv. Nii jääb nupp süsteeminupuks, samal ajal kui toiming kuulub teie andmesalvele.

Teavitus on esituskomponent. bsui/toast-provider renderdab viisakusliku live-piirkonna ja bsui/toast renderdab sulgemisnupuga olekuteate. Pakkuja ei paiguta end ekraanile ning sulgemisnupp ei peida märgistusena renderdatud teadet. Seega teeb vaade mõlemat: ümbris koos position: fixed-ga paigutab piirkonna ja iga teavitus asub elemendis div, mille hidden sidumine ja klõpsukäsitleja kuuluvad vaate andmesalvele. Sulgemisnupu klõps liigub üles kuni selle div-ni.

5. samm: andmesalv

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

Vormile reageerimine. Eduka salvestamise korral väljastab bsui/form sündmuse formsuccess, mis levib ülespoole, mida saab tühistada ning mis sisaldab loodud kirjet atribuudis event.detail. Ebaõnnestunud salvestamine väljastab sündmuse formerror koos vea sisuga. Kuulaja asub dokumendil (data-wp-on-document--formsuccess), mitte vaate juurelemendil, sest avatud dialoogi hüpik teisaldatakse asukohta document.body ja selle sündmused ei levi seetõttu enam ploki kaudu. Kontroll owner jätab vahele sama lehe teiste vormide sündmused.

Funktsiooni event.preventDefault() kutsumine takistab vormil väljade asendamist eduteatega; vorm lähtestab end siiski. Seejärel lisab toiming kirje loendi algusesse, sulgeb dialoogi bsui/dialog andmesalve toiminguga close ja kuvab teavituse. close sulgeb ülemise avatud dialoogi ning viib fookuse tagasi selle päästikule, nii et pärast loomist on klaviatuurifookus jälle nupul Uus projekt.

Vigade korral tagasipööramine. bs.mutate() rakendab optimistliku muudatuse kohe ja taastab eelmised väärtused, kui fn tagastatud lubadus tagasi lükatakse. bs.fn() ja bs.db() ei lükka lubadust tagasi HTTP vigade korral: RPC funktsiooni tagastatud WP_Error, valideerimisviga või puuduv kirje lahendatakse veasisuga. Abifunktsioon ok() muudab tulemuse, milles on code, tagasilükatud lubaduseks. Nii taastatakse rea eelmine olek ja kuvatakse veateavitus. Ilma selleta liidetaks ebaõnnestunud uuenduse korral veasisu reale ja ebaõnnestunud kustutuse korral jääks rida eemaldatuks.

Ploki nimetamine. Blockstudio väljastab tekstisisesed skriptid nimega <script type="module"> ja mooduliskriptidel puudub document.currentScript, seega ei saa bs.fn() tuvastada, milline plokk seda kutsub. Edastage ploki nimi kolmanda argumendina, nagu andmesalv teeb argumendiga BLOCK.

6. samm: lisage vaade lehele

Failipõhisele lehele lisatakse plokk selle sildiga:

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

Parser teisendab sildi algupäraseks plokiks:

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

Käivitage wp bs pages sync lehe loomiseks. postStatus: "private" peidab selle anonüümsete külastajate eest, kes näeksid muidu ainult sisselogimisteadet.

Vaate käitumine käitusajal

Kui leht on avatud toimetajana:

  1. Tabelis kuvatakse mõlemad renderdatud read; arhiveeritud real on märk Arhiveeritud ja nupp Taasta.
  2. Nupul Uus projekt klõpsates avaneb dialoog. Hüpik ja taust liiguvad asukohta document.body, fookus läheb väljale Nimi ning Escape või Tühista sulgeb dialoogi.
  3. Kehtivate väärtuste esitamisel saadetakse üks POST asukohta /wp-json/blockstudio/v1/db/acme-projects/default. Dialoog sulgub, uus rida ilmub loendi algusesse ja nurgas kuvatakse neljaks sekundiks teade „Projekt on loodud.”
  4. Nupp Arhiveeri muudab märgi kohe ja saadab set_status käsu kaudu /wp-json/blockstudio/v1/fn/acme/projects/set_status. Kui kirje on vahepeal mujal kustutatud, tagastab funktsioon oma vea 404, rea olekuks saab jälle Aktiivne ja kuvatakse teade „Muudatust ei salvestatud.”
  5. Nupp Kustuta eemaldab rea kohe. Viimase rea kustutamisel kuvatakse teade „Projekte veel pole.”

Stiilimine

Vaate enda CSS kasutab teegi disainitokeneid, nii et tabel sobib ümbritsevate komponentidega ja järgib kõiki --bs-ui-*-atribuudi teemamuudatusi:

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 z-index hoiab teavituste ala dialoogi tausta all, mille kiht on 50. Kogu vaate teema muutmiseks kirjutage tokenid üle, nagu kirjeldatakse jaotises Stiilimine; nii komponendid kui ka tabel järgivad muudatust.

Järgmised sammud

  • UI komponendid: disainisüsteem, tokenid ja täielik komponentide komplekt.
  • UI kompositsioon: liitkomponentide perekonnad, päästiku atribuutide edastamine ja dialoogi kihtmudel.
  • Andmebaas: salvestusrežiimid, juurdepääsu haldus, bs.db() ja bs.mutate().
  • RPC: juurdepääsu haldus, HTTP meetodid ja plokkidevahelised väljakutsed.
  • Täispinu plokid: samad ehitusplokid ülesannete rakenduses ja uudiskirjaga liitumise vormis.