Saltar al contenido

Creación de páginas basadas en archivos

La creación tradicional de páginas con WordPress se hace en el editor de bloques: arrastrar bloques, configurar opciones y hacer clic en guardar. Esto funciona para clientes que crean sus propias páginas, pero genera problemas para los desarrolladores que crean páginas estructuradas y con control de versiones. El diseño de la página está en la base de datos, no en el código. No puedes revisarlo en una solicitud de cambios, revertirlo con git ni reproducirlo en una instalación nueva.

Las páginas basadas en archivos de Blockstudio resuelven este problema. Defina las páginas como archivos en su tema, escriba plantillas HTML que se conviertan en bloques WordPress y controle exactamente lo que los clientes pueden editar. Un comando explícito sincroniza esos archivos con entradas normales de WordPress, y las plantillas siguen siendo la fuente de verdad.

Esta guía explica cómo crear páginas desde cero y se centra especialmente en los controles de bloqueo y edición que hacen prácticas las páginas basadas en archivos para proyectos de clientes.

Su primera página

Cree una carpeta pages en su tema y añada una subcarpeta con dos archivos:

Código
theme/
└── pages/
    └── about/
        ├── page.json
        └── index.php
JSON
{
  "name": "about",
  "title": "About Us",
  "postStatus": "publish"
}
HTML
<h1>About Us</h1>
<p>We build things for the web.</p>

Ejecute el comando de sincronización de páginas:

Shell
wp bs pages sync

Blockstudio analiza HTML y lo convierte en bloques WordPress, y crea una página llamada “About Us” con el slug about. Ábrala en el editor y verá un encabezado y un párrafo, igual que si los hubiera añadido manualmente.

Edite index.php, cambie el texto y vuelva a ejecutar el comando. Recargue el editor para ver la actualización. Este es el ciclo básico: escriba HTML, sincronice de forma intencionada y obtenga bloques.

El lenguaje de plantillas

El analizador HTML de Blockstudio convierte elementos HTML estándar en bloques WordPress. Escriba un <p> para obtener un bloque de párrafo. Escriba un <h2> para obtener un bloque de encabezado. La correspondencia es intuitiva:

HTML Bloque
<p> Párrafo
De <h1> a <h6> Encabezado (el nivel coincide con la etiqueta)
<ul>, <ol> Lista
<blockquote> Cita
<img> Imagen
<div>, <section> Grupo
<hr> Separador
<details> Detalles
<table> Tabla

Para los bloques sin un equivalente HTML directo, use el elemento <block> con un atributo name:

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h2>Hero Title</h2>
  <p>Content over the background image.</p>
</block>

<block name="core/spacer" height="80px" />

<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
  <block name="core/button" url="/work">See Our Work</block>
</block>

Los atributos de los elementos <block> se pasan como atributos del bloque. Los valores se convierten automáticamente: "true" se convierte en booleano, "3" en entero y las cadenas JSON como '{"type":"flex"}' se descodifican en objetos.

Diseños

Los grupos admiten distintos modos de diseño mediante el atributo layout:

HTML
<!-- Default group (stacked) -->
<div>
  <p>Stacked by default.</p>
</div>

<!-- Row (horizontal flex) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
  <p>Side</p>
  <p>by side</p>
</block>

<!-- Stack (vertical flex) -->
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
  <p>Stacked</p>
  <p>with flex</p>
</block>

<!-- Columns -->
<block name="core/columns">
  <block name="core/column">
    <p>Left column.</p>
  </block>
  <block name="core/column">
    <p>Right column.</p>
  </block>
</block>

Bloques personalizados

La sintaxis <block> funciona con cualquier bloque registrado, incluidos sus propios bloques Blockstudio:

HTML
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />

Los atributos se asignan automáticamente a los valores de campo Blockstudio del bloque.

Creación de una página de destino

Aquí tiene una página de destino completa que usa bloques básicos para la estructura y el diseño:

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "slug": "landing",
  "postStatus": "publish",
  "templateLock": "all"
}
HTML
<block name="core/cover" url="https://images.unsplash.com/photo-1497366216548-37526070297c?w=1600">
  <h1>Build faster with Blockstudio</h1>
  <p>File-based blocks. Zero build step. Full editor integration.</p>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Get Started</block>
    <block name="core/button" url="/docs">Documentation</block>
  </block>
</block>

<div>
  <h2>Why developers love it</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3>No build step</h3>
      <p>Write PHP, CSS, and JavaScript. No webpack, no bundler, no transpiler.</p>
    </block>
    <block name="core/column">
      <h3>File-based</h3>
      <p>Every block is a folder. Every page is a template. Version control everything.</p>
    </block>
    <block name="core/column">
      <h3>Full editor support</h3>
      <p>Fields, previews, and InnerBlocks work in the block editor out of the box.</p>
    </block>
  </block>
</div>

<block name="core/media-text" mediaurl="https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=800" mediatype="image">
  <h2>Ship entire sites from your IDE</h2>
  <p>Define pages, blocks, and patterns as files. Blockstudio handles the rest.</p>
</block>

<div>
  <h2>Frequently asked questions</h2>
  <details>
    <summary>Do I need to learn React?</summary>
    <p>No. Templates are PHP. Fields are JSON. Interactivity is optional.</p>
  </details>
  <details>
    <summary>Does it work with my existing theme?</summary>
    <p>Yes. Drop a blockstudio folder into any theme and start creating blocks.</p>
  </details>
</div>

<div>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Start Building</block>
  </block>
</div>

Esta página incluye una portada principal, una cuadrícula de características de tres columnas, una sección de texto y contenido multimedia, acordeones de preguntas frecuentes y una llamada a la acción. Todo en un solo archivo HTML. templateLock: "all" en page.json significa que el cliente no puede cambiar nada. La siguiente sección explica cómo flexibilizarlo.

Control del editor

Aquí es donde las páginas basadas en archivos muestran todo su potencial. Blockstudio te ofrece dos controles independientes: bloqueo de plantilla y modo de edición de bloques. En conjunto, te permiten definir exactamente qué partes de una página pueden modificar los clientes. Bloquea la estructura y deja que editen el texto. Inmoviliza algunas secciones y deja otras completamente abiertas. Crea una página en la que el cliente solo pueda escribir en tres encabezados específicos.

Bloqueo de plantilla

La propiedad templateLock en page.json controla la edición estructural: si se pueden añadir, quitar o reordenar bloques.

"all" (predeterminado)

JSON
{
  "name": "terms",
  "templateLock": "all"
}

Es el bloqueo más estricto. Los clientes no pueden añadir, quitar ni mover bloques. Tampoco pueden editar su contenido (salvo que se combine con blockEditingMode). Este es el valor predeterminado si no especificas uno.

Cuándo usarlo: páginas legales, condiciones del servicio y políticas de privacidad. Cualquier página cuyo contenido solo deba cambiar mediante código.

"insert"

JSON
{
  "name": "about",
  "templateLock": "insert"
}

Los clientes no pueden añadir ni quitar bloques, pero sí mover los existentes y editar su contenido. La cantidad de bloques permanece fija, pero el orden es flexible.

Cuándo usarlo: páginas con un conjunto fijo de secciones que el cliente puede reordenar. Por ejemplo, una página de portafolio con una cantidad predeterminada de secciones cuyo orden decide el cliente.

"contentOnly"

JSON
{
  "name": "homepage",
  "templateLock": "contentOnly"
}

Los clientes pueden editar el texto, pero no añadir, quitar ni mover bloques. A diferencia de "all", "all" también impide editar el contenido, mientras que "contentOnly" lo permite explícitamente.

Cuándo usarlo: la opción más habitual para páginas destinadas a clientes. El desarrollador controla el diseño y el cliente completa el texto.

false

JSON
{
  "name": "blog",
  "templateLock": false
}

Sin ningún bloqueo. Los clientes tienen control total: pueden añadir, quitar y mover cualquier bloque, así como editarlo. La plantilla proporciona una estructura inicial, pero a partir de ahí el cliente puede hacerla suya.

Cuándo usarlo: páginas de índice de blog, páginas de contenido libre o cualquier página en la que el cliente deba tener plena libertad editorial.

Modo de edición de bloques

Mientras que templateLock controla la estructura (añadir, quitar y mover), blockEditingMode controla la interacción de cada bloque: si se puede seleccionar, configurar o editar.

Establece un valor predeterminado para la página en page.json:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

"default"

Edición completa. Se pueden seleccionar los bloques, cambiar su configuración y editar su contenido. Es la experiencia habitual del editor.

"contentOnly"

Los bloques se pueden editar, pero solo su contenido de texto. No se puede abrir su configuración, cambiar colores, ajustar el relleno ni modificar atributos que no sean de contenido. La barra de herramientas del bloque solo muestra opciones de formato de texto.

"disabled"

Los bloques no son interactivos en absoluto. Se muestran en el editor, pero no se pueden pulsar, seleccionar ni modificar de ninguna manera. El cliente ve el contenido, pero no puede tocarlo.

Anulaciones por elemento

Aquí es donde se pone interesante. El valor de blockEditingMode para la página establece un valor predeterminado para todos sus bloques, pero puedes anularlo en elementos concretos de la plantilla:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Heading</h1>
  <p blockEditingMode="contentOnly">Edit this paragraph too.</p>
</block>

<div>
  <h2>Features</h2>
  <p>This paragraph cannot be edited (inherits "disabled").</p>
  <p blockEditingMode="contentOnly">But this one can.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">This button is frozen</block>
</block>

El valor predeterminado de la página es "disabled", así que ningún bloque es interactivo al principio. Después, algunos elementos habilitan "contentOnly", lo que permite editar solo su texto. El resultado: una página en la que el cliente puede escribir exactamente en dos campos de texto (el encabezado y el párrafo principales) y en un párrafo de características. Todo lo demás queda bloqueado.

Esto funciona con cualquier elemento HTML (<h1>, <p>, <div>, etc.) y con elementos <block>. También puedes establecer blockEditingMode="default" en elementos concretos para dar acceso a la edición completa:

HTML
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>

Ahora el cliente puede cambiar el texto del botón, URL, los estilos y cualquier otro ajuste. El resto de la página permanece bloqueado.

Propagación a los elementos antecesores

Hay un detalle importante sobre cómo interactúan las anulaciones por elemento con los bloques contenedores. Si el valor predeterminado de una página es "disabled" y estableces blockEditingMode="contentOnly" en un encabezado dentro de un grupo, hay que poder acceder a ese encabezado. Pero el grupo que lo contiene es "disabled", así que no se puede acceder a él.

Blockstudio resuelve esto automáticamente. Cuando un bloque secundario tiene una anulación del modo de edición, todos los bloques antecesores se configuran como "contentOnly" para que se pueda acceder al bloque secundario. No hace falta configurar manualmente los modos de los contenedores principales. Basta con establecer la anulación en el bloque que quieres que se pueda editar y se abrirá el acceso hasta él.

HTML
<!-- page default: "disabled" -->
<div>
  <!-- this group is auto-set to "contentOnly" because it contains an override -->
  <div>
    <!-- this group is also auto-set to "contentOnly" -->
    <p blockEditingMode="contentOnly">Deeply nested but still editable.</p>
  </div>
</div>

La propagación a los antecesores solo eleva los contenedores a "contentOnly", nunca a "default". Así, los grupos antecesores se pueden recorrer (puedes acceder a ellos), pero no editar por completo (no puedes cambiar su configuración).

Matriz de decisiones

La combinación de templateLock y blockEditingMode ofrece distintos grados de control. Estas son las combinaciones más útiles:

El desarrollador lo controla todo

JSON
{ "templateLock": "all" }

No hace falta blockEditingMode. El valor predeterminado templateLock: "all" impide cualquier cambio. Úsalo en páginas que se gestionan exclusivamente mediante código.

El cliente edita todo el texto

JSON
{ "templateLock": "contentOnly" }

El cliente puede editar el texto de cualquier bloque, pero no cambiar la estructura de la página. Es una opción sencilla y flexible.

El cliente edita solo ciertos textos

JSON
{
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

Se combina con blockEditingMode="contentOnly" en elementos concretos de la plantilla. Es la opción más precisa: el cliente solo puede editar los bloques que marques.

El cliente reordena secciones fijas

JSON
{ "templateLock": "insert" }

El cliente puede reorganizar las secciones y editar el contenido, pero no añadir ni eliminar bloques. Es una buena opción para páginas con un conjunto fijo de secciones cuyo orden puede cambiar.

El cliente tiene control total

JSON
{ "templateLock": false }

La plantilla sirve como punto de partida. A partir de ahí, el cliente puede hacer lo que quiera.

Cómo conservar las ediciones del cliente

De forma predeterminada, cuando actualizas un archivo de plantilla, Blockstudio reemplaza todo el contenido de la página. Si el cliente editó un encabezado en el editor, ese cambio se pierde en la siguiente sincronización. Esto está bien para las páginas que controla el desarrollador, pero si los clientes aportan contenido, necesitas una forma de conservar su trabajo.

Claves

Añade un atributo key a cualquier elemento para combinarlo en lugar de reemplazarlo:

HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1>Default Hero Title</h1>
  <p>Default hero description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p>Feature introduction text.</p>
</div>

<div>
  <h2>Unkeyed Section</h2>
  <p>This gets replaced on every sync.</p>
</div>

Cuando cambia la plantilla y se vuelve a sincronizar la página:

  • Los bloques con clave conservan el contenido del cliente (texto, bloques internos y formato). Los atributos estructurales de la plantilla (como url de la portada) se actualizan igualmente.
  • Los bloques sin clave se reemplazan por completo con la versión de la plantilla.

Una clave protege todo el bloque y sus elementos secundarios. No hace falta asignar claves a los párrafos individuales dentro de un grupo que ya tiene una clave. La clave del grupo los cubre a todos.

Las claves deben ser únicas

Las claves deben ser únicas en toda la plantilla. Si dos elementos comparten la misma clave, el segundo se trata como si no tuviera clave (y se muestra una advertencia PHP). Usa nombres descriptivos: "hero", "features", "cta", "testimonial-section".

Evolución de las plantillas

Las claves te permiten añadir secciones nuevas a una plantilla sin alterar el contenido existente del cliente:

HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
<div key="testimonials">
  <h2>What Clients Say</h2>
  <p>Default testimonial text.</p>
</div>

Al sincronizar, se conservan los cambios del cliente en el título y los servicios. La nueva sección de testimonios aparece con el contenido predeterminado de la plantilla. Si más adelante quitas de la plantilla un bloque con clave, también se elimina de la página.

Flujo de trabajo completo para el cliente

Así se aplicaría todo esto en un proyecto real:

JSON
{
  "name": "homepage",
  "title": "Home",
  "slug": "home",
  "postStatus": "publish",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Your Company Name</h1>
  <p blockEditingMode="contentOnly">Your tagline goes here.</p>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Contact Us</block>
  </block>
</block>

<div key="features">
  <h2 blockEditingMode="contentOnly">What We Do</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service One</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Two</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Three</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
  </block>
</div>

<block name="core/media-text" key="about" mediaurl="https://example.com/team.jpg" mediatype="image">
  <h2 blockEditingMode="contentOnly">About Us</h2>
  <p blockEditingMode="contentOnly">Tell your story here.</p>
</block>

<div key="cta">
  <h2 blockEditingMode="contentOnly">Ready to get started?</h2>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Get in Touch</block>
  </block>
</div>

Esta página tiene cuatro secciones con clave. El cliente puede editar los encabezados y párrafos marcados con blockEditingMode="contentOnly", y esos cambios se conservan al actualizar la plantilla. El desarrollador controla el diseño, las imágenes, las URL de los botones y la estructura general. Si más adelante añade una sección de testimonios entre «about» y «cta», esta aparecerá en la siguiente sincronización sin alterar ninguno de los textos del cliente.

Vinculaciones de bloques: una alternativa a las claves

WordPress 6.5 introdujo las vinculaciones de bloques API, que conectan los atributos de los bloques con los metadatos de las entradas. En lugar de guardar el contenido editable en el marcado del bloque (donde lo protegen las claves), el contenido reside en wp_postmeta (donde las sincronizaciones de plantillas no pueden modificarlo).

HTML
<h1 metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'>
  Default Title
</h1>

<p metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'>
  Default description.
</p>

Las claves de metadatos deben registrarse en PHP:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest' => true,
    'single'       => true,
    'type'         => 'string',
    'default'      => 'Default Title',
) );

Las vinculaciones de bloques tienen dos ventajas frente a las claves: los datos se pueden consultar con WP_Query mediante meta_query y están disponibles en el REST API. La contrapartida es que hay que registrar cada clave de metadatos en PHP y que las vinculaciones solo funcionan con atributos de bloques individuales (no con contenido anidado complejo).

Usa claves para secciones con contenido enriquecido donde importa la estructura de los bloques (un grupo con encabezados, párrafos e imágenes). Usa vinculaciones para valores de texto individuales que también necesites consultar o mostrar en otros lugares.

Plantillas de tipos de contenido

Usa templateFor para establecer una estructura de bloques predeterminada para todas las entradas nuevas de un tipo determinado:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}
HTML
<h1>Product Name</h1>

<block name="core/columns">
  <block name="core/column">
    <img src="" alt="Product image" />
  </block>
  <block name="core/column">
    <p>Product description goes here.</p>
    <block name="core/buttons">
      <block name="core/button" url="#">Buy Now</block>
    </block>
  </block>
</block>

<div>
  <h2>Specifications</h2>
  <table>
    <thead>
      <tr><th>Feature</th><th>Value</th></tr>
    </thead>
    <tbody>
      <tr><td>Weight</td><td>1.2 kg</td></tr>
    </tbody>
  </table>
</div>

Todas las entradas nuevas de tipo «product» empiezan con esta estructura. templateLock: "insert" permite a los editores reorganizar las secciones y editar el contenido, pero no añadir ni quitar bloques.

Consejos

Sincroniza en un punto de despliegue planificado. Ejecuta wp bs pages sync después de cambiar o desplegar las fuentes de las páginas. Las visitas a la interfaz pública y al área de administración nunca sincronizan las páginas. El sistema de despliegue PHP puede llamar a Blockstudio\Pages::reconcile() y examinar su informe legible por máquina.

Fija los ID de las entradas importantes. Usa postId en page.json para las páginas a las que hacen referencia menús, enlaces codificados directamente u otros sistemas. Si no fijas el ID, una página eliminada y creada de nuevo recibe otro ID y esas referencias dejan de funcionar.

Usa sync: false para crear páginas iniciales. Si quieres crear una página una sola vez y luego entregársela por completo al cliente, configura "sync": false y créala con Blockstudio\Pages::force_sync(). La reconciliación normal la ignorará.

Bloquea y desbloquea con PHP. Llama a Blockstudio\Pages::lock('about') para impedir la sincronización de una página concreta (útil durante periodos de edición del cliente). Llama a Blockstudio\Pages::unlock('about') para volver a habilitarla.

Motores de plantillas. Además de PHP, puedes escribir plantillas en Twig (requiere Timber) o en Blade (requiere illuminate/view). Esto es útil para bucles y filtros, pero las plantillas de página se compilan durante la sincronización explícita, no durante la solicitud de la interfaz pública. Usa PHP si la compilación del propio código fuente necesita funciones auxiliares exclusivas de PHP.

La sincronización forzada ignora las claves. Al llamar a Pages::force_sync('about'), se reemplaza todo el contenido de la página y se ignoran las claves y las comprobaciones de la fecha de modificación. Úsala cuando quieras restablecer deliberadamente una página al estado de la plantilla.

Próximos pasos

  • Referencia de páginas: todas las propiedades de page.json, el PHP API y una explicación detallada del algoritmo de combinación por claves.
  • Resumen de páginas y patrones: el analizador de HTML, la referencia de sintaxis de bloques, los renderizadores personalizados y el mapeo de elementos.
  • Patrones: la misma sintaxis de plantillas para crear patrones de bloques reutilizables en lugar de páginas.