Personalizzazione dei Componenti core customizing-core-components

I Componenti core implementano diversi modelli che consentono una facile personalizzazione, dalla semplice assegnazione di uno stile al riutilizzo di funzionalità avanzate.

Architettura flessibile flexible-architecture

I Componenti core sono stati concepiti per essere flessibili ed estensibili. Una panoramica della loro architettura rivela dove è possibile effettuare personalizzazioni.

Tutti i Componenti core implementano il Sistema di stili.

Archetipo progetto AEM aem-project-archetype

L’Archetipo progetto AEM crea un progetto Adobe Experience Manager minimo come punto di partenza per i tuoi progetti, incluso un esempio di componente HTL personalizzato con i modelli Sling per la logica e la corretta implementazione dei Componenti core con il modello proxy consigliato.

Modelli di personalizzazione customization-patterns

Personalizzazione delle finestre di dialogo customizing-dialogs

Potrebbe risultare conveniente personalizzare le opzioni di configurazione disponibili nella finestra di dialogo di un Componente core, che si tratti della finestra di dialogo per progettazione o della finestra di dialogo per modifica.

Ogni finestra di dialogo ha una struttura di nodi coerente. Si consiglia di replicare questa struttura in un componente ereditante, in modo che le opzioni Sling Resource Merger e Nascondi condizioni possano essere utilizzate per nascondere, sostituire o riordinare le sezioni della finestra di dialogo originale. La struttura da replicare è definita fino al livello del nodo dell’elemento Scheda.

Per essere pienamente compatibile con qualsiasi modifica apportata a una finestra di dialogo nella sua versione corrente, è molto importante che le strutture al di sotto del livello dell’elemento Scheda non vengano toccate (nascoste, aggiunte, sostituite, riordinate, ecc.). Al contrario, un elemento Scheda derivato dall’elemento padre deve essere nascosto tramite la proprietà sling:hideResource (vedi Proprietà di Sling Resource Merger) e devono essere aggiunti nuovi elementi Scheda contenenti i campi di configurazione personalizzati. La proprietà sling:orderBefore può essere utilizzata per riordinare gli elementi Scheda, se necessario.

La finestra di dialogo che segue illustra la struttura consigliata e come nascondere e sostituire una scheda ereditata come descritto in precedenza:

<?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"/>
                        <myTab
                               jcr:primaryType="nt:unstructured"
                               jcr:title="My Tab"
                               sling:resourceType="granite/ui/components/coral/foundation/container">

                               <!-- myTab content -->

                        </myTab>
                </items>
            </tabs>
        </items>
    </content>
</jcr:root>

Personalizzazione della logica di un Componente core customizing-the-logic-of-a-core-component

La logica di business dei Componenti core è implementata nei modelli Sling. Questa logica può essere estesa utilizzando un modello di delega Sling.

Ad esempio, il componente core Titolo utilizza la proprietà jcr:title della risorsa richiesta per fornire il testo del titolo. Se la proprietà jcr:title non è definita, viene effettuato un regresso al titolo della pagina corrente. Noi vogliamo modificare questo comportamento, in modo che il titolo della pagina corrente sia sempre visualizzato.

Poiché l’implementazione dei modelli dei Componenti core è privata, è necessario estenderla con un modello di delega.

@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();
    }
}

Per ulteriori dettagli sul modello di delega, vedi l’articolo Wiki sui Componenti core Modello di delega per modelli Sling in GitHub.

Personalizzazione del markup customizing-the-markup

A volte gli stili avanzati richiedono una diversa struttura di markup del componente.

Ciò può essere fatto facilmente copiando i file HTL che devono essere modificati dal Componente core al componente proxy.

Riprendendo l’esempio del componente core Breadcrumb, core, per personalizzare l’output di markup, il file breadcrumb.html deve essere copiato nel componente specifico del sito che ha la proprietà sling:resourceSuperTypes che punta al componente core Breadcrumb.

Definizione degli stili dei componenti styling-the-components

La prima forma di personalizzazione consiste nell’applicare gli stili CSS.

Per semplificare questa operazione, i Componenti core forniscono un markup semantico e seguono una convenzione di denominazione standard ispirata a Bootstrap. Inoltre, per individuare e denominare gli stili dei singoli componenti, ciascun Componente core è racchiuso in un elemento DIV con le classi “cmp” e “cmp-<name>”.

Ad esempio, osservando il file HTL del componente core Breadcrumb v1: breadcrumb.html, notiamo che la gerarchia degli dell’output degli elementi è ol.breadcrumb > li.breadcrumb-item > a. Quindi, per fare in modo che una regola CSS influisca solo sulla classe di breadcrumb di quel componente, tutte le regole devono denominate come indicato di seguito:

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

Inoltre, ciascuno dei Componenti core utilizza la funzionalità Sistema di stili di AEM che consente agli autori di modelli di definire nomi di classi CSS aggiuntivi che possono essere applicati al componente dagli autori delle pagine. Ciò consente di definire per ogni modello un elenco di stili di consentiti e se uno di questi deve essere applicato per impostazione predefinita a tutti i componenti di quel tipo.

Compatibilità degli aggiornamenti delle personalizzazioni upgrade-compatibility-of-customizations

Sono possibili tre diversi tipi di aggiornamento:

In genere, l’aggiornamento di AEM a una nuova versione non influisce sui Componenti core o sulle personalizzazioni eseguite, purché le versioni dei componenti supportino anche la nuova versione di AEM a cui viene effettuata la migrazione e le personalizzazioni non utilizzino API che sono state dichiarate obsolete oppure rimosse.

L’aggiornamento dei Componenti core senza passare a una versione principale più recente non dovrebbe influire sulle personalizzazioni, purché vengano utilizzati i modelli di personalizzazione descritti in questa pagina.

Il passaggio a una versione principale più recente dei Componenti core è compatibile solo per la struttura del contenuto, ma potrebbe essere necessario eseguire il refactoring delle personalizzazioni. Per ogni versione di un componente verranno pubblicati registri di modifica chiari per evidenziare le modifiche che avrebbero un impatto sul tipo di personalizzazioni descritte in questa pagina.

Supporto delle personalizzazioni support-of-customizations

Come per qualsiasi componente AEM, occorre essere consapevoli di alcune situazioni concernenti le personalizzazioni:

Vedi anche la sezione Supporto dei componenti core.

Articolo successivo: