Contenido dinámico: fuentes, bucles y asignaciones de campos

Contenido dinámico conecta registros de un proveedor habilitado con los bloques normales del CMS. El proveedor controla los datos y sus traducciones; usted controla el diseño, la plantilla repetida y las asignaciones. Esta guía explica el flujo del panel de CMS 1.104.0 con el estándar de fuentes 1.0. El ejemplo es el catálogo de plugins publicado.

Puede configurar las conexiones sin escribir peticiones API ni introducir IDs de bloques. El acceso API y las credenciales pertenecen a la integración instalada; este espacio selecciona fuentes ya registradas por ella.

Encontrar una fuente y sus usos

Abra Contenido dinámico → Fuentes. Los detalles muestran proveedor, origen declarado, colección o registro único, idiomas, clave estable y campos disponibles. La declaración de idiomas describe un contrato; no confirma una conexión en directo satisfactoria.

Las vistas Bucles, Conexiones de campos y Problemas indican dónde se usan las fuentes. Filtre por sitio, estado de publicación o búsqueda. Las cifras cuentan bloques y conexiones guardados, no tarjetas generadas. Abrir el inventario lee la configuración sin solicitar contenido remoto. Los usos de Shared Slots enlazan a su editor existente; el flujo guiado siguiente utiliza slots propios de la página.

La integración del ejemplo ofrece tres fuentes distintas:

Published plugin catalog (webblocks-extensions-live::plugins): colección para tarjetas repetidas.
Published plugin (webblocks-extensions-live::plugin): un plugin seleccionado, por ejemplo como registro fijo.
Catalog interface (webblocks-extensions-live::ui): el registro labels aporta textos de interfaz traducidos y compartidos.

Estas etiquetas del proveedor pueden seguir en inglés aunque el panel esté traducido. Los registros de la fuente usan el idioma solicitado.

Conectar una fuente a una página

En los detalles, seleccione Usar en una página. Elija sitio y página y pulse Cargar destino. Para la colección del catálogo, seleccione Grid como bloque del bucle. Cargue ese destino y seleccione su hijo directo Card como plantilla repetida.

En una página publicada puede inspeccionar y previsualizar inmediatamente. Antes de guardar cambios, elija Preparar borrador y seleccione el destino en ese borrador. Los bloques clonados tienen IDs propios; utilice los selectores visibles y revise las asignaciones resultantes. La página publicada permanece intacta.

Si falta una plantilla adecuada, Crear cuadrícula y tarjeta iniciales añade al borrador una plantilla sin conectar en un slot propio de la página. Conserva los bloques y no elige asignaciones automáticamente. La instalación, el acceso y las credenciales API se configuran en la integración del proveedor, no aquí. Consulte Sistema de plugins para instalarla.

Elegir el bucle y la plantilla repetida

El bucle pertenece al Grid; la Card se repite una vez por registro coincidente. Los bloques Image, Header, Plain Text y Button Link dentro de la Card reciben el registro actual. Un Header fijo junto a la Card sigue siendo editorial y no puede usar el registro actual de ese bucle.

El árbol identifica el propietario del bucle, la plantilla repetida y los campos conectados. Los antecesores contraídos señalan contenido dinámico debajo. Siga un indicador hasta el bucle o la asignación. Una sola Card guardada puede producir diez tarjetas públicas sin diez copias editables.

Elija un hijo directo compatible, no un nieto ni un bloque de otra página. Section, Container, Stack, Cluster, Grid y Slide admiten plantillas hijas que cumplan las demás reglas; Slider requiere Slide, Columns requiere Column Item, Feature Grid requiere Feature Item o Column Item y Link List requiere Link List Item. Card y Split no ofrecen esta capacidad de contenedor de colecciones.

Section
└─ Container
   └─ Grid  [loop: Published plugin catalog]
      ├─ Header  [fixed editorial block]
      └─ Card  [repeated template]
         ├─ Image
         ├─ Header
         ├─ Plain Text
         └─ Button Link

Configurar filtros, ordenación y paginación

Para el catálogo, configure Máximo de registros en 50, Campo de ordenación en title, dirección ascendente y Registros por página en 12; active Paginar registros. Cincuenta es el límite de resolución, no una garantía de que existan cincuenta registros. Diez coincidencias con doce por página producen una página de vista previa. Slider no admite este control de paginación.

Filtre solo por campos declarados. Published plugin catalog ya selecciona plugins publicados en el proveedor; no invente un campo status ni mantenga otro filtro de publicación en CMS. Configure por separado Si no hay registros y Si falla la fuente: ocultar la plantilla o conservar su versión editorial. Revise ambas decisiones antes de publicar.

En colecciones pequeñas, CMS filtra y ordena los registros devueltos. Los proveedores con capacidad de consulta ejecutan la consulta. Los detalles de la fuente indican el modelo utilizado.

Asignar campos al registro actual, a uno fijo o al valor editorial

En Asignaciones de la plantilla, elija el modo de valor de cada campo de destino:

Registro actual del bucle: los valores cambian por tarjeta. Seleccione colección y campo compatible; el registro es el elemento actual.
Registro fijo de la fuente: todas las tarjetas pueden compartir un valor. Seleccione fuente, registro y después un campo compatible.
Valor editorial / respaldo: utiliza el texto o medio introducido en el bloque. Si una conexión no devuelve un valor utilizable, el valor editorial también puede servir de respaldo.

Por ejemplo, conecte el título de Header a title, el contenido de Plain Text a summary y la URL de Button Link a url del registro actual. Para la etiqueta del botón, use la fuente fija Catalog interface, registro labels, campo explore. Fuente, registro y campo tienen selectores separados; Buscar registros y campos reduce las opciones.

Los bloques conectados también tienen una pestaña Contenido dinámico. Los valores normales de Campos del bloque son respaldos editoriales. Un campo de texto no puede seleccionar uno exclusivo de URL; las opciones del registro actual se limitan a la rama de la plantilla seleccionada. Antes de cambiar o eliminar un bucle, resuelva las asignaciones afectadas; la validación rechaza conexiones huérfanas o incompatibles.

Conectar por separado imagen, texto alternativo, pie y enlace

La fuente proporciona una URL de imagen accesible o una referencia multimedia de esta instalación CMS. El ID numérico de imagen de una aplicación remota no es automáticamente un ID multimedia CMS. CMS muestra la imagen mediante el bloque Image normal; no se copia el archivo en cada Card.

Utilice cuatro conexiones independientes en Image del catálogo:

Fuente de imagen → image_url del registro actual.
Texto alternativo → image_alt.
Pie opcional → image_caption.
Enlace → url.

El archivo puede compartirse entre idiomas, mientras cambian texto alternativo y pie. El texto alternativo describe información visual relevante; el pie añade contexto visible opcional. No copie uno en el otro. En la API, Image subtitle representa el texto alternativo e Image title el pie. Compruebe la carga y la adecuación de ambos textos; un campo de tipo URL no garantiza una imagen.

Obtener las traducciones del proveedor

El estándar 1.0 exige a cada fuente los seis idiomas CMS: en, tr, de, es, it y fr, aunque el sitio habilite menos. CMS solicita el idioma habilitado del sitio actual; el proveedor entrega texto del registro, texto alternativo, pie y etiquetas compartidas correspondientes. No se traduce cada tarjeta generada en el editor de páginas.

La misma Card usa, por ejemplo, summary en inglés y la traducción turca del proveedor cuando el idioma solicitado es tr. La etiqueta del botón procede de Catalog interface / labels / explore en ese mismo idioma. El archivo de imagen puede seguir siendo el mismo.

Las partes estáticas escritas alrededor del bucle conservan las traducciones normales de páginas y bloques. La validación comprueba marcadores de idioma, claves estables y tipos, pero no certifica la calidad de traducción. Previsualice cada idioma habilitado y revise el texto real. El proveedor no debe etiquetar inglés sin traducir como otro idioma.

Comprobar la vista previa configurada antes de guardar

Seleccione Idioma de vista previa y pulse Comprobar fuente y previsualizar. La vista privada en una pestaña nueva muestra la plantilla real con las asignaciones, filtro, ordenación, límite y paginación actuales sin guardar. No guarda ni publica la página. Abrir únicamente los detalles de la fuente no realiza esta comprobación.

Confirme cantidad de registros, títulos, resúmenes, etiquetas y destinos de botones. Compruebe imágenes cargadas, textos alternativos y pies traducidos. Distinga un resultado vacío válido de acceso denegado, respuesta que incumple el contrato o proveedor no disponible. La vista previa informa por separado. Revise acceso o ajustes del proveedor cuando corresponda; no sustituya datos ausentes por traducciones supuestas.

Si cambia ajustes, genere otra vista previa. Con paginación, recorra las páginas para revisar el resultado configurado. Una muestra API ayuda a diagnosticar, pero no sustituye la vista visual completa de la Card.

Guardar un borrador y revisar la publicación por separado

Guardar conexiones del borrador solo actualiza el borrador y registra una revisión. Si la página cambió desde que la abrió, recargue y revise antes de guardar. Una configuración inválida conserva los ajustes anteriores. Revise de nuevo el borrador renderizado en todos los idiomas habilitados y use el flujo editorial normal para publicar o promover la actualización.

Una colección repite bloques dentro de una página existente. El destino de detalle debe existir o proceder de una regla de Páginas automáticas configurada aparte. Conectar un bucle no crea ni activa esa regla. El proveedor de plugins publicados determina los registros disponibles; CMS no debe mantener una segunda copia manual del catálogo.

Referencia técnica: estándar de fuentes y contrato de entidad

Un plugin habilitado registra las fuentes en PluginDefinition::contentSources(...). Un resolutor de entidad implementa ContentSourceResolver: options() ofrece opciones seguras y legibles con identidad estable como clave; resolve() devuelve un registro para sitio, página, idioma y contexto de vista previa. Un resolutor de colección implementa ContentCollectionSourceResolver; las colecciones grandes pueden implementar QueryableContentCollectionSourceResolver con ContentCollectionQuery y ContentCollectionResult para consultas, totales y ventanas de página.

La declaración siguiente pertenece a la integración, no al editor. Cada registro resuelto debe incluir _locale igual al idioma solicitado, una clave de cadena no vacía declarada por recordKey y todos los campos declarados. Use null para valores no disponibles; las claves de colección deben ser únicas. Los tipos son text, rich_text, url o media. Un valor media es un ID multimedia CMS positivo; los demás valores distintos de null son cadenas. Los valores URL deben cumplir el contrato URL de la fuente.

ContentSourceDefinition::collection('catalog::items')
  ->label('Catalog items')
  ->resolver(CatalogItems::class)
  ->standard(
    locales: ['en', 'de', 'tr', 'es', 'it', 'fr'],
    description: 'Localized catalog records.',
    origin: 'Catalog application',
    recordKey: 'id',
  )
  ->fields([
    'id' => ['type' => 'text', 'label' => 'Record ID'],
    'title' => ['type' => 'text', 'label' => 'Title'],
    'image_url' => ['type' => 'url', 'label' => 'Image'],
    'image_alt' => ['type' => 'text', 'label' => 'Alternative text'],
    'image_caption' => ['type' => 'text', 'label' => 'Caption'],
  ]);

Las fuentes sin versión se marcan como Heredada — necesita actualizar el estándar. Las selecciones existentes pueden conservarse; las conexiones nuevas requieren el estándar multilingüe. Los proveedores controlan tablas y registros; CMS controla diseño y renderizado. Los contenedores de plugins activan la capacidad con contentCollectionTemplate() y muestran los hijos resueltos con ContentCollectionRenderer::children($block); los manifiestos usan content_collection.enabled y opcionalmente content_collection.child_types. Los plugins deben reutilizar los renderizadores Card, Grid e Image del núcleo.

Referencia técnica: acceso, caché y valores de respaldo

Para registros restringidos, añada ContentSourceAccessPolicy mediante accessPolicy(...); CMS comprueba sitio, página, idioma, estado de vista previa y actor autenticado antes de resolver. Los fallos de entidad y valores vacíos conservan el respaldo editorial del campo. El resultado vacío de una colección y los errores del resolutor se configuran por separado; fuentes denegadas o eliminadas conservan el árbol guardado. Problemas y los controles del bloque identifican conexiones no disponibles sin borrarlas silenciosamente.

cacheFor($seconds) habilita caché limitada; cero, el valor predeterminado, la desactiva. Las claves incluyen fuente, sitio, página, idioma, argumentos de registro/consulta y ajustes. La vista previa omite esta caché. Tras cambiar datos del dominio, llame a app(ContentSourceRuntime::class)->invalidate('plugin-handle::source') para invalidar sus variantes. Duplicación, revisiones y exportación/importación conservan conexiones y configuración de colección; los resultados ejecutados del proveedor no se copian en esos paquetes.

Referencia técnica: Internal Content API

GET /webadmin/api/content-sources descubre fuentes habilitadas y accesibles. Añada block_id para ver destinos compatibles y capacidad de colección. POST /webadmin/api/content-sources/{source}/preview resuelve una entidad seleccionada o un máximo de cinco muestras de colección, exponiendo solo campos declarados. Este endpoint de muestras no renderiza toda la plantilla configurada.

PATCH /webadmin/api/blocks/{block} acepta content_bindings y content_collection en el nivel superior o dentro de settings. Cada objeto sustituye su configuración correspondiente; null la borra. Se validan acceso, registros, tipos, pertenencia de hijos directos y capacidad de plantilla. Las peticiones inválidas devuelven 422 invalid_content_source_configuration. Use un borrador propio o de actualización y renderice después; respete la autorización y publicación de Internal Content API. Image subtitle y title mantienen sus distintos significados de texto alternativo y pie.