Personalización de componentes principales

Los Componentes principales implementan varios patrones que facilitan la personalización, desde el estilo simple hasta la reutilización avanzada de la funcionalidad.

Arquitectura flexible

Los componentes principales se diseñaron desde el principio para que fueran flexibles y ampliables. Un vistazo a una descripción general de su arquitectura revela dónde se pueden realizar las personalizaciones.

Arquitectura de componentes principales

  • El cuadro de diálogo de diseño define qué pueden hacer o no los autores en el cuadro de diálogo de edición.
  • El cuadro de diálogo de edición muestra a los autores solo las opciones que pueden utilizar.
  • El modelo Sling verifica y prepara el contenido para la vista (plantilla).
  • El resultado del modelo Sling se puede serializar en JSON para casos de uso SPA.
  • HTL procesa el HTMLserver-side para el procesamiento tradicional en el servidor.
  • El HTML resulta semántico, accesible, optimizado para motores de búsqueda y fácil de diseñar.

Y todos los componentes principales implementan el Sistema de estilos.

Tipo de archivo del proyecto AEM

El archivo del proyecto AEM procesa un proyecto mínimo de Adobe Experience Manager como punto de partida para sus propios proyectos, incluido un ejemplo de componente HTL personalizado con modelos Sling para la lógica y la correcta implementación de los componentes principales con el patrón de proxy recomendado.

Patrones de personalización

Personalización de cuadros de diálogo

Puede que desee personalizar las opciones de configuración disponibles en un cuadro de diálogo de componentes principales, ya sea el Diálogo de diseño o el Cuadro de diálogo de edición.

Cada cuadro de diálogo tiene una estructura de nodos coherente. Se recomienda que esta estructura se duplique en un componente heredado para que fusión de recursos de Sling y ocultar condiciones se puedan usar para ocultar, reemplazar o reordenar secciones del cuadro de diálogo original. La estructura que se va a replicar se define como cualquier elemento hasta el nivel de nodo de elemento de pestaña.

Para ser totalmente compatible con los cambios realizados en un cuadro de diálogo en su versión actual, es muy importante que las estructuras debajo del nivel de elemento de pestaña no se toquen (oculto, agregado, sustituido, reordenado, etc.). En su lugar, se debe ocultar un elemento de ficha del elemento principal mediante la propiedad sling:hideResource (consulte Sling Resource Merger Properties) y se deben agregar nuevos elementos de pestaña que contengan los campos de configuración personalizados. sling:orderBefore se puede utilizar para reordenar los elementos de la ficha si es necesario.

El cuadro de diálogo siguiente muestra la estructura de diálogo recomendada, así como cómo ocultar y reemplazar una ficha heredada, tal como se describe anteriormente:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0"
          xmlns:jcr="https://www.jcp.org/jcr/1.0"
          xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
          xmlns:granite="https://www.adobe.com/jcr/granite/1.0"
          jcr:primaryType="nt:unstructured">
    <content jcr:primaryType="nt:unstructured">
        <items jcr:primaryType="nt:unstructured">
            <tabs jcr:primaryType="nt:unstructured">
                <items jcr:primaryType="nt:unstructured">
                        <originalTab
                                jcr:primaryType="nt:unstructured"
                                sling:hideResource="true"/>
                        </originalTab>
                        <myTab
                               jcr:primaryType="nt:unstructured"
                               jcr:title="My Tab"
                               sling:resourceType="granite/ui/components/coral/foundation/container"/>
                               <!-- myTab content -->
                        </myTab>
                </items>
            </basic>
        </items>
    </content>
</jcr:root>

Personalización de la lógica de un componente principal

La lógica empresarial de los componentes principales se implementa en los modelos Sling. Esta lógica se puede ampliar utilizando un patrón de delegación de Sling.

Por ejemplo, el componente principal del título utiliza la propiedad jcr:title del recurso solicitado para proporcionar el texto del título. Si no se define ninguna propiedad jcr:title , se implementa una alternativa al título de la página actual. Queremos cambiar el comportamiento para que el título de la página actual se muestre siempre.

Dado que la implementación de los modelos de los componentes principales es privada, deben ampliarse con un patrón de delegación.

@Model(adaptables = SlingHttpServletRequest.class,
       adapters = Title.class,
       resourceType = "myproject/components/pageHeadline")
public class PageHeadline implements Title {
    @ScriptVariable private Page currentPage;
    @Self @Via(type = ResourceSuperType.class)
    private Title title;
    @Override public String getText() {
        return currentPage.getTitle();
    }
    @Override public String getType() {
        return title.getType();
    }
}

Para obtener más información sobre el patrón de delegación, consulte el artículo de la wiki de los componentes principales de GitHub Patrón de delegación para modelos Sling.

Personalización del marcado

A veces, el estilo avanzado requiere una estructura de marcado diferente del componente.

Esto se puede hacer fácilmente copiando los archivos HTL que necesitan modificarse del componente principal al componente proxy .

Siguiendo de nuevo el ejemplo del componente de ruta de exploración principal, para personalizar su salida de marcado, el archivo breadcrumb.html tendría que copiarse en el componente específico del sitio que tiene un sling:resourceSuperTypes que apunta al componente de ruta de exploración principal.

Diseño de los componentes

La primera forma de personalización es aplicar estilos CSS.

Para facilitar esto, los componentes principales procesan el marcado semántico y siguen una convención de nombres estandarizada inspirada en Bootstrap. Además, para establecer fácilmente como objetivo y espacio de nombres los estilos para los componentes individuales, cada componente principal se envuelve en un elemento DIV con las clases " cmp" y " cmp-<name>".

Por ejemplo, observe el archivo HTL del componente de ruta de exploración principal v1: ruta de exploración.html, vemos que la salida de la jerarquía de elementos es ol.breadcrumb > li.breadcrumb-item > a. Por lo tanto, para asegurarse de que una regla CSS solo afecta a la clase de ruta de exploración de ese componente, todas las reglas deben tener un espacio de nombres como se muestra a continuación:

.cmp-breadcrumb .breadcrumb {}  
.cmp-breadcrumb .breadcrumb-item {}  
.cmp-breadcrumb a {}

Además, cada uno de los componentes principales aprovecha la función AEM Sistema de estilos que permite a los autores de plantillas definir nombres de clase CSS adicionales que los autores de la página pueden aplicar al componente. Esto permite definir para cada plantilla una lista de estilos de componente permitidos y si uno de ellos debe aplicarse de forma predeterminada a todos los componentes de ese tipo.

Compatibilidad de actualización de las personalizaciones

Se pueden realizar tres tipos diferentes de actualizaciones:

  • actualización de la versión de AEM
  • actualización de los componentes principales a una nueva versión secundaria
  • actualización de los componentes principales a una versión principal

Por lo general, actualizar AEM a una nueva versión no afectará a los componentes principales ni a las personalizaciones realizadas, siempre que las versiones de los componentes también admitan la nueva versión de AEM a la que se está migrando y que las personalizaciones no utilicen API que hayan sido obsoletas o eliminadas.

La actualización de los componentes principales sin cambiar a una versión principal más reciente no debería afectar a las personalizaciones, siempre y cuando se utilicen los patrones de personalización descritos en esta página.

El cambio a una versión principal más reciente de los componentes principales solo es compatible con la estructura de contenido, pero es posible que sea necesario refactorizar las personalizaciones. Se publicarán registros de cambios claros para cada versión del componente a fin de resaltar los cambios que podrían afectar al tipo de personalizaciones descritas en esta página.

Compatibilidad con personalizaciones

Al igual que para cualquier componente AEM, hay que tener en cuenta varias cosas sobre las personalizaciones:

  1. Nunca modifique directamente el código de los componentes principales.

    De este modo, no se admitirían por completo y las futuras actualizaciones de los componentes se convertirían en un proceso doloroso. En su lugar, utilice los métodos de personalización descritos en esta página.

  2. El código personalizado es su propia responsabilidad.

    Nuestro programa de asistencia no cubre el código personalizado y los problemas notificados que no se pueden reproducir con los componentes principales de vainilla que se usan como documentados no se califican.

  3. Vea las funciones en desuso y eliminadas.

    Con cada versión de AEM nueva a la que se actualiza, asegúrese de que todas las API utilizadas sigan estando actualizadas, teniendo en cuenta la página Funciones obsoletas y eliminadas.

Consulte también la sección Compatibilidad con componentes principales.

Consulte lo siguiente:

En esta página