Construir páginas con blocks
Un constructor de páginas es una lista de secciones donde cada sección elige su forma: una portada con
título e imagen, un texto, una cita, una galería. Eso es un campo blocks.
Esta guía recorre el caso entero con el código de la demo del repositorio (apps/demo): declararlo, editarlo en
el panel, pintarlo en Astro y, si ya guardabas las secciones en un json, pasarlas a blocks.
Cuándo usarlo
Sección titulada «Cuándo usarlo»- Filas que tienen todas la misma forma (los enlaces de un menú, unas preguntas frecuentes): un
array. - Filas de formas distintas que quien edita elige y ordena:
blocks, que es lo de esta guía. - Un texto con formato dentro de una sola sección: un
richText, que también cabe como subcampo de un bloque. - Datos con una forma que no quieres tipar ni consultar:
json.
Declarar la colección
Sección titulada «Declarar la colección»La colección pages de la demo tiene un título, un slug y las sections:
const pages = defineCollection({ slug: 'pages', fields: [ { name: 'title', type: 'text', required: true }, { name: 'slug', type: 'text', required: true, unique: true, index: true }, { name: 'sections', type: 'blocks', labels: { singular: 'Sección', plural: 'Secciones' }, blocks: [ { slug: 'hero', label: 'Portada', fields: [ { name: 'title', type: 'text', required: true }, { name: 'align', type: 'radio', options: ['left', 'center'], defaultValue: 'left' }, { name: 'image', type: 'upload', to: 'ssd' }, ], }, { slug: 'rich-text', label: 'Texto', fields: [{ name: 'content', type: 'richText' }] }, { slug: 'quote', label: 'Cita', fields: [ { name: 'text', type: 'textarea', required: true }, { name: 'author', type: 'text' }, ], }, { slug: 'gallery', label: 'Galería', fields: [ { name: 'image1', type: 'upload', to: 'ssd' }, { name: 'image2', type: 'upload', to: 'ssd' }, { name: 'image3', type: 'upload', to: 'ssd' }, ], }, ], }, ],})Tres cosas que salen de ahí:
- El
slugde un bloque va en minúsculas, con dígitos y guiones (rich-text, norichText): es elblockTypede sus filas y el final del nombre de su tabla, ydefineConfiglanzaINVALID_BLOCK_SLUGcon cualquier otro. En la tabla, el guion es un guion bajo:rich-textdapages_sections_rich_text. - Cada tipo de bloque es una tabla hija, y la tabla del documento no cambia. Con
cms db:migratesalenpages_sections_hero,pages_sections_rich_text,pages_sections_quoteypages_sections_gallery, todas nuevas: es una migración que solo añade. Ver Tablas hijas. - Los subcampos son los de una fila: los trece tipos de un valor y una columna —aquí
text,textarea,radio,richTextyupload—. Ungroup, unpointo otra lista dentro de una fila se rechazan al validar el config.
pnpm cms db:migrate # escribe migrations/<fecha>_<nombre>/migration.sql, léelopnpm cms db:apply # lo aplica a la D1 localcms db:generate escribe además el tipo de cada fila en .cms/types.d.ts, como una unión que se estrecha por
blockType:
export interface Page { id: string createdAt: Date updatedAt: Date title: string slug: string sections: ( | { id: string; blockType: 'hero'; title: string; align: 'left' | 'center' | null; image: string | Medio | null } | { id: string; blockType: 'rich-text'; content: unknown | null } | { id: string; blockType: 'quote'; text: string; author: string | null } | { id: string; blockType: 'gallery'; image1: string | Medio | null; image2: string | Medio | null; image3: string | Medio | null } )[]}Editarlo en el panel
Sección titulada «Editarlo en el panel»En /admin/collections/pages el campo es una lista de filas plegables. «Añadir sección» abre un menú con el
catálogo (cada bloque con su label y su admin.description), y elegir uno añade una fila de ese tipo, con
solo sus subcampos. Cada fila se sube, se baja, se duplica y se elimina desde su menú, con Alt+↑ y Alt+↓, o
arrastrando su asa. El tipo de una fila no se cambia: se elimina y se añade otra. El detalle, con el teclado, los
errores por fila y lo que pasa con un tipo que el config ya no declara, está en
Editar una lista en el panel.
Pintarlo en Astro
Sección titulada «Pintarlo en Astro»Una página de Astro lee el documento con la API local y recorre sections con un switch sobre blockType.
Esta es, abreviada, la src/pages/[slug].astro de la demo:
---import RichText from '@kevolution-co/cms/rich-text/RichText.astro'import Layout from '@/layouts/Layout.astro'
export const prerender = false
const { slug } = Astro.paramsconst { pages, ssd } = Astro.locals.cms.collections
const page = slug === undefined ? null : await pages.findOne({ where: { slug: { equals: slug } }, depth: 1, overrideAccess: true })
if (page === null) return new Response('No existe ninguna página con ese slug.', { status: 404 })---
<Layout title={page.title}> { page.sections.map((block) => { switch (block.blockType) { case 'hero': return <h2>{block.title}</h2> case 'rich-text': return <RichText value={block.content} /> case 'quote': return <blockquote>{block.text}</blockquote> case 'gallery': return [block.image1, block.image2, block.image3].map((image) => /* … */) default: block satisfies never return null } }) }</Layout>- Cada
caseestrecha la fila. Dentro decase 'hero',blocktienetitle,aligneimage, y ningún subcampo de los otros bloques. - El
defaulthace que olvidar un bloque sea un error de compilación. Si añades un bloque al config y no uncase, en eldefaultla fila deja de serneveryastro checkfalla. En ejecución no pinta nada. depth: 1trae los ficheros como documento. Sin él,imagees el id pelado de la biblioteca. Condepth, la imagen esstring | Medio | nullen el tipo, y la demo la estrecha con una función de dos líneas (resolved) antes de pintarla: ver Relaciones:depth.overrideAccess: trueporque la API local es anónima por defecto y esta ruta decide qué se muestra. La demo no es pública para escribir:pagesdeclaraaccessy solo un administrador crea, edita o borra.- Una ruta
[slug]en la raíz no tapa/admin. Astro prefiere la ruta con nombre exacto, así que el panel y la API REST siguen donde estaban; a cambio, una página con el slugadminno se vería nunca.
Las filas llegan ya ordenadas, con su id y su blockType, y nunca con parent ni _order. Ver
Leer listas.
Escribirlo desde código
Sección titulada «Escribirlo desde código»Una lista que llega reemplaza las filas que había, y cada fila lleva su blockType y los subcampos de su
bloque, sin id (el servidor pone uno). El seed de la demo crea así sus dos páginas:
await cms.collections.pages.create( { slug: 'sobre-esta-demo', title: 'Sobre esta demo', sections: [ { blockType: 'hero', title: 'Un constructor de páginas con blocks', align: 'center', image: imageId }, { blockType: 'quote', text: 'El tipo de cada sección es fijo.', author: 'La guía' }, ], }, { overrideAccess: true },)blockType es obligatorio y tiene que ser uno del catálogo: { blockType: 'otro' } no compila, y una fila de un
tipo que no existe es UNKNOWN_BLOCK. Para el texto con formato de un rich-text, markdownToLexical, de
@kevolution-co/cms/rich-text/convert, convierte markdown al árbol que guarda el campo.
Pasar un json que ya tenías
Sección titulada «Pasar un json que ya tenías»Si hoy guardas las secciones (o los enlaces de un menú) en un campo json, pasar a array o blocks depende de
dónde vive.
Un global
Sección titulada «Un global»Un global vive en KV y una lista es el JSON de sus filas bajo una clave, así que no hay
migración: declara la lista y guarda. Es lo que hizo la demo con nav, que era un json con
[{ "href": "/", "label": "Inicio" }]:
{ name: 'nav', type: 'array', fields: [ { name: 'href', type: 'text', required: true }, { name: 'label', type: 'text', required: true }, ],}- Las filas guardadas sin
idse leen. Cada una recibe su posición comoid("0","1"), la misma en cada lectura, y el primer guardado de esa lista lo persiste. Un guardado de otro campo (eltagline) no la toca. - Los subcampos tienen que ser exactamente las claves que ya guardabas. Una clave que el config no declara
(
target, por ejemplo) o una fila a la que le falta un camporequiredhace que guardar el global falle, aunque lo que guardes sea otro campo:UNKNOWN_FIELDoREQUIRED, con la ruta de la fila (nav.0.target). Revisa el valor guardado antes de cambiar el config. Si ya lo has cambiado, el panel enseña las filas y deja corregirlas. - Un valor que no es un array de objetos se lee como si la lista no existiera (
[]) y se avisa en la consola.
Una colección
Sección titulada «Una colección»Una colección guarda las filas en tablas hijas, y ninguna migración copia lo que había en la columna json: la
migración que genera cms db:migrate crea la tabla hija y quita la columna, y las filas se pierden salvo que las
copies tú. El CMS no escribe esa copia por ti: es SQL tuyo, en la propia migración, entre el CREATE TABLE y el
DROP COLUMN.
Con posts.meta (un json con [{ "label": "…", "url": "…" }]) pasando a un array llamado links:
-
Declara
linksy quitametadel config, y ejecutapnpm cms db:migrate. Con terminal te pide confirmación, porque quitar una columna pierde sus datos. Sale esto:migrations/<fecha>_<nombre>/migration.sql CREATE TABLE `posts_links` (`parent` text NOT NULL,`id` text NOT NULL,`_order` integer NOT NULL,`label` text,`url` text,CONSTRAINT `posts_links_pk` PRIMARY KEY(`parent`, `id`));--> statement-breakpointALTER TABLE `posts` DROP COLUMN `meta`; -
Añade la copia entre las dos sentencias. Una fila de una tabla hija necesita
parent(el documento), unidy un_order(la posición, desde 0):migrations/<fecha>_<nombre>/migration.sql CREATE TABLE `posts_links` (`parent` text NOT NULL,`id` text NOT NULL,`_order` integer NOT NULL,`label` text,`url` text,CONSTRAINT `posts_links_pk` PRIMARY KEY(`parent`, `id`));--> statement-breakpointINSERT INTO posts_links (parent, id, _order, label, url)SELECT p.id, lower(hex(randomblob(16))), j.key, j.value ->> 'label', j.value ->> 'url'FROM posts p, json_each(CASE WHEN json_valid(p.meta) AND json_type(p.meta) = 'array' THEN p.meta ELSE '[]' END) jWHERE j.type = 'object';--> statement-breakpointALTER TABLE `posts` DROP COLUMN `meta`; -
Aplícala en local, mira el resultado y solo entonces en remoto:
Ventana de terminal pnpm cms db:applynpx wrangler d1 execute DB --local --command "SELECT parent, _order, label FROM posts_links ORDER BY parent, _order"pnpm cms db:apply --remotecms db:generate --checksigue en verde: compara elsnapshot.json, no el SQL que has editado.
Lo que hace cada pieza, y por qué no es un json_each(p.meta) a secas:
j.keyes la posición de cada elemento (0,1,2…), así que el orden del array se conserva.lower(hex(randomblob(16)))es elidde la fila: 32 caracteres, que es unidválido, y único por construcción. Si lo prefieres,CAST(j.key AS TEXT)también vale, porque elidsolo tiene que ser único dentro del documento.- El
CASEdeja pasar solo los arrays.json_eachsobre unnullde SQL no devuelve filas, pero sobre una cadena vacía o un JSON roto lanza un error. Sobre unnullde JSON o un número devuelve una fila sin posición, que viola elNOT NULLde_order, y sobre un texto ("hola") la fila hace fallar el->>. Sobre un objeto devuelve una fila por clave: con valores que no son JSON ("label": "x") falla, y con números,nullu objetos dentro no falla y deja filas de basura, con el nombre de la clave como_order. Los errores hacen fallar la migración entera: se aplica en una sola transacción y no queda nada aplicado (en local, comprobado), pero no avanza. WHERE j.type = 'object'salta los elementos que no son un objeto (un7, una cadena, unnull) en lugar de crear filas vacías. Esa fila no se copia y su posición queda sin usar: no importa, solo ordena.->>devuelveNULLpara una clave que falta o unnull, y el valor tal cual para el resto. Lo que no declares como subcampo no se copia: una clavetargetdeljsonse pierde con la columna.
Después de migrar:
maxRowsvale 100 por defecto. La migración no lo mira, así que una lista de 120 filas se copia entera y se lee, pero no se puede volver a guardar hasta que declares unmaxRowsmayor (hasta 1000) o quites filas:MAX_ROWS. Antes de migrar, mira cuál es la mayor:SELECT max(json_array_length(meta)) FROM posts WHERE json_valid(meta) AND json_type(meta) = 'array'.- Una celda
requiredque salió vacía (una fila a la que le faltaba la clave) no impide la migración, pero sí guardar esa lista: el panel marca la celda y la rellenas. Los subcampos de la migración no llevanNOT NULL. - La columna desaparece con la migración. El código desplegado que lea
metafalla entredb:apply --remotey el deploy del código nuevo: hazlo en una ventana de mantenimiento, o en el patrón de dos migraciones y una copia en medio de Convertir un campo en hasMany, donde la columna se quita cuando ya nadie la lee.
Si el json era de bloques
Sección titulada «Si el json era de bloques»Cada tipo de bloque es su tabla, y _order es la posición en la lista entera, no en su tabla: así que se
copia una tabla por tipo, con la misma j.key. Un json con
[{ "blockType": "hero", "title": "…" }, { "blockType": "quote", "text": "…" }] a sections:
INSERT INTO pages_sections_hero (parent, id, _order, title)SELECT p.id, lower(hex(randomblob(16))), j.key, j.value ->> 'title'FROM pages p, json_each(CASE WHEN json_valid(p.sections) AND json_type(p.sections) = 'array' THEN p.sections ELSE '[]' END) jWHERE j.type = 'object' AND j.value ->> 'blockType' = 'hero';--> statement-breakpointINSERT INTO pages_sections_quote (parent, id, _order, text, author)SELECT p.id, lower(hex(randomblob(16))), j.key, j.value ->> 'text', j.value ->> 'author'FROM pages p, json_each(CASE WHEN json_valid(p.sections) AND json_type(p.sections) = 'array' THEN p.sections ELSE '[]' END) jWHERE j.type = 'object' AND j.value ->> 'blockType' = 'quote';Una fila cuyo blockType no es de ningún INSERT no se copia. Los upload y los relationship se copian como el
id que ya guardabas, y su clave foránea hace fallar la migración (FOREIGN KEY constraint failed) si ese id ya no
existe: límpialo antes de migrar.
Los límites que conviene saber
Sección titulada «Los límites que conviene saber»- No se puede filtrar ni ordenar por un subcampo de una lista:
where,sortyselectsobresections.titleson unQueryError. Las consultas sobre filas están en #227. Para buscar páginas por algo que está en un bloque, saca ese dato a un campo de la colección (title,slug). - Una lista que llega reemplaza la anterior entera, y sin
If-Matchdos guardados a la vez son last-write-wins sobre toda ella (el panel no mandaIf-Match). - Cada tipo de bloque cuenta como una tabla en las sentencias de un guardado:
3T + 2en unupdate. La colecciónpagestieneT = 4, y un documento con muchas listas puede pasar de las 50 consultas del plan Free de D1. Ver el límite de sentencias. - Las tablas hijas no llevan clave foránea al documento: un
DELETEa mano contra D1 deja filas huérfanas.
El resto de límites —maxRows, el tamaño de una lista, UNKNOWN_BLOCK, qué pasa en un global— están en
Campos y en Limitaciones.