Vai al contenuto

Creare la schermata di un’app con UI incluso

Prima o poi, la maggior parte dei progetti WordPress ha bisogno di una schermata più simile a un’applicazione che a una pagina: un elenco di record, un pulsante che apre un modulo e un messaggio quando il salvataggio riesce. Di solito si ricorre a un framework JavaScript, a una serie di controller REST e a una libreria di componenti, tutti mantenuti accanto al tema.

Blockstudio include già tutti questi elementi. db.php offre archiviazione per i blocchi, convalida ed endpoint CRUD. rpc.php aggiunge azioni server personalizzate. I componenti inclusi in UI forniscono la finestra di dialogo, i campi dei moduli, i pulsanti, i badge e le notifiche toast. Uno store Interactivity API li collega. Questa guida realizza una schermata completa in una singola cartella di blocco:

  • Una tabella di progetti, generata sul server e mantenuta sincronizzata sul client.
  • Una finestra di dialogo Nuovo progetto con un modulo convalidato in base allo schema.
  • Pulsanti Archivia e Ripristina che chiamano una funzione RPC con aggiornamento ottimistico e ripristino in caso di errore.
  • Pulsanti Elimina che usano direttamente i dati API.
  • Una notifica toast dopo la creazione riuscita e un’altra quando una modifica non viene salvata.

Prima di iniziare

I componenti inclusi sono facoltativi. Attivateli in blockstudio.json:

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

La schermata si trova in un unico blocco:

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

Passaggio 1: il modello dei dati

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

Ogni operazione richiede la capacità edit_posts, quindi gli endpoint rispondono con 401 alle richieste degli utenti senza sessione e solo gli editor e gli utenti con privilegi superiori possono modificare i dati. L’archiviazione SQLite conserva i record in projects/db/default.sqlite, accanto al codice.

status è required anziché avere un default. Con SQLite e l’archiviazione nelle tabelle, lo schema non inserisce un valore mancante in fase di creazione; pertanto, un record creato senza status viene salvato con un valore vuoto. Rendendo obbligatorio il campo e inviandolo dal modulo, tutte le righe restano valide.

Inserite alcuni record dal terminale:

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

L’elenco viene restituito dal più recente al meno recente, lo stesso ordine usato nella tabella.

Passaggio 2: un’azione server

Dal punto di vista dell’utente, archiviare non equivale a modificare un semplice campo, quindi si usa una funzione con un nome specifico:

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() convalida i dati in base allo schema, quindi enum in db.php continua a verificare il valore. Chiamando la funzione con uno stato sconosciuto si ottiene lo stesso formato di errore dei dati API:

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

La funzione è utilizzabile anche dal terminale:

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

Passaggio 3: la definizione del blocco

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 fa sì che WordPress elabori le direttive del template sul server, così le righe della tabella vengono generate prima dell’esecuzione di qualsiasi JavaScript.

Passaggio 4: il template

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>

Vale la pena esaminare più da vicino quattro parti di questo template.

Lo stato del server prepara il primo rendering. wp_interactivity_state() passa i record sia al processore delle direttive lato server sia allo store client. Il template data-wp-each genera righe effettive sul server, una tr per ogni record. isArchived è una closure: durante l’elaborazione sul server, WordPress la valuta per ogni riga e wp_interactivity_get_context() restituisce il contesto della riga; così le righe archiviate mostrano il badge e il pulsante corretti prima dell’hydration. Nel browser subentra il getter omonimo dello store. Anche hasProjects è un semplice valore per lo stesso motivo: senza di esso, il server non saprebbe se nascondere il paragrafo dello stato vuoto.

La finestra di dialogo e il modulo usano componenti di sistema. trigger_label viene inoltrato a bsui/button all’interno dell’elemento di attivazione, come descritto nella composizione UI. bsui/form con block="acme/projects" serializza i campi con FormData e li invia all’endpoint di creazione del blocco. Ogni bsui/field contiene il nome del proprio campo, così gli errori di convalida dello schema vengono associati al controllo corretto. Se inviate il modulo vuoto, sotto Nome compare «Devono essere presenti almeno 2 caratteri.» e sotto Email del responsabile «Inserite un indirizzo email valido.»; in fondo al modulo compare anche «Convalida non riuscita.». Il campo status nascosto viene inviato insieme ai dati del modulo, consentendo ai nuovi progetti di soddisfare il requisito del campo obbligatorio.

La tabella è markup scritto da voi. bsui/table è adatto alle righe definite nel template: le celle di intestazione le ordinano spostando gli elementi tr esistenti, cosa che entrerebbe in conflitto con data-wp-each per la gestione delle righe. Prima di Blockstudio 7.7, le sue parti inserivano anche un div direttamente dentro table, thead, tbody e tr, elementi che i browser spostano fuori dalla tabella. Per le righe provenienti da uno store, scrivete voi l’elemento table e mantenete i componenti di sistema all’interno delle celle. I badge e i pulsanti nel template della riga sono normali tag bsui/badge e bsui/button. Ogni pulsante si trova in un span che contiene la direttiva di clic, così il pulsante resta quello di sistema mentre l’azione appartiene al vostro store.

La notifica toast ha solo una funzione visiva. bsui/toast-provider genera un’area live con modalità cortese, mentre bsui/toast visualizza un messaggio di stato con un pulsante di chiusura. Il provider non posiziona l’area sullo schermo e il pulsante di chiusura non nasconde una notifica generata dal markup. Per questo la schermata fa entrambe le cose: un contenitore con position: fixed posiziona l’area e ogni notifica si trova in un div, il cui binding hidden e gestore di clic appartengono allo store della schermata. Il clic sul pulsante di chiusura risale fino a quel div.

Passaggio 5: lo store

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

Reagire al modulo. Dopo un salvataggio riuscito, bsui/form invia un evento formsuccess che risale la gerarchia, può essere annullato e contiene il record creato in event.detail. Se il salvataggio non riesce, viene inviato formerror con il corpo dell’errore. Il listener è collegato al documento (data-wp-on-document--formsuccess), anziché all’elemento principale della schermata, perché il popup di una finestra di dialogo aperta viene spostato in document.body e i suoi eventi non risalgono più attraverso il blocco. Il controllo owner ignora gli eventi generati da altri moduli nella stessa pagina.

Chiamando event.preventDefault() si evita che il modulo sostituisca i campi con un messaggio di conferma; il modulo continua comunque a reimpostarsi. L’azione aggiunge il record in testa all’elenco, chiude la finestra di dialogo con l’azione close dello store bsui/dialog e mostra la notifica toast. close chiude la finestra di dialogo aperta in cima e riporta il focus al relativo elemento di attivazione; dopo la creazione, il focus della tastiera torna quindi su Nuovo progetto.

Ripristino in caso di errori. bs.mutate() applica subito la modifica ottimistica e ripristina i valori precedenti se la promise di fn viene rifiutata. bs.fn() e bs.db() non vengono rifiutati in caso di errori HTTP: un WP_Error dalla funzione RPC, un errore di convalida o un record mancante restituiscono il corpo dell’errore. L’helper ok() trasforma in rifiuto un risultato che contiene code, quindi la riga viene ripristinata e compare la notifica toast di errore. Senza questo helper, l’aggiornamento non riuscito incorporerebbe il corpo dell’errore nella riga e l’eliminazione non riuscita la lascerebbe rimossa.

Assegnare un nome al blocco. Blockstudio stampa gli script inline come <script type="module"> e gli script dei moduli non hanno document.currentScript; perciò bs.fn() non può rilevare quale blocco sta effettuando la chiamata. Passate il nome del blocco come terzo argomento, come fa lo store con BLOCK.

Passaggio 6: inserire la schermata in una pagina

Una pagina basata su file inserisce il blocco tramite il relativo tag:

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

Il parser converte il tag in un blocco nativo:

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

Eseguite wp bs pages sync per creare la pagina. postStatus: "private" la nasconde ai visitatori anonimi, che altrimenti vedrebbero solo il messaggio di accesso.

Comportamento della schermata in esecuzione

Con la pagina aperta come editor:

  1. La tabella viene visualizzata con entrambe le righe già generate; quella archiviata mostra il badge Archiviato e il pulsante Ripristina.
  2. Nuovo progetto apre la finestra di dialogo. Il popup e lo sfondo si spostano in document.body, il focus passa al campo Nome ed Esc o Annulla chiudono la finestra.
  3. Inviando valori validi, viene inviata una richiesta POST a /wp-json/blockstudio/v1/db/acme-projects/default. La finestra di dialogo si chiude, la nuova riga compare in cima e nell’angolo viene visualizzato «Progetto creato.» per quattro secondi.
  4. Archivia aggiorna subito il badge e invia set_status tramite /wp-json/blockstudio/v1/fn/acme/projects/set_status. Se nel frattempo il record è stato eliminato altrove, la funzione restituisce l’errore 404, la riga torna allo stato Attivo e compare il messaggio «La modifica non è stata salvata.».
  5. Elimina rimuove subito la riga. Eliminando l’ultima, viene mostrato «Non ci sono ancora progetti.»

Stili

Il file CSS della schermata usa i token della libreria; così la tabella si abbina ai componenti circostanti e segue eventuali sostituzioni del tema per le proprietà --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;
}

Il z-index di 40 mantiene l’area delle notifiche toast sotto lo sfondo della finestra di dialogo, che si trova a 50. Per modificare il tema dell’intera schermata, sovrascrivete i token come descritto nella sezione stili; sia i componenti sia la tabella si adegueranno.

Passaggi successivi

  • UIComponenti: il sistema di design, i token e l’intera raccolta di componenti.
  • UIComposizione: famiglie di componenti composti, inoltro agli elementi di attivazione e modello dei livelli alla base delle finestre di dialogo.
  • Database: modalità di archiviazione, controllo degli accessi, bs.db() e bs.mutate().
  • RPC: controllo degli accessi, metodi HTTP e chiamate tra blocchi.
  • Blocchi full stack: gli stessi elementi costitutivi in un’app per le attività e in una registrazione alla newsletter.