Sovellusnäkymän rakentaminen mukana toimitetulla UI:llä
Useimmat WordPress-projektit tarvitsevat ennen pitkää näkymän, joka on enemmän sovellus kuin sivu: tietueluettelo, painike, joka avaa lomakkeen, sekä ilmoitus onnistuneesta tallennuksesta. Tavallinen ratkaisu on JavaScript-kehys, joukko REST-ohjaimia ja komponenttikirjasto, joita kaikkia ylläpidetään teeman rinnalla.
Blockstudio sisältää jo nämä kaikki osat. db.php tarjoaa lohkotallennuksen, validoinnin ja CRUD-päätepisteet. rpc.php lisää mukautetut palvelintoiminnot. Mukana toimitettavat UI-komponentit tarjoavat valintaikkunan, lomakekentät, painikkeet, merkit ja ilmoitukset. Interactivity API-tila yhdistää ne. Tässä oppaassa rakennetaan kokonainen näkymä yhteen lohkokansioon:
- Projektitaulukko, joka renderöidään palvelimella ja pidetään synkronoituna asiakaspuolella.
- Uusi projekti -valintaikkuna, jonka lomake validoidaan skeemaa vasten.
- Arkistoi– ja Palauta-painikkeet, jotka kutsuvat RPC-funktiota optimistisella päivityksellä ja palautuksella.
- Poista-painikkeet, jotka käyttävät tietojen API-toimintoa suoraan.
- Ilmoitus onnistuneen luonnin jälkeen sekä toinen silloin, kun muutosta ei tallenneta.
Ennen aloittamista
Mukana toimitettavat komponentit ovat valinnaisia. Ota ne käyttöön kohdassa blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
Näkymä sijaitsee yhdessä lohkossa:
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
Vaihe 1: Tietomalli
<?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,
],
],
];
Jokainen toiminto vaatii valmiuden edit_posts, joten päätepisteet vastaavat kirjautumattomaan pyyntöön arvolla 401 ja vain toimittajat tai sitä korkeammalla tasolla olevat voivat muuttaa tietoja. SQLite-tallennus pitää tietueet kohteessa projects/db/default.sqlite koodin vieressä.
status on tyypiltään required eikä sisällä arvoa default. Kun käytössä ovat SQLite ja taulukkotallennus, skeema ei täydennä puuttuvaa arvoa luotaessa. Ilman arvoa status luotu tietue tallennetaan siksi tyhjänä. Kun kenttä määritetään pakolliseksi ja arvo lähetetään lomakkeesta, jokainen rivi pysyy kelvollisena.
Lisää pari tietuetta komentoriviltä:
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
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 ...
Luettelo palautetaan uusimmat ensin, samassa järjestyksessä kuin taulukko näyttää ne.
Vaihe 2: Palvelintoiminto
Arkistointi ei ole käyttäjän näkökulmasta tavallinen kentän muokkaus, joten sille määritetään nimetty toiminto:
<?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() validoi syötteen skeemaa vasten, joten kohteen enum db.php suojaa yhä arvoa. Funktiolle annettu tuntematon tila palauttaa saman virhemuodon kuin tietojen API:
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
Funktiota voi kutsua myös komentoriviltä:
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
Vaihe 3: Lohkon määrittely
{
"$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 saa arvon WordPress käsittelemään mallipohjan ohjeet palvelimella, jolloin taulukon rivit renderöidään ennen minkään JavaScript-toiminnon suorittamista.
Vaihe 4: Mallipohja
<?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>
Tämän mallipohjan neljää osaa kannattaa tarkastella lähemmin.
Palvelintila alustaa ensimmäisen näkymän. wp_interactivity_state() välittää tietueet sekä palvelinpuolen ohjeiden käsittelijälle että asiakaspuolen tilalle. data-wp-each-mallipohja laajenee palvelimella varsinaisiksi riveiksi, yksi tr kutakin tietuetta kohti. isArchived on sulkeuma: WordPress laskee sen jokaiselle riville palvelinkäsittelyn aikana, ja wp_interactivity_get_context() palauttaa kyseisen rivin kontekstin. Näin arkistoiduilla riveillä näkyvät oikea merkki ja painike jo ennen aktivointia. Selaimessa saman niminen tilan getter ottaa tehtävän hoitaakseen. hasProjects on tavallinen arvo samasta syystä: ilman sitä palvelin ei tietäisi, pitäisikö tyhjän tilan kappale piilottaa.
Valintaikkuna ja lomake ovat järjestelmäkomponentteja. trigger_label välitetään käynnistimen sisällä olevalle bsui/button-komponentille, kuten kohdassa UI Koostaminen kuvataan. bsui/form yhdessä arvon block="acme/projects" kanssa sarjallistaa kentät arvolla FormData ja lähettää ne lohkon luontipäätepisteeseen. Kunkin bsui/field-elementin mukana kulkee syötteensä nimi, joten skeeman kenttäkohtaiset virheet kohdistuvat oikean syötteen alle. Tyhjän lomakkeen lähettäminen näyttää Nimi-kentän alla tekstin “Must be at least 2 characters.” ja Omistajan sähköposti -kentän alla tekstin “Must be a valid email address.” sekä lomakkeen alareunassa tekstin “Validation failed.”. Piilotettu status-syöte kulkee lomakkeen tietojen mukana, jolloin uudet projektit saavat pakollisen kentän arvon.
Taulukon merkkaus on sinun kirjoittamaasi. bsui/table sopii mallipohjassa määritetyille riveille: sen otsikkosolut lajittelevat siirtämällä olemassa olevia tr-elementtejä. Tämä olisi ristiriidassa sen kanssa, että data-wp-each hallitsee rivejä. Ennen versiota Blockstudio 7.7 sen osat sijoittivat myös div-elementin suoraan elementtien table, thead, tbody ja tr sisään, mistä selaimet siirtävät sen pois taulukosta. Jos rivit tulevat tilasta, kirjoita table-elementti itse ja pidä järjestelmäkomponentit solujen sisällä. Rivimallipohjan merkit ja painikkeet ovat tavallisia bsui/badge– ja bsui/button-tageja. Kukin painike on elementissä span, johon napsautusohje kuuluu. Näin painike pysyy järjestelmän painikkeena, kun taas toiminto kuuluu tilallesi.
Ilmoitus on esityskomponentti. bsui/toast-provider renderöi kohteliaan live-alueen, ja bsui/toast renderöi tilaviestin, jossa on sulkemispainike. Tarjoaja ei sijoita itseään näytölle, eikä sulkemispainike piilota merkinnästä renderöityä ilmoitusta. Siksi näkymä tekee molemmat: position: fixed-arvon sisältävä kääre sijoittaa alueen, ja kukin ilmoitus on elementissä div, jonka hidden-sidonta ja napsautuskäsittelijä kuuluvat näkymän tilalle. Sulkemispainikkeen napsautus kuplii kyseiseen kohteeseen div.
Vaihe 5: Tila
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');
}
},
},
});
Lomakkeen tapahtumien käsittely. Onnistuneen tallennuksen jälkeen bsui/form lähettää tapahtuman formsuccess, joka kuplii, voidaan peruuttaa ja joka sisältää luodun tietueen kohdassa event.detail. Epäonnistunut tallennus lähettää tapahtuman formerror, jonka mukana on virheen sisältö. Kuuntelija on dokumentissa (data-wp-on-document--formsuccess), ei näkymän juurielementissä, koska avoimen valintaikkunan ponnahdusikkuna siirretään kohteeseen document.body, jolloin sen tapahtumat eivät enää kupli lohkon läpi. owner-tarkistus ohittaa saman sivun muiden lomakkeiden tapahtumat.
event.preventDefault()-kutsun ansiosta lomake ei vaihda kenttiään onnistumisviestiin, mutta nollaa silti itsensä. Toiminto lisää sitten tietueen luettelon alkuun, sulkee valintaikkunan bsui/dialog-tilan toiminnolla close ja näyttää ilmoituksen. close sulkee ylimmän avoimen valintaikkunan ja palauttaa kohdistuksen sen käynnistimeen, joten luonnin jälkeen näppäimistön kohdistus palaa painikkeeseen Uusi projekti.
Virheiden jälkeinen palautus. bs.mutate() ottaa optimistisen muutoksen käyttöön heti ja palauttaa edelliset arvot, jos kohteen fn promise hylätään. bs.fn() ja bs.db() eivät hylkää promisea kohteen HTTP virhetilanteissa: RPC-funktion palauttama WP_Error, validointivirhe tai puuttuva tietue ratkaistaan virheen sisältävänä vastauksena. ok()-apu muuttaa vastauksen, jossa on code, hylkäykseksi, jolloin rivi palautuu ennalleen ja virheilmoitus näytetään. Ilman sitä epäonnistuneen päivityksen virheen sisältävä vastaus yhdistyisi riviin ja epäonnistuneen poiston jälkeen rivi jäisi poistetuksi.
Lohkon nimeäminen. Blockstudio tulostaa sisäiset skriptit tunnisteella <script type="module">, eikä moduuliskripteillä ole tunnistetta document.currentScript. Siksi bs.fn() ei voi tunnistaa kutsuvaa lohkoa. Anna lohkon nimi kolmantena argumenttina, kuten tila tekee arvolla BLOCK.
Vaihe 6: Lisää näkymä sivulle
Tiedostopohjainen sivu lisää lohkon tunnisteellaan:
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
Jäsennin muuntaa tunnisteen natiiviksi lohkoksi:
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Luo sivu komennolla wp bs pages sync. postStatus: "private" pitää sen poissa kirjautumattomien kävijöiden näkyviltä, sillä he näkisivät joka tapauksessa vain kirjautumisviestin.
Näkymän toiminta ajon aikana
Kun sivu on avoinna toimittajana:
- Taulukko latautuu molemmat rivit renderöityinä. Arkistoidulla rivillä näkyvät Arkistoitu-merkki ja Palauta-painike.
- Uusi projekti avaa valintaikkunan. Ponnahdusikkuna ja tausta siirtyvät kohteeseen
document.body, kohdistus asettuu Nimi-kenttään, ja Esc-näppäin tai Peruuta sulkee ikkunan. - Kelvollisten arvojen lähettäminen lähettää yhden
POST-tapahtuman kohteeseen/wp-json/blockstudio/v1/db/acme-projects/default. Valintaikkuna sulkeutuu, uusi rivi ilmestyy luettelon alkuun ja kulmassa näkyy neljän sekunnin ajan ilmoitus "Project created.". - Arkistoi vaihtaa merkin heti ja lähettää pyynnön kohteen
set_statuskautta kohteeseen/wp-json/blockstudio/v1/fn/acme/projects/set_status. Jos tietue poistettiin muualla sillä välin, funktio palauttaa virheen404. Rivi palaa tilaan Aktiivinen, ja näkyviin tulee ilmoitus "That change was not saved.". - Poista poistaa rivin heti. Viimeisen rivin poisto tuo näkyviin tekstin "No projects yet.".
Tyylit
Näkymän oma CSS käyttää kirjaston tunnisteita, joten taulukko sopii yhteen ympäröivien komponenttien kanssa ja noudattaa kaikkia --bs-ui-*-ominaisuuksien teemamuutoksia:
.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;
}
Kohteen 40 z-index sijoittaa ilmoitusalueen valintaikkunan taustan alle, jonka taso on 50. Jos haluat muuttaa koko näkymän teemaa, korvaa tunnisteet kohdassa tyylit kuvatuilla tavoilla. Komponentit ja taulukko noudattavat muutoksia.
Seuraavat vaiheet
- UI-komponentit: suunnittelujärjestelmä, tunnisteet ja koko komponenttijoukko.
- UI-koostaminen: yhdistelmäperheet, käynnistimien välitys ja valintaikkunan kerrosmalli.
- Tietokanta: tallennustilat, käyttöoikeuksien hallinta,
bs.db()jabs.mutate(). - RPC: käyttöoikeuksien hallinta, HTTP-menetelmät ja lohkojen väliset kutsut.
- Täyden pinon lohkot: samat rakennuspalikat tehtäväsovelluksessa ja uutiskirjeen tilauslomakkeessa.