Crear una pantalla de aplicación con los UI incluidos
La mayoría de los proyectos WordPress tarde o temprano necesitan una pantalla que se parezca más a una aplicación que a una página: una lista de registros, un botón que abre un formulario y un aviso cuando se guarda algo. La solución habitual es un framework JavaScript, un conjunto de controladores REST y una biblioteca de componentes, todo ello junto al tema y bajo mantenimiento propio.
Blockstudio ya incluye todas esas piezas. db.php aporta almacenamiento en bloques, validación y endpoints CRUD. rpc.php añade acciones de servidor personalizadas. Los componentes UI incluidos proporcionan el diálogo, los campos del formulario, los botones, las insignias y las notificaciones emergentes. Un almacén de Interactivity API los conecta. Esta guía crea una pantalla de principio a fin en una sola carpeta de bloque:
- Una tabla de proyectos, renderizada en el servidor y sincronizada en el cliente.
- Un diálogo Nuevo proyecto con un formulario que valida los datos según el esquema.
- Botones Archivar y Restaurar que llaman a una función RPC con una actualización optimista y una reversión.
- Botones Eliminar que usan directamente la API de datos.
- Una notificación emergente tras crear un elemento correctamente y otra cuando no se guarda un cambio.
Antes de empezar
Los componentes incluidos son opcionales. Actívelos en blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
La pantalla se encuentra en un solo bloque:
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
Paso 1: El modelo de datos
<?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,
],
],
];
Cada operación requiere la capacidad edit_posts, por lo que los endpoints responden con 401 a las solicitudes de usuarios sin sesión iniciada y solo los editores y roles superiores pueden cambiar los datos. El almacenamiento SQLite guarda los registros en projects/db/default.sqlite, junto al código.
status es required, en lugar de incluir un default. Con SQLite y el almacenamiento en tablas, el esquema no completa un valor que falta al crear un registro, así que uno creado sin status se almacena vacío. Si el campo es obligatorio y se envía desde el formulario, todas las filas siguen siendo válidas.
Añada un par de registros desde la línea de comandos:
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 lista aparece con los elementos más recientes primero, que es el orden que usa la tabla.
Paso 2: Una acción de servidor
Desde el punto de vista del usuario, archivar no es una simple edición de campo, así que se define una función con nombre:
<?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() valida los datos según el esquema, por lo que enum en db.php sigue protegiendo el valor. Si se llama a la función con un estado desconocido, devuelve el mismo formato de error que la API de datos:
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
La función también se puede llamar desde la línea de comandos:
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
Paso 3: La definición del bloque
{
"$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 hace que WordPress procese las directivas de la plantilla en el servidor, lo que permite renderizar las filas de la tabla antes de que se ejecute cualquier JavaScript.
Paso 4: La plantilla
<?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 examinar con más detalle cuatro partes de esta plantilla.
El estado del servidor prepara la primera renderización. wp_interactivity_state() pasa los registros tanto al procesador de directivas del servidor como al almacén del cliente. La plantilla data-wp-each se expande en filas reales en el servidor, una por cada tr. isArchived es un cierre: WordPress lo evalúa para cada fila durante el procesamiento del servidor y wp_interactivity_get_context() devuelve el contexto de esa fila, de modo que las filas archivadas muestran la insignia y el botón correctos antes de la hidratación. En el navegador, el getter del mismo nombre en el almacén toma el relevo. hasProjects es un valor simple por el mismo motivo: sin él, el servidor no sabría si ocultar el párrafo que indica que no hay elementos.
El diálogo y el formulario son componentes del sistema. trigger_label se reenvía al bsui/button dentro del activador, como se describe en ComposiciónUI. bsui/form con block="acme/projects" serializa los campos con FormData y los envía al endpoint de creación de ese bloque. Cada bsui/field lleva el nombre de su campo de entrada, por lo que los errores de esquema de cada campo aparecen junto al control correcto. Al enviar el formulario vacío, debajo de Nombre aparece «Debe tener al menos 2 caracteres» y debajo de Correo del propietario aparece «Debe ser una dirección de correo electrónico válida». Al final del formulario también aparece «La validación ha fallado». El campo de entrada oculto status se envía junto con los datos del formulario, lo que permite que los proyectos nuevos cumplan el requisito del campo obligatorio.
La tabla usa su propio marcado. bsui/table es adecuado para filas escritas en la plantilla: sus celdas de encabezado ordenan moviendo los elementos tr existentes, lo que entraría en conflicto con data-wp-each por el control de las filas. Antes de la versión 7.7 de Blockstudio, sus partes también colocaban un div directamente dentro de table, thead, tbody y tr, y los navegadores los sacaban de la tabla. Para las filas procedentes de un almacén, escriba usted mismo el elemento table y mantenga los componentes del sistema dentro de las celdas. Las insignias y los botones de la plantilla de fila son etiquetas bsui/badge y bsui/button corrientes. Cada botón está dentro de un span que lleva la directiva de clic, por lo que el botón sigue siendo el del sistema y la acción pertenece al almacén.
La notificación emergente solo presenta el contenido. bsui/toast-provider renderiza una región activa cortés y bsui/toast muestra un mensaje de estado con un botón para descartarlo. El proveedor no posiciona la región en la pantalla y el botón para descartarlo no oculta una notificación renderizada desde el marcado. Por eso, la pantalla hace ambas cosas: un contenedor con position: fixed posiciona la región, y cada notificación está dentro de un div cuyo enlace hidden y controlador de clic pertenecen al almacén de la pantalla. Al hacer clic en el botón para descartarla, el evento asciende hasta ese div.
Paso 5: El almacén
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');
}
},
},
});
Cómo responde al formulario. Si se guarda correctamente, bsui/form envía un evento formsuccess que asciende por la jerarquía, se puede cancelar y lleva el registro creado en event.detail. Si el guardado falla, envía formerror con el cuerpo del error. El listener está en el documento (data-wp-on-document--formsuccess), en lugar de la raíz de la pantalla, porque la ventana emergente de un diálogo abierto se mueve a document.body y sus eventos dejan de ascender por el bloque. La comprobación owner omite los eventos de otros formularios de la misma página.
Llamar a event.preventDefault() impide que el formulario sustituya sus campos por el mensaje de confirmación; aun así, el formulario se restablece. Luego, la acción añade el registro al principio de la lista, cierra el diálogo con la acción close del almacén bsui/dialog y muestra la notificación. close cierra el diálogo abierto que está en primer plano y devuelve el foco a su activador, por lo que, al terminar la creación, el foco del teclado vuelve a Nuevo proyecto.
Revertir los cambios si hay errores. bs.mutate() aplica el cambio optimista de inmediato y restablece los valores anteriores si se rechaza la promesa de fn. bs.fn() y bs.db() no rechazan las solicitudes ante errores HTTP: un WP_Error de la función RPC, un error de validación o un registro que no existe se resuelven con el cuerpo del error. El asistente ok() convierte en rechazo un resultado que incluye code, por lo que la fila vuelve a su estado anterior y aparece la notificación de error. Sin este asistente, una actualización fallida combinaría el cuerpo del error con la fila, y una eliminación fallida dejaría la fila eliminada.
Asignar un nombre al bloque. Blockstudio imprime los scripts en línea como <script type="module">, y los scripts de módulo no tienen document.currentScript, por lo que bs.fn() no puede detectar qué bloque realiza la llamada. Pase el nombre del bloque como tercer argumento, tal como hace el almacén con BLOCK.
Paso 6: Colocar la pantalla en una página
Una página basada en archivos coloca el bloque con su etiqueta:
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
El analizador convierte la etiqueta en un bloque nativo:
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Ejecute wp bs pages sync para crear la página. postStatus: "private" la oculta a los visitantes anónimos, que de todos modos solo verían el mensaje de inicio de sesión.
Funcionamiento de la pantalla
Con la página abierta como editor:
- La tabla aparece con las dos filas renderizadas; la fila archivada muestra la insignia Archivado y un botón Restaurar.
- Nuevo proyecto abre el diálogo. La ventana emergente y el fondo se mueven a
document.body, el foco pasa al campo Nombre y la tecla Escape o Cancelar cierra el diálogo. - Al enviar valores válidos, se envía un
POSTa/wp-json/blockstudio/v1/db/acme-projects/default. El diálogo se cierra, la nueva fila aparece al principio y «Proyecto creado» se muestra en la esquina durante cuatro segundos. - Archivar cambia la insignia de inmediato y envía
set_statusmediante/wp-json/blockstudio/v1/fn/acme/projects/set_status. Si el registro se eliminó entretanto, la función devuelve su error404, la fila vuelve a Activo y aparece «No se guardó ese cambio». - Eliminar quita la fila de inmediato. Al eliminar la última, aparece «Todavía no hay proyectos».
Estilos
El CSS propio de la pantalla lee los tokens de la biblioteca, por lo que la tabla combina con los componentes que la rodean y sigue cualquier cambio de tema en las propiedades --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;
}
El z-index de 40 mantiene la región de notificaciones debajo del fondo del diálogo, que está en 50. Para cambiar el tema de toda la pantalla, sobrescriba los tokens como se explica en estilos; tanto los componentes como la tabla seguirán el cambio.
Pasos siguientes
- Componentes de UI: el sistema de diseño, los tokens y el conjunto completo de componentes.
- Composición de UI: familias compuestas, reenvío al activador y el modelo de capas del diálogo.
- Base de datos: modos de almacenamiento, control de acceso,
bs.db()ybs.mutate(). - RPC: control de acceso, métodos HTTP y llamadas entre bloques.
- Bloques full stack: los mismos componentes básicos en una aplicación de tareas y un formulario de suscripción a un boletín.