Créer l’écran d’une application avec le UI intégré
La plupart des projets WordPress ont tôt ou tard besoin d’un écran qui ressemble davantage à une application qu’à une page : une liste d’enregistrements, un bouton qui ouvre un formulaire et un message lorsque l’enregistrement réussit. La solution habituelle consiste à utiliser un framework JavaScript, un ensemble de contrôleurs REST et une bibliothèque de composants, tous maintenus à côté du thème.
Blockstudio fournit déjà chacun de ces éléments. db.php fournit le stockage des blocs, la validation et les points de terminaison CRUD. rpc.php ajoute des actions serveur personnalisées. Les composants UI intégrés fournissent la boîte de dialogue, les champs de formulaire, les boutons, les badges et les notifications toast. Un store API les relie. Ce guide crée un écran complet, de bout en bout, dans un seul dossier de bloc :
- Un tableau de projets, rendu sur le serveur et synchronisé côté client.
- Une boîte de dialogue Nouveau projet avec un formulaire validé selon le schéma.
- Des boutons Archiver et Restaurer qui appellent une fonction RPC avec mise à jour optimiste et annulation.
- Des boutons Supprimer qui utilisent directement le API de données.
- Une notification toast après la création, et une autre lorsqu’une modification n’est pas enregistrée.
Avant de commencer
Les composants intégrés sont facultatifs. Activez-les dans blockstudio.json :
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
L’écran tient dans un seul bloc :
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
Étape 1 : le modèle de données
<?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,
],
],
];
Chaque opération nécessite la capacité edit_posts. Les points de terminaison répondent donc 401 aux requêtes des visiteurs déconnectés, et seuls les éditeurs et les rôles supérieurs peuvent modifier les données. Le stockage SQLite conserve les enregistrements dans projects/db/default.sqlite, à côté du code.
status est required plutôt que de transporter un default. Avec SQLite et le stockage en table, le schéma ne renseigne pas une valeur manquante lors de la création ; un enregistrement créé sans status est donc stocké avec une valeur vide. Rendre ce champ obligatoire et l’envoyer depuis le formulaire garantit la validité de chaque ligne.
Ajoutez quelques enregistrements depuis la ligne de commande :
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 ...
La liste revient du plus récent au plus ancien, comme dans le tableau.
Étape 2 : une action serveur
Du point de vue de l’utilisateur, l’archivage n’est pas une simple modification de champ ; il fait donc l’objet d’une fonction nommée :
<?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() valide selon le schéma ; le enum dans db.php continue donc de protéger la valeur. Appeler la fonction avec un statut inconnu renvoie la même structure d’erreur que le API de données :
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
La fonction peut aussi être appelée depuis la ligne de commande :
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
Étape 3 : la définition du bloc
{
"$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 demande à WordPress de traiter les directives du modèle sur le serveur ; les lignes du tableau sont ainsi rendues avant l’exécution de tout JavaScript.
Étape 4 : le modèle
<?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>
Quatre éléments de ce modèle méritent un examen plus attentif.
L’état du serveur prépare le premier affichage. wp_interactivity_state() transmet les enregistrements au processeur de directives côté serveur et au store client. Le modèle data-wp-each génère de vraies lignes sur le serveur, une tr par enregistrement. isArchived est une fermeture : WordPress l’évalue pour chaque ligne pendant le traitement serveur, et wp_interactivity_get_context() renvoie le contexte de cette ligne. Les lignes archivées affichent ainsi le bon badge et le bon bouton avant l’hydratation. Dans le navigateur, l’accesseur du store portant le même nom prend le relais. hasProjects est une valeur simple pour la même raison : sans elle, le serveur ne saurait pas s’il doit masquer le paragraphe indiquant que la liste est vide.
La boîte de dialogue et le formulaire sont des composants du système. trigger_label est transmis au bsui/button dans le déclencheur, comme décrit dans la composition UI. bsui/form avec block="acme/projects" sérialise ses champs avec FormData et les envoie au point de terminaison de création du bloc. Chaque bsui/field porte le nom de son champ ; les erreurs de validation du schéma apparaissent donc sous le bon contrôle. L’envoi du formulaire vide affiche « Must be at least 2 characters. » sous Nom, « Must be a valid email address. » sous E-mail du responsable et « Validation failed. » en bas du formulaire. Le champ status masqué est envoyé avec les données du formulaire, ce qui permet aux nouveaux projets de satisfaire le champ obligatoire.
Le tableau utilise votre propre balisage. bsui/table convient aux lignes définies dans le modèle : les cellules d’en-tête trient en déplaçant les éléments tr existants, ce qui entrerait en conflit avec la gestion des lignes par data-wp-each. Avant la version 7.7 de Blockstudio, ses éléments internes plaçaient aussi un div directement dans table, thead, tbody et tr ; les navigateurs le sortent alors du tableau. Pour les lignes issues d’un store, écrivez vous-même l’élément table et placez les composants du système dans les cellules. Les badges et les boutons du modèle de ligne sont des balises bsui/badge et bsui/button ordinaires. Chaque bouton se trouve dans un span qui porte la directive de clic : le bouton reste ainsi celui du système, tandis que l’action appartient à votre store.
La notification toast est purement visuelle. bsui/toast-provider affiche une région dynamique polie, et bsui/toast affiche un message d’état avec un bouton de fermeture. Le fournisseur ne positionne pas lui-même la région à l’écran, et le bouton de fermeture ne masque pas une notification rendue à partir du balisage. L’écran fait donc les deux : un conteneur avec position: fixed positionne la région, et chaque notification se trouve dans un div dont la liaison hidden et le gestionnaire de clic appartiennent au store de l’écran. Un clic sur le bouton de fermeture remonte jusqu’à ce div.
Étape 5 : le store
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');
}
},
},
});
Réagir au formulaire. En cas d’enregistrement réussi, bsui/form déclenche un événement formsuccess qui remonte, peut être annulé et transporte l’enregistrement créé dans event.detail. En cas d’échec, le formulaire déclenche formerror avec le corps de l’erreur. L’écouteur se trouve sur le document (data-wp-on-document--formsuccess) et non sur l’élément racine de l’écran, car la fenêtre contextuelle d’une boîte de dialogue ouverte est déplacée vers document.body ; ses événements ne remontent donc plus jusqu’au bloc. La vérification owner ignore les événements provenant d’autres formulaires de la même page.
Appeler event.preventDefault() empêche le formulaire de remplacer ses champs par le message de réussite ; il se réinitialise quand même. L’action ajoute ensuite l’enregistrement en tête de liste, ferme la boîte de dialogue avec l’action close du store bsui/dialog, puis affiche la notification toast. close ferme la boîte de dialogue ouverte au premier plan et rend le focus à son déclencheur ; après une création, le focus clavier revient donc sur Nouveau projet.
Annuler en cas d’erreur. bs.mutate() applique immédiatement la modification optimiste et restaure les valeurs précédentes lorsque la promesse de fn est rejetée. bs.fn() et bs.db() ne rejettent pas les erreurs HTTP : une réponse WP_Error de la fonction RPC, un échec de validation ou un enregistrement manquant renvoient tous le corps de l’erreur. L’assistant ok() transforme en rejet tout résultat contenant un code ; la ligne reprend donc son état précédent et la notification d’échec s’affiche. Sans cet assistant, une mise à jour échouée fusionnerait le corps de l’erreur avec la ligne, et une suppression échouée laisserait la ligne supprimée.
Nommer le bloc. Blockstudio affiche les scripts intégrés sous la forme <script type="module">, et les scripts de module n’ont pas de document.currentScript ; bs.fn() ne peut donc pas détecter le bloc appelant. Passez le nom du bloc en troisième argument, comme le fait le store avec BLOCK.
Étape 6 : placer l’écran sur une page
Une page définie par fichier place le bloc à l’aide de sa balise :
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
L’analyseur transforme la balise en bloc natif :
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Exécutez wp bs pages sync pour créer la page. postStatus: "private" la rend inaccessible aux visiteurs anonymes, qui ne verraient de toute façon que le message de connexion.
Fonctionnement de l’écran à l’exécution
Lorsque la page est ouverte en tant qu’éditeur :
- Le tableau apparaît avec ses deux lignes déjà rendues ; la ligne archivée affiche le badge Archivé et un bouton Restaurer.
- Nouveau projet ouvre la boîte de dialogue. La fenêtre contextuelle et l’arrière-plan passent dans
document.body, le focus est placé dans le champ Nom, et Échap ou Annuler ferme la boîte de dialogue. - L’envoi de valeurs valides transmet un seul
POSTà/wp-json/blockstudio/v1/db/acme-projects/default. La boîte de dialogue se ferme, la nouvelle ligne apparaît en tête de liste et « Project created. » s’affiche dans le coin pendant quatre secondes. - Archiver change immédiatement le badge et transmet
set_statusvia/wp-json/blockstudio/v1/fn/acme/projects/set_status. Si l’enregistrement a été supprimé entre-temps, la fonction renvoie son erreur404, la ligne repasse à Actif et « That change was not saved. » s’affiche. - Supprimer retire immédiatement la ligne. La suppression de la dernière ligne affiche « No projects yet. ».
Styles
Le CSS propre à l’écran utilise les jetons de la bibliothèque ; le tableau s’accorde ainsi aux composants voisins et suit toute surcharge de thème des propriétés --bs-ui-* :
.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;
}
Le z-index de 40 maintient la région des notifications toast sous l’arrière-plan de la boîte de dialogue, placé à 50. Pour modifier le thème de tout l’écran, remplacez les jetons comme indiqué dans la section styles ; les composants et le tableau suivront.
Étapes suivantes
- Composants UI : système de design, jetons et ensemble complet de composants.
- Composition UI : familles de composants composés, transmission au déclencheur et modèle de superposition de la boîte de dialogue.
- Base de données : modes de stockage, contrôle d’accès,
bs.db()etbs.mutate(). - RPC : contrôle d’accès, méthodes HTTP et appels entre blocs.
- Blocs full stack : les mêmes briques dans une application de tâches et une inscription à une newsletter.