Fragmentos de contenido visual: plantillas visual-content-fragments-templates
En Adobe Experience Manager (AEM) as a Cloud Service, las plantillas de HTML se pueden utilizar para visualizar fragmentos de contenido y entregarlos en formato HTML.
Las plantillas de HTML permiten controlar cómo se muestran los fragmentos de contenido. Puede crear plantillas de HTML en el editor de código que elija, luego cargarlas y asignarlas a modelos de fragmentos de contenido en AEM. Los marcadores de posición de contenido que utilizan Handlebars.js permiten asignar la plantilla a tipos de datos en el modelo de fragmento de contenido. Una vez asignada a un modelo, una plantilla está disponible para utilizarse con cualquier fragmento de contenido basado en el modelo, para visualizar el fragmento o para enviarlo como una experiencia modular en formato HTML a cualquier canal, por ejemplo web, correo electrónico, aplicación móvil u otros.
Este artículo explica cómo crear plantillas de HTML personalizadas con sintaxis de Handlebars para procesar fragmentos de contenido visual.
Después de crear las plantillas, puede:
Lo que aprenderá what-you-will-learn
Después de proporcionar una introducción (muy rápida) a:
- Uso de las plantillas en AEM
- Uso de la URL de publicación
Esta página cubre (con más detalle):
- Handlebars: los conceptos básicos necesarios de la sintaxis
- Cómo acceder a los datos de fragmentos de contenido
- Uso de fragmentos de contenido anidados
- Administrar campos multivalor
- Creación de bucles y lógica condicional
- Prácticas recomendadas de diseño de plantillas para fragmentos de contenido
Requisitos previos prerequisites
Para comprender y trabajar con las tecnologías aquí tratadas, debería tener lo siguiente:
- Comprensión básica de HTML
- Familiaridad con fragmentos de contenido y modelos de fragmentos de contenido de AEM
- Comprensión de los modelos de fragmentos de contenido
Uso de una plantilla de HTML de fragmento de contenido using-a-content-fragment-html-template
Uso de una plantilla de HTML de fragmento de contenido en AEM using-a-content-fragment-html-template-in-aem
Para obtener más información sobre cómo utilizar la plantilla en AEM, consulte:
Uso de la URL de publicación de fragmento de contenido visual using-the-visual-content-fragment-publish-url
Una vez que haya creado fragmentos de contenido visual utilizando la plantilla, puede usar la URL de publicación de los fragmentos de contenido visual.
Manillar: los (muy) conceptos básicos handlebars-the-very-basics
Handlebars es un lenguaje de creación de plantillas simple que usa llaves dobles (corchetes) {{ }} para insertar contenido dinámico en HTML.
Sintaxis básica basic-syntax
Un ejemplo de sintaxis básica de Handlebars:
Conceptos clave key-concepts
Los conceptos clave de Handlebars:
{{ }}{{{ }}}{{! }}{{{ }}}) para los valores de campo porque los valores se representan previamente en HTML.Referencia de contexto de plantilla template-context-reference
Cuando se representa la plantilla, recibe un objeto de contexto que contiene todos los datos sobre el fragmento de contenido. Esto abarcará:
-
el fragmento que ha seleccionado
-
todos los demás fragmentos a los que se hace referencia desde ese fragmento seleccionado
note NOTE Se puede hacer referencia a los fragmentos: - en la IU: hasta la profundidad máxima de 5
- al utilizar la API: la profundidad es configurable, hasta la profundidad máxima de 10
Fragmento de contenido principal main-content-fragment
La estructura del objeto de contexto para el fragmento de contenido (seleccionado):
fieldsallFields{name, value} para iteraciónhasFieldstrue si el fragmento tiene camposmetadataEstructura de propiedades (Fragmentos principal y de referencia) properties-structure-main-and-referenced-fragments
El objeto properties tiene la misma estructura para el fragmento seleccionado y para cada fragmento referenciado.
idtitledescriptionpath/content/dam/...hasDescriptiontruecreatedDatemodifiedDatepublishedDatestatusDRAFTmodelid, path, name, technicalName, descriptionvalidationStatus{property, message}previewReplicationStatustagsid, title, titlePath, name, path, descriptionfieldTagstags.Ejemplos: Acceso a plantillas
Para el fragmento de contenido (seleccionado):
Fragmentos de contenido referenciados referenced-content-fragments
La estructura del objeto de contexto para cualquier fragmento al que se haga referencia:
hasReferencedFragmentstrue cuando existen referenciasreferencedFragmentsreferencesErrortrue si se produjo un error al cargar las referenciasreferencesErrorMessagereferencesError es trueEstructura del fragmento de referencia referenced-fragment-structure
Cada elemento de referencedFragments contiene:
anchorIdpropertieshasFieldsfieldsallFields{name, value} para iteraciónmetadataEjemplos: Acceso a la plantilla para el primer fragmento de contenido al que se hace referencia (primer elemento de la lista indexada en 0):
O desde el mapa de campos:
Estructura de metadatos de fragmento de contenido content-fragment-metadata-structure
Los metadatos de un fragmento (el bloque de metadatos/campos respaldado por su esquema de metadatos) aparecen en metadata. Es distinto de properties, que contiene los valores estructurales (title, description, path, tags, dates, status).
metadatametadata se representan como vacías en lugar de como erroresmetadata.schemaIddefault cuando no se encuentra ningunometadata.valuesmetadata.fieldsname, type (cadena, entero, número, booleano, matriz, objeto), value y title (etiqueta legible en lenguaje natural del esquema)metadata.values mantiene los tipos JSON, un número o una lectura booleana de ahí funciona directamente con los ayudantes booleanos y de comparación, a diferencia de un campo escalar que alcanza la plantilla preprocesada como una cadena. Consulte también Comparación y ayudantes de lógica booleana.Estructura del campo de recursos asset-field-structure
Los recursos a los que se hace referencia no son una colección de nivel superior; no hay referencedAssets. Se llega a un recurso a través del campo que lo contiene, fields.<assetField> o fields.<ref>.fields.<assetField> para un recurso dentro de un fragmento al que se hace referencia.
Un valor de campo de recurso tiene doble naturaleza. Impreso sin procesar es el recurso procesado previamente por HTML; si se profundiza en, expone los metadatos del recurso en properties.
<img> para una imagen).Requiere llaves triples:
{{{fields.heroImage}}}propertiesUn campo de recursos de varios valores es una lista. Itere con {{#each fields.gallery}}, usando {{{this}}} para HTML y {{this.properties.assetId}} para los metadatos.
Propiedades de un recurso DAM local properties-of-a-local-dam-asset
Estas claves las lleva la respuesta de fragmento de contenido y siempre están disponibles:
assetIdurn:aaid:aem:1fb05fe4-...path/content/dam/wknd/ian_provo.jpgnameian_provo.jpgtitledescriptiontypeassetassetfieldNameprofilePicturestatusNEW, DRAFT, PUBLISHED, MODIFIED, UNPUBLISHEDDRAFTpreviewReplicationStatusPUBLISHED, UNPUBLISHED, MODIFIED, NEVER_PUBLISHEDcreated, modified, publishedat (ISO-8601), by, fullName, firstName, lastNamedc:formatimage/jpegrepo:size251434tiff:ImageWidth1152tiff:ImageHeight1152yournamespace:persistentID. Obtenido del recurso bajo demandaLos nombres de propiedad que contienen dos puntos requieren la sintaxis entre corchetes:
Propiedades de un recurso de Dynamic Media properties-of-a-dynamic-media-asset
Un recurso de Dynamic Media (remoto) no lleva ninguna ruta DAM. Solo hay dos claves en línea:
repositorydelivery-p12345-e67890.adobeaemcloud.comassetIdurn:aaid:aem:1fb05fe4-...Juntos, esto es suficiente para crear una URL de entrega de Dynamic Media en lugar de utilizar la imagen incrustada. Las demás propiedades se recuperan del host de entrega del recurso. Solo se sirven allí los recursos aprobados (publicados), por lo que un recurso de Dynamic Media no aprobado no resuelve nada más allá de estas dos claves.
this.properties.<key> y no un properties.<key> vacío. Una ruta de acceso vacía cuya clave también es una propiedad de fragmento de contenido, como title, description, path o status, se resuelve en el fragmento y no en el recurso.Acceso básico al campo basic-field-access
Se recomienda el acceso directo al campo, si es necesario, puede iterar en todos los campos.
Acceso directo al campo (recomendado) direct-field-access-recommended
Acceda a los campos directamente por nombre mediante el mapa de campos:
Recuerde:
- Utilice llaves triples
{{{ }}}para los valores de campo si contienen HTML procesado previamente (texto enriquecido) - Los nombres de campo (título, subtítulo, descripción, primaryImage) deben coincidir con el modelo de fragmento de contenido exactamente
- Los campos que faltan no se representan: no se generan errores y la sintaxis de Handlebars permanece presente (y visible) en el fragmento de HTML procesado
Iterar en todos los campos iterate-through-all-fields
Utilice allFields cuando no conozca los nombres de campo por adelantado:
Recuerde:
{{name}}usa llaves dobles (etiqueta de texto sin formato){{{value}}}usa llaves triples (valor de HTML procesado previamente)
Fragmentos de contenido anidados nested-content-fragments
Cuando un campo de fragmento de contenido hace referencia a otro fragmento de contenido, puede utilizar la notación de puntos para acceder directamente a los campos del fragmento al que se hace referencia.
Anidado de un solo nivel single-level-nesting
Un ejemplo de anidamiento de un solo nivel:
Patrón: fields.referenceFieldName.nestedFieldName
Anidado de varios niveles multi-level-nesting
El sistema admite una profundidad de anidación ilimitada:
Patrón: fields.level1.level2.level3.fieldName (profundidad limitada; el valor predeterminado es 5, se puede ampliar a 10 cuando se utiliza la API)
Requisito de parámetro de API: hidratación api-parameter-requirements
Para habilitar el acceso anidado a fragmentos de contenido, debe incluir el parámetro de consulta hydration en la llamada de API:
Para habilitar la hidratación:
# Enable hydration with depth=2 for 2 levels of nesting
GET /adobe/sites/cf/fragments/{id}/preview?hydration=%7B%22enabled%22%3Atrue%2C%22maxDepth%22%3A2%7D
maxDepth123+Campos multivalor multi-valued-fields
Existen varios tipos de campos multivalorados.
Campos de texto de varios valores multi-valued-text-fields
Los campos de texto, number, fecha y otros campos simples se convierten en matrices cuando se asignan varios valores:
Recuerde, cuando acceda a elementos de matriz por índice en Handlebars:
- Use:
.[0](punto antes del corchete)
- No:
[0]
Campos numéricos multivalorados multi-valued-number-fields
Los números se convierten en cadenas para su procesamiento:
Referencias de fragmentos de contenido multivalor multi-valued-content-fragment-references
Cuando un campo hace referencia a varios fragmentos de contenido:
Referencias de recursos de varios valores multi-valued-asset-references
Referencia de contenido campos configurados para tipos de contenido que son recursos (por ejemplo, imágenes y documentos) se representan previamente como HTML. Los recursos de varios valores se convierten en matrices:
Referencias anidadas de varios valores nested-multi-valued-references
Las referencias de varios valores pueden contener referencias de varios valores en cualquier profundidad:
Bucles e iteración loops-and-iteration
Handlebars proporciona el ayudante {{#each}} para recorrer en iteración matrices y objetos.
Iteración en matrices iterating-over-arrays
Un ejemplo de iteración en matrices:
Variables especiales en bucles special-variables-in-loops
Dentro de bloques de {{#each}}, Handlebars proporciona variables especiales:
Iteración en fragmentos referenciados iterating-over-referenced-fragments
Ejemplo de iteración en fragmentos referenciados:
Bucles anidados nested-loops
Un ejemplo de bucles anidados:
Renderización condicional conditional-rendering
Utilice condicionales para mostrar u ocultar contenido en función de la disponibilidad de los datos.
If/Else básico basic-if-else
Un ejemplo de una construcción básica if-else:
A menos que (negativo o condicional) unless-negative-conditional
Un asistente de unless:
hideAuthor es un valor booleano real; por ejemplo, de metadata.values.*. Sin embargo, un campo booleano de un solo valor, llega preprocesado como la cadena "true" o "false", y "false" es una cadena que no está vacía (verdadera), por lo que {{#unless fields.hideAuthor}} oculta al autor incluso cuando el campo es false. Compare el campo escalar explícitamente en su lugar; por ejemplo, {{#if (eq fields.hideAuthor "true")}}. Consulte también Comparación y ayudantes de lógica booleana.Condiciones anidadas nested-conditials
Un ejemplo de condicional anidado:
Comparación y ayudantes de lógica booleana comparison-and-boolean-logic-helpers
Además de los ayudantes de stock {{#if}} y {{#unless}}, el servicio registra los ayudantes de comparación y de lógica booleana para que una plantilla pueda procesarse condicionalmente en los valores de campo. Tanto los ayudantes de comparación como los de lógica booleana funcionan como un bloque y como una subexpresión en línea:
Comparación numérica en campos de un solo valor numeric-comparison-on-single-valued-fields
Un campo de un solo valor se presenta como una cadena (fields.quantity is "7", no 7), pero los ayudantes hacen que una cadena numérica sea obligatoria en el momento de la comparación, por lo que {{#gte fields.quantity 5}} y {{#eq fields.quantity 0}} se comparan como números, junto con {{#gte metadata.values.quantity 5}}, donde el valor ya se ha escrito. La ordenación (gt/gte/lt/lte) siempre se compara numéricamente. Coerces de igualdad con intención: un campo de cadena se compara como un número sólo cuando el otro operando es un número auténtico: un literal numérico ({{#eq fields.qty 0}}) o un campo escrito como metadata.values.*. La comparación de dos campos de cadena o un literal entre comillas ({{#eq fields.version "1.0"}}) mantiene la igualdad de cadena exacta, por lo que las versiones, los códigos postales y los identificadores modelados como texto nunca se contraen ("007" no es igual a "7"). Las fechas se cruzan como cadenas ISO-8601, por lo que eq/neq las comparan por igualdad de cadena exacta y los ayudantes de pedidos las rechazan como no numéricas. Un operando que falta, en blanco o no numérico se trata como “condición no cumplida” y procesa la rama else en lugar de generar errores.
Los ayudantes booleanos utilizan la veracidad simple (sin coerción) boolean-helpers-use-plain-truthiness-no-coercion
Los ayudantes booleanos and/or/not no hacen la coerción: aplican la veracidad de Handlebars estándar, donde cualquier cadena que no esté vacía es verdadera (los valores falsos son false, null, undefined, 0, "", []). Un campo booleano de un solo valor se presenta como la cadena "true" o "false", y "false" es una cadena que no está vacía, por lo que {{#not fields.flag}} ve un valor “true” y toma la rama else incluso cuando el campo indica “false”. Compare explícitamente un campo booleano escalar ({{#eq fields.flag "true"}}) en lugar de proporcionarlo a and/or/not; ya se ha escrito una lectura booleana de metadata.values.* y funciona directamente con los ayudantes booleanos.
Campos con nombre de asistente fields-named-after-a-helper
Si se registran estos ayudantes, sus nombres se reclaman globalmente, pero un campo con el nombre de uno sigue procesando su propio valor cuando se lee sin argumentos: {{eq}} dentro de {{#with fields}} imprime el texto del campo eq, no un resultado de comparación. Los ayudantes están disponibles tanto en la plantilla de visualización como dentro de Handlebars incrustados en un valor de campo de fragmento de contenido.
Ayudantes de Handlebars integrados built-in-handlebars-helpers
Handlebars incluye varios ayudantes integrados, más allá de {{#if}} y {{#each}}.
{{#if condition}}false, undefined, null, 0, "", []{{#unless condition}}#if){{#each array}}{{else}} para matrices vacías{{#with object}}{{lookup this "key"}}Con el asistente with-helper
Crea un nuevo ámbito para objetos anidados para reducir los prefijos de ruta repetitiva:
Avanzar patrones advanced-patterns
A continuación se muestran algunos ejemplos de patrones avanzados.
Acceso al contexto principal en bucles anidados accessing-parent-context-in-nested-loops
Use ../ para acceder al ámbito principal desde un bucle anidado:
Clases CSS dinámicas dynamic-css-classes
Un ejemplo de clases CSS dinámicas:
Ejemplos completos complete-examples
Se proporcionan varios ejemplos completos como referencia.
Publicación de blog con autor
Una publicación de blog con detalles del autor:
Llamada de API requerida:
GET /adobe/sites/cf/fragments/{id}/preview?hydration=%7B%22enabled%22%3Atrue%2C%22maxDepth%22%3A1%7D
Vista de tabla genérica (sin conocimientos previos de campos) generic-table-view-no-prior-knowledge-of-fields
Una vista de tabla genérica, sin un conocimiento inherente de campos. es similar a la Plantilla genérica:
Prácticas recomendadas best-practices
Las prácticas recomendadas incluyen:
-
Utilice siempre llaves triples para los valores de campo que contengan contenido de marcado de HTML.
-
Los valores de campo se representan previamente en HTML.
note NOTE Las llaves dobles muestran las etiquetas HTML sin procesar como texto sin formato.
code language-handlebars <!-- CORRECT --> {{{fields.description}}} <!-- WRONG - displays HTML tags as text --> {{fields.description}} -
-
Compruebe la existencia antes de acceder a los campos anidados.
code language-handlebars <!-- GOOD: check before accessing nested fields --> {{#if fields.author}} <p>By {{{fields.author.name}}}</p> {{/if}} <!-- RISKY: may render empty if author is not set --> <p>By {{{fields.author.name}}}</p> -
Utilice el acceso directo al campo siempre que sea posible.
- Es más fácil de leer y de mantener que repetir
allFieldsy coincidir por nombre.
- Es más fácil de leer y de mantener que repetir
-
Estructurar plantillas con comentarios de sección.
code language-handlebars {{! ===== HEADER SECTION ===== }} <header> <h1>{{properties.title}}</h1> </header> {{! ===== MAIN CONTENT ===== }} <main> {{#if hasFields}} <!-- fields rendering --> {{/if}} </main> {{! ===== REFERENCES ===== }} {{#if hasReferencedFragments}} <!-- references rendering --> {{/if}} -
Gestionar correctamente los datos que faltan con reserva.
code language-handlebars {{#if fields.title}} <h1>{{{fields.title}}}</h1> {{snippet-not-found:else}} <h1>Untitled</h1> {{/if}} -
Utilice siempre una estructura de documentos de HTML adecuada.
code language-handlebars <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>{{properties.title}}</title> </head> <body> <!-- your content here --> </body> </html> -
Realice pruebas con una variedad de escenarios de contenido:
- Todos los campos completados
- Faltan campos opcionales
- Campos multivalor vacíos
- Anidado profundo (varios niveles)
- Referencias que no se cargan
-
Utilice elementos semánticos de HTML:
- Para una mejor accesibilidad, use
<article>,<header>,<main>,<footer>,<time>,<address>o similar.
- Para una mejor accesibilidad, use
-
Mantener estilos en CSS.
- Utilice etiquetas
<style>u hojas de estilo externas. - Evite los estilos en línea siempre que sea posible.
- Utilice etiquetas
-
Lógica compleja del documento:
- Use los comentarios de Handlebars
({{! }}). - No utilice comentarios de HTML, que aparecen en la salida procesada.
- Use los comentarios de Handlebars
Resolución de problemas troubleshooting
Algunas sugerencias para la solución de problemas incluyen:
<p>Hello World</p> se muestra literalmente{{{fields.description}}}{{{fields.author.name}}} está en blancomaxDepth tenga la profundidad suficiente{{#each fields.tags}} para repetir todos los elementos{{{fields.tags[0]}}} se representa vacío{{{fields.tags.[0]}}}hasReferencedFragments siempre es falso?hydration=%7B%22enabled%22%3Atrue%7D; también comprobar {{#if referencesError}}{{#if}} o {{#each}} bloques sin cerrar; agregue la salida de diagnóstico: <pre>hasFields: {{hasFields}} | title: {{properties.title}}</pre>{{! comment }} en lugar de HTML <!-- comment -->{{#if fields.enabled}} siempre es verdadero"false" es verdadera en Handlebars. Solo los datos reales false, null, undefined, 0, "" y [] son falsos.<, & mostrado en lugar de <, &{{{fields.content}}}#each no está definida../ para el ámbito principal: {{{../name}}}; usar ../../ para el ámbito principal{{else}} dentro de {{#each}}: {{#each fields.tags}}...{{else}}<p>No tags</p>{{/each}}Uso de recursos working-with-assets
AEM procesa previamente como HTML los fragmentos de contenido a los que se hace referencia en Assets. Por lo tanto, las llaves triples son obligatorias para todas las referencias de recursos.
<img src="..." alt="..."><video> elemento<a href="..."> vínculoRecuerde:
- Utilice siempre llaves triples para los campos de recursos.
Si utiliza llaves dobles, se omitirá la etiqueta de HTML generada y se mostrará como texto sin procesar en lugar de representar la imagen, el vídeo o el vínculo.
Uso del campo de recursos asset-field-usage
Un ejemplo de uso de campos de recursos:
Ayudantes de plantilla personalizados customer-template-helpers
El sistema proporciona controladores Handlebars personalizados para generar elementos HTML con atributos HTML personalizados. Estos ayudantes le proporcionan control sobre el marcado generado, a la vez que gestionan la complejidad de extraer direcciones URL de origen a partir de contenido procesado previamente.
Ayudantes disponibles:
asset- Genera etiquetas<img>con atributos personalizadostext: genera<span>etiquetas que ajustan el contenido de texto con atributos personalizados
asset asistente asset-helper
Sintaxis:
Recuerde:
- Utilice llaves triples
{{{ }}}con el asistente de recursos, no llaves dobles.
Cuatro ejemplos básicos four-basic-examples
Cuatro ejemplos básicos son:
Atributos admitidos supported-attributes
Puede añadir cualquier atributo de HTML válido:
classclass="my-class another-class"idid="unique-id"altalt="Custom alt text" (overrides existing alt)data-*data-index="1" data-type="hero"aria-*aria-label="Description" aria-hidden="true"widthwidth="300"heightheight="200"loadingloading="lazy"stylestyle="border-radius: 8px;"Omitir texto alternativo override-alt-text
Se puede anular el atributo alt de la imagen original:
Ejemplo complejo complex-example
Un ejemplo complejo es:
Uso de con bucles using-with-loops
Asistente de recursos en bucles:
text asistente text-helper
El asistente de texto genera una etiqueta <span> que ajusta el contenido de texto con clases CSS y atributos HTML personalizados. Útil para aplicar estilo a campos de texto individuales.
Sintaxis:
Recuerde:
- Utilice llaves triples
{{{ }}}con el asistente de texto, no llaves dobles.
Tres ejemplos básicos three-basic-examples
Tres ejemplos básicos son:
Casos de uso comunes common-use-cases
Algunos casos de uso comunes incluyen:
Con bucles with-loops
Un caso de uso común con bucles incluye:
Ayudantes: validación de atributos helpers-attribute-validation
Ambos ayudantes validan los nombres de atributo antes de incluirlos en la salida.
Nombres de atributo válidos:
-
Debe comenzar por una letra (a-z, A-Z)
-
Solo puede contener letras, dígitos, guiones y guiones bajos; consulte las Convenciones de nombres
-
Sin distinción de mayúsculas y minúsculas
-
Por ejemplo:
- Válido:
class,id,data-value,aria-label,my_attr,dataIndex1
- No válido:
123-attr,-class,@special,$money
- Válido:
Los nombres de atributo no válidos se omiten silenciosamente con una advertencia en los registros:
Recuerde:
- Compruebe los registros del servidor para ver las advertencias “Formato de nombre de atributo no válido bloqueado”.
Comparación de la salida directa con los ayudantes comparing-direct-output-to-helpers
Cuándo se debe establecer la salida directa {{{fields.xxx}}}:
- No necesita un estilo personalizado
- Desea el resultado predeterminado tal cual
- El campo contiene HTML complejo que no desea modificar
Cuándo usar los ayudantes:
- Debe añadir clases CSS para el estilo
- Debe agregar atributos personalizados de HTML (
data-*,aria-*y otros) - Desea una estructura de HTML coherente y controlada
Comparación:
Referencia rápida quick-reference
Se proporciona información de referencia rápida como referencia.
Variables de contexto context-variables
Las variables de contexto:
Acceso al campo field-access
Cómo acceder a los campos:
Flujo de control control-flow
Flujo de control:
Variables de bucle loop-variables
Las variables de bucle:
Ayudantes de plantilla personalizados custom-template-helpers
Los ayudantes de plantilla personalizados:
Recursos adicionales additional-resources
Hay recursos adicionales disponibles: