Personalizar y ampliar fragmentos de contenido

Un fragmento de contenido extiende un recurso estándar; consulte:

• Creación y administración de fragmentos de contenido y creación de páginas con fragmentos de contenido para obtener más información sobre los fragmentos de contenido.

• Administración de recursos y personalización y ampliación de recursos para obtener más información sobre los recursos estándar.

Arquitectura

Las partes constituyentes básicas de un fragmento de contenido son:

• Un fragmento de contenido,
• consistente en uno o más Elemento de contenido s,
• y que pueden tener una o más Variación de contenido s.

Según el tipo de fragmento, también se utilizan modelos o plantillas:

• Modelos de fragmento de contenido:

  • Se utiliza para definir fragmentos de contenido que contienen contenido estructurado.
  • Los modelos de fragmento de contenido definen la estructura de un fragmento de contenido al crearlo.
  • Un fragmento hace referencia al modelo; por lo tanto, los cambios en el modelo pueden/afectarán a cualquier fragmento dependiente.
  • Los modelos están compuestos por tipos de datos.
  • Las funciones para agregar nuevas variaciones, etc., deben actualizar el fragmento según corresponda.
  PRECAUCIÓN

  Cualquier cambio en un modelo de fragmento de contenido existente puede afectar a los fragmentos dependientes; esto puede llevar a propiedades huérfanas en esos fragmentos.

• Plantillas de fragmento de contenido:

  • Se utiliza para definir fragmentos de contenido sencillos.
  • Las plantillas definen la estructura (básica, de solo texto) de un fragmento de contenido cuando se crea.
  • La plantilla se copia en el fragmento cuando se crea; por lo tanto, los cambios adicionales en la plantilla no se reflejarán en los fragmentos existentes.
  • Las funciones para agregar nuevas variaciones, etc., deben actualizar el fragmento según corresponda.
  • Las plantillas de fragmento de contenido funcionan de una manera diferente a la de otros mecanismos de plantilla dentro del ecosistema de AEM (por ejemplo, plantillas de página, etc.). Por lo tanto, deben considerarse por separado.
  • Cuando se basa en una plantilla, el tipo MIME del contenido se administra en el contenido real; esto significa que cada elemento y variación puede tener un tipo MIME diferente.

Integración con Assets

Content Fragment Management (CFM) es parte de AEM Assets como:

• Los fragmentos de contenido son recursos.
• Utilizan la funcionalidad de Recursos existente.
• Están totalmente integrados con Recursos (consolas de administración, etc.).

Asignación de fragmentos de contenido estructurado a recursos

Los fragmentos de contenido con contenido estructurado (es decir, basados en un modelo de fragmento de contenido) se asignan a un solo recurso:

• Todo el contenido se almacena en el nodo jcr:content/data del recurso:

  • Los datos del elemento se almacenan en el subnodo maestro:

    jcr:content/data/master

  • Las variaciones se almacenan bajo un subnodo que lleva el nombre de la variación:
    p. ej. jcr:content/data/myvariation

  • Los datos de cada elemento se almacenan en el subnodo correspondiente como una propiedad con el nombre del elemento:
    Por ejemplo: el contenido del elemento text se almacena como propiedad text en jcr:content/data/master

• Los metadatos y el contenido asociado se almacenan por debajo de jcr:content/metadata
  Excepto el título y la descripción, que no se consideran metadatos tradicionales y se almacenan en
  jcr:content

Asignación de fragmentos de contenido simple a recursos

Los fragmentos de contenido simple (basados en una plantilla) se asignan a una composición compuesta por un recurso principal y subrecursos (opcionales):

• Toda la información que no sea de contenido de un fragmento (como título, descripción, metadatos, estructura) se administra exclusivamente en el recurso principal.

• El contenido del primer elemento de un fragmento se asigna a la representación original del recurso principal.

  • Las variaciones (si las hay) del primer elemento se asignan a otras representaciones del recurso principal.

• Los elementos adicionales (si existen) se asignan a subrecursos del recurso principal.

  • El contenido principal de estos elementos adicionales se asigna a la representación original del subactivo correspondiente.
  • Otras variaciones (si procede) de cualquier elemento adicional se relacionan con otras representaciones del subactivo correspondiente.

Ubicación del recurso

Al igual que con los recursos estándar, un fragmento de contenido se incluye en:

/content/dam

Permisos de recursos

Para obtener más información, consulte Fragmento de contenido - Eliminar consideraciones.

Integración de funciones

• La función Administración de fragmentos de contenido (CFM) se basa en el núcleo de recursos, pero debe ser lo más independiente posible.
• CFM proporciona sus propias implementaciones para los elementos de las vistas de tarjeta/columna/lista; estos complementos se conectan a las implementaciones de representación de contenido de Recursos existentes.
• Se han ampliado varios componentes de Recursos para incluir fragmentos de contenido.

Uso de fragmentos de contenido en páginas

Se puede hacer referencia a los fragmentos de contenido desde AEM páginas, al igual que a cualquier otro tipo de recurso. AEM proporciona el componente principal Fragmento de contenido, un componente que permite incluir fragmentos de contenido en las páginas. También puede ampliar este componente principal Fragmento de contenido.

• El componente utiliza la propiedad fragmentPath para hacer referencia al fragmento de contenido real. La propiedad fragmentPath se administra de la misma manera que otras propiedades similares de otros tipos de recursos; por ejemplo, cuando el fragmento de contenido se mueve a otra ubicación.

• El componente permite seleccionar la variación que se va a mostrar.

• Además, se puede seleccionar un rango de párrafos para restringir el resultado; por ejemplo, esto se puede utilizar para la salida de varias columnas.

• El componente permite contenido intermedio:

  • Aquí el componente permite colocar otros recursos (imágenes, etc.) entre los párrafos del fragmento al que se hace referencia.

  • Para el contenido intermedio debe:

    • ser conscientes de la posibilidad de referencias inestables; el contenido intermedio (agregado al crear una página) no tiene una relación fija con el párrafo al que está situado, insertando un nuevo párrafo (en el editor de fragmentos de contenido) antes de que la posición del contenido intermedio pueda perder la posición relativa
    • considere los parámetros adicionales (como los filtros de variante y párrafo) para evitar falsos positivos en los resultados de búsqueda

Configuración mediante la consola OSGi

La implementación back-end de fragmentos de contenido es, por ejemplo, responsable de hacer que las instancias de un fragmento se utilicen en una página en la que se pueda buscar o de administrar el contenido de medios mixtos. Esta implementación necesita saber qué componentes se utilizan para procesar fragmentos y cómo se parametriza el procesamiento.

Los parámetros para esto se pueden configurar en la Consola Web, para el paquete OSGi Configuración del componente de fragmento de contenido.

• Tipos
  de recursoslista de
  sling:resourceTypes se puede proporcionar para definir los componentes que se utilizan para procesar fragmentos de contenido y a los que se debe aplicar el procesamiento en segundo plano.

• Propiedades de
  referenciaSe puede configurar una lista de propiedades para especificar dónde se almacena la referencia al fragmento para el componente correspondiente.

Aún hay algunas directrices que debe seguir para garantizar que el componente sea compatible con el procesamiento en segundo plano del fragmento de contenido:

• El nombre de la propiedad donde se definen los elementos que se van a procesar debe ser element o elementNames.

• El nombre de la propiedad donde se define la variación que se va a representar debe ser variation o variationName.

• Si se admite la salida de varios elementos (mediante elementNames para especificar varios elementos), el modo de visualización real se define con la propiedad displayMode:

  • Si el valor es singleText (y sólo hay un elemento configurado), el elemento se representa como texto con contenido intermedio, compatibilidad con el diseño, etc. Es el valor predeterminado para los fragmentos en los que solo se procesa un solo elemento.
  • De lo contrario, se utiliza un enfoque mucho más sencillo (podría denominarse "vista de formulario"), en el que no se admite contenido intermedio y el contenido del fragmento se representa "tal cual".

• Si el fragmento se procesa para displayMode == singleText (implícita o explícitamente), entran en juego las siguientes propiedades adicionales:

  • paragraphScope define si se deben representar todos los párrafos, o solo un rango de párrafos (valores: all vs. range)

  • si paragraphScope == range la propiedad paragraphRange define el rango de párrafos que se van a procesar

Integración con otros marcos

Los fragmentos de contenido se pueden integrar con:

• Traducciones

  Los fragmentos de contenido están completamente integrados con el flujo de trabajo de traducción de AEM. A nivel arquitectónico, esto significa:

  • Las traducciones individuales de un fragmento de contenido son en realidad fragmentos independientes; por ejemplo:

    • están situadas bajo diferentes raíces lingüísticas:

      /content/dam/<path>/en/<to>/<fragment>

      vs.

      /content/dam/<path>/de/<to>/<fragment>

    • pero comparten exactamente la misma ruta relativa debajo de la raíz del idioma:

      /content/dam/<path>/en/<to>/<fragment>

      vs.

      /content/dam/<path>/de/<to>/<fragment>

  • Además de las rutas basadas en reglas, no hay más conexión entre las distintas versiones de idioma de un fragmento de contenido; se gestionan como dos fragmentos independientes, aunque la interfaz de usuario proporciona los medios para desplazarse entre las variantes de idioma.

  NOTA

  El flujo de trabajo de traducción AEM funciona con /content:

  • Dado que los modelos de fragmentos de contenido residen en /conf, no se incluyen en dichas traducciones. Puede internacionalizar las cadenas de IU.

  • Las plantillas se copian para crear el fragmento de modo que quede implícito.

• Esquemas de metadatos

  • Los fragmentos de contenido (re)utilizan los esquemas de metadatos, que se pueden definir con recursos estándar.

  • CFM ofrece su propio esquema específico:

    /libs/dam/content/schemaeditors/forms/contentfragment

    esto se puede ampliar si es necesario.

  • El formulario de esquema correspondiente se integra con el editor de fragmentos.

La Content Fragment Management API - Server-Side

Puede utilizar la API del lado del servidor para acceder a los fragmentos de contenido; consulte:

com.adobe.cq.dam.cfm

Interfaces clave

Las tres interfaces siguientes pueden servir como puntos de entrada:

• Plantilla de fragmento(FragmentTemplate)

  Utilice FragmentTemplate.createFragment() para crear un nuevo fragmento.

  Resource templateOrModelRsc = resourceResolver.getResource("...");
  FragmentTemplate tpl = templateOrModelRsc.adaptTo(FragmentTemplate.class);
  ContentFragment newFragment = tpl.createFragment(parentRsc, "A fragment name", "A fragment description.");
  

  Esta interfaz representa:

  • un modelo de fragmento de contenido o una plantilla de fragmento de contenido desde la cual crear un fragmento de contenido,
  • y (después de la creación) la información estructural de dicho fragmento

  Esta información puede incluir:

  • Acceso a datos básicos (título, descripción)

  • Obtenga acceso a plantillas y modelos para los elementos del fragmento:

    • Plantillas de elementos de lista
    • Obtener información estructural para un elemento determinado
    • Acceder a la plantilla de elementos (consulte ElementTemplate)

  • Acceder a plantillas para las variaciones del fragmento:

    • Plantillas de variación de lista
    • Obtener información estructural para una variación determinada
    • Acceder a la plantilla de variación (consulte VariationTemplate)

  • Obtener contenido asociado inicial

  Interfaces que representan información importante:

  • ElementTemplate

    • Obtener datos básicos (nombre, título)
    • Obtener contenido inicial del elemento

  • VariationTemplate

    • Obtener datos básicos (nombre, título, descripción)

• Fragmento de contenido(ContentFragment)

  Esta interfaz le permite trabajar con un fragmento de contenido de forma abstracta.

  PRECAUCIÓN

  Se recomienda enfáticamente acceder a un fragmento a través de esta interfaz. Se debe evitar cambiar directamente la estructura de contenido.

  La interfaz le proporciona los medios para:

  • Administrar datos básicos (por ejemplo, obtener nombre; get/set title/description)

  • Acceso a metadatos

  • Elementos de acceso:

    • Elementos de lista

    • Obtener elementos por nombre

    • Crear nuevos elementos (consulte Advertencias)

    • Acceso a datos de elementos (consulte ContentElement)

  • Variaciones de lista definidas para el fragmento

  • Crear nuevas variaciones globalmente

  • Administrar contenido asociado:

    • Colecciones de lista
    • Añadir colecciones
    • Eliminar colecciones

  • Acceso al modelo o plantilla del fragmento

  Las interfaces que representan los elementos principales de un fragmento son:

  • Elemento de contenido(ContentElement)

    • Obtener datos básicos (nombre, título, descripción)

    • Obtener o definir contenido

    • Variaciones de acceso de un elemento:

      • Variaciones de lista
      • Obtener variaciones por nombre
      • Crear nuevas variaciones (consulte Advertencias)
      • Quitar variaciones (consulte Advertencias)
      • Acceso a datos de variación (consulte ContentVariation)

    • Método abreviado para resolver variaciones (aplicando alguna lógica adicional de reserva específica para la implementación si la variación especificada no está disponible para un elemento)

  • Variación de contenido(ContentVariation)

    • Obtener datos básicos (nombre, título, descripción)
    • Obtener o definir contenido
    • Sincronización simple, basada en la información modificada por última vez

  Las tres interfaces ( ContentFragment, ContentElement, ContentVariation) extienden la interfaz Versionable, que agrega capacidades de versiones, requeridas para los fragmentos de contenido:

  • Crear nueva versión del elemento
  • Versiones de lista del elemento
  • Obtener el contenido de una versión específica del elemento con versiones

Adaptación: Uso de adaptabilidad()

Se pueden adaptar los siguientes elementos:

• ContentFragment puede adaptarse a:

  • Resource - el recurso Sling subyacente; tenga en cuenta que la actualización del subyacente Resource directamente requiere la reconstrucción del ContentFragment objeto.

  • Asset - la Asset abstracción DAM que representa el fragmento de contenido; tenga en cuenta que la actualización Asset directa requiere la reconstrucción del ContentFragment objeto.

• ContentElement puede adaptarse a:

  • ElementTemplate - para acceder a la información estructural del elemento.

• FragmentTemplate puede adaptarse a:

  • Resource - Resource determinar el modelo al que se hace referencia o la plantilla original copiada;

    • los cambios realizados a través del Resource no se reflejan automáticamente en el FragmentTemplate.

• Resource puede adaptarse a:

  • ContentFragment
  • FragmentTemplate

Advertencias

Cabe señalar que:

• La API se implementa para proporcionar funcionalidad admitida por la interfaz de usuario.

• Toda la API está diseñada para no persistir cambios automáticamente (a menos que se indique lo contrario en el JavaDoc de API). Por lo tanto, siempre tendrá que transferir la resolución de recursos de la solicitud correspondiente (o la resolución que esté utilizando).

• Tareas que podrían requerir un esfuerzo adicional:

  • La creación o eliminación de nuevos elementos no actualizará la estructura de datos de fragmentos simples (basados en una plantilla de fragmento).

  • La creación de nuevas variaciones desde ContentElement no actualizará la estructura de datos (pero crearlas globalmente desde ContentFragment sí lo hará).

  • La eliminación de las variaciones existentes no actualizará la estructura de datos.

Content Fragment Management API - Cliente

Información adicional

Consulte lo siguiente:

• filter.xml

  El filter.xml para la administración de fragmentos de contenido está configurado para que no se superponga con el paquete de contenido principal de Recursos.

Editar sesiones

Una sesión de edición se inicia cuando el usuario abre un fragmento de contenido en una de las páginas del editor. La sesión de edición finaliza cuando el usuario abandona el editor seleccionando Guardar o Cancelar.

Requisitos

Los requisitos para controlar una sesión de edición son:

• Editar un fragmento de contenido, que puede abarcar varias vistas (= páginas HTML), debe ser atómico.
• La edición también debe ser transaccional; al final de la sesión de edición, los cambios se deben confirmar (guardar) o revertir (cancelar).
• Los casos perimetrales deben gestionarse correctamente; estas situaciones incluyen situaciones como cuando el usuario abandona la página introduciendo una dirección URL manualmente o utilizando la navegación global.
• Debe estar disponible un guardado automático periódico (cada x minutos) para evitar la pérdida de datos.
• Si dos usuarios editan un fragmento de contenido al mismo tiempo, no deben sobrescribir los cambios de los demás.

Procesos

Los procesos involucrados son:

• Inicio de una sesión

  • Se crea una nueva versión del fragmento de contenido.
  • Se ha iniciado el guardado automático.
  • Se configuran las cookies; definen el fragmento que se está editando y que hay una sesión de edición abierta.

• Finalización de una sesión

  • Se ha detenido el guardado automático.

  • Al confirmar:

    • Se actualiza la última información modificada.
    • Las cookies se eliminan.

  • Al revertir:

    • Se restaura la versión del fragmento de contenido que se creó al iniciar la sesión de edición.
    • Las cookies se eliminan.

• Edición

  • Todos los cambios (guardado automático incluido) se realizan en el fragmento de contenido activo, no en un área separada y protegida.
  • Por lo tanto, esos cambios se reflejan inmediatamente en AEM páginas que hacen referencia al fragmento de contenido correspondiente

Acciones

Las acciones posibles son:

• Introducción de una página

  • Compruebe si ya hay una sesión de edición; comprobando la cookie correspondiente.

    • Si existe una, compruebe que la sesión de edición se inició para el fragmento de contenido que se está editando actualmente

      • Si el fragmento actual, vuelva a establecer la sesión.
      • Si no es así, intente cancelar la edición del fragmento de contenido editado anteriormente y eliminar las cookies (no habrá ninguna sesión de edición posterior).

    • Si no existe ninguna sesión de edición, espere a que el usuario realice el primer cambio (véase más abajo).

  • Compruebe si ya se hace referencia al fragmento de contenido en una página y, en caso afirmativo, muestre la información adecuada.

• Cambio de contenido

  • Siempre que el usuario cambia de contenido y no hay una sesión de edición presente, se crea una nueva sesión de edición (consulte Inicio de una sesión).

• Salida de una página

  • Si hay una sesión de edición presente y los cambios no se han mantenido, se muestra un cuadro de diálogo de confirmación modal para notificar al usuario la pérdida potencial de contenido y permitirle permanecer en la página.

Ejemplos

Ejemplo: Acceso a un fragmento de contenido existente

Para conseguirlo, puede adaptar el recurso que representa la API a:

com.adobe.cq.dam.cfm.ContentFragment

Por ejemplo:

// first, get the resource
Resource fragmentResource = resourceResolver.getResource("/content/dam/fragments/my-fragment");
// then adapt it
if (fragmentResource != null) {
    ContentFragment fragment = fragmentResource.adaptTo(ContentFragment.class);
    // the resource is now accessible through the API
}

Ejemplo: Creación de un nuevo fragmento de contenido

Para crear un nuevo fragmento de contenido mediante programación, debe utilizar:

com.adobe.cq.dam.cfm.ContentFragmentManager#create

Por ejemplo:

Resource templateOrModelRsc = resourceResolver.getResource("...");
FragmentTemplate tpl = templateOrModelRsc.adaptTo(FragmentTemplate.class);
ContentFragment newFragment = tpl.createFragment(parentRsc, "A fragment name", "A fragment description.");

Ejemplo: Especificación del intervalo de guardado automático

El intervalo de guardado automático (medido en segundos) se puede definir con el administrador de configuración (ConfMgr):

• Nodo: <*conf-root*>/settings/dam/cfm/jcr:content

• Nombre de propiedad: autoSaveInterval

• Tipo: Long

• Predeterminado: 600 (10 minutos); esto se define en /libs/settings/dam/cfm/jcr:content

Si desea establecer un intervalo de guardado automático de 5 minutos, debe definir la propiedad en el nodo; por ejemplo:

• Nodo: /conf/global/settings/dam/cfm/jcr:content

• Nombre de propiedad: autoSaveInterval

• Tipo: Long

• Valor: 300 (5 minutos equivale a 300 segundos)

Plantillas de fragmento de contenido

Consulte Plantillas de fragmento de contenido para obtener información completa.

Componentes para la creación de páginas

Para obtener más información, consulte

• Componentes principales - Componente de fragmento de contenido (recomendado)
• Componentes de fragmento de contenido: Componentes para la creación de páginas