Linee guida per i componenti component-guidelines

I Componenti core seguono modelli di implementazione moderni che sono molto diversi da quelli dei componenti di base.

Questa pagina spiega i modelli e indica quando utilizzarli per creare componenti personalizzati. La prima sezione Modelli generici dei componenti vale per qualsiasi tipo di componente, mentre la seconda sezione Modelli di componenti riutilizzabili vale per i componenti destinati a essere riutilizzati per vari siti o progetti, come, ad esempio, i Componenti core.

Modelli generici dei componenti general-component-patterns

Le linee guida illustrate in questa sezione sono consigliate per qualsiasi tipo di componente, indipendentemente dal fatto che sia specifico per un singolo progetto o debba essere ampiamente riutilizzato per più siti o progetti.

Componenti configurabili configurable-components

I componenti possono avere finestre di dialogo con diverse opzioni. Questa caratteristica dovrebbe essere utilizzata al meglio per rendere i componenti flessibili e configurabili ed evitare di implementare tanti componenti che spesso non sono che varianti l’uno dell’altro.

In genere, se un wireframe o un design contiene varianti di elementi simili, queste varianti non devono essere implementate come componenti diversi, ma come un unico componente con opzioni per la scelta delle varianti.

Per fare un ulteriore passo in avanti, se i componenti vengono riutilizzati per più siti o progetti, vedi la sezione Funzionalità preconfigurabili.

Separazione tra logica e markup separation-of-concerns

In genere, è consigliabile tenere separata la logica (o modello) di un componente dal modello di markup (o vista). Ci sono diversi modi per farlo, tuttavia quello consigliato è utilizzare i modelli Sling per la logica e l’HTML Template Language (HTL) per il markup, come fanno anche i Componenti core.

I modelli Sling sono un set di annotazioni Java per accedere facilmente alle variabili necessarie dai POJO (Plain Old Java Object) e offrono quindi un modo semplice, efficace ed efficiente di implementare la logica Java per i componenti.

L’HTL è stato concepito appositamente come linguaggio di modelli sicuro e semplice per AEM. Può richiamare molte forme di logica e ciò lo rende molto flessibile.

Modelli di componenti riutilizzabili reusable-component-patterns

Anche le linee guida incluse in questa sezione possono essere utilizzate per qualsiasi tipo di componente, tuttavia hanno più senso per i componenti destinati a essere riutilizzati per più siti o progetti, come, ad esempio, i Componenti core. Pertanto, queste linee guida possono essere ignorate per i componenti utilizzati solo su un singolo sito o progetto.

Funzionalità preconfigurabili pre-configurable-capabilities

Oltre alla finestra di dialogo per modifica utilizzata dagli autori di pagine, i componenti possono avere anche una finestra di dialogo per progettazione per consentire agli autori di modelli di preconfigurarli. L’Editor di modelli consente di impostare tutte queste preconfigurazioni, che sono chiamate “Criteri”.

Per rendere i componenti il più possibile riutilizzabili, è necessario fornire loro opzioni significative per la preconfigurazione. Ciò consente di abilitare o disabilitare funzioni dei componenti, in modo che soddisfino le esigenze specifiche dei vari siti.

Modello di componente proxy proxy-component-pattern

Poiché ogni risorsa di contenuto ha una proprietà sling:resourceType che fa riferimento al componente per eseguirne il rendering, in genere è buona prassi che queste proprietà puntino ai componenti specifici del sito, invece di puntare ai componenti condivisi da più siti. Ciò offre maggiore flessibilità ed evita il refactoring del contenuto, nel caso un sito necessiti di un comportamento diverso di un componente, perché questa personalizzazione può quindi essere applicata al componente specifico per il sito e non influisce sugli altri siti.

Tuttavia, affinché i componenti specifici del progetto non debbano duplicare il codice, ciascuno di essi deve fare riferimento al componente principale condiviso con la proprietà sling:resourceSuperType. Questi componenti specifici del progetto, che sono principalmente solo componenti padre, vengono detti “componenti proxy”. I componenti proxy possono essere completamente vuoti, se ereditano interamente la funzionalità, oppure se ne possono ridefinire alcuni aspetti.

Controllo delle versioni dei componenti component-versioning

I componenti devono restare completamente compatibili nel tempo, ma talvolta sono necessarie modifiche che non possono essere mantenute compatibili. Una soluzione che soddisfa queste opposte esigenze consiste nell’introdurre il controllo delle versioni dei componenti, aggiungendo un numero nel loro percorso del tipo di risorsa e nei nomi qualificati delle classi Java per le loro implementazioni. Questo numero rappresenta una versione principale, secondo quanto definito dalle linee guida per il controllo delle versioni semantiche, e viene incrementato solo per modifiche che non sono compatibili con le versioni precedenti.

Le modifiche non compatibili apportate ai seguenti aspetti dei componenti daranno origine a una nuova versione:

Per ulteriori dettagli, vedi il documento Criteri di controllo delle versioni in GitHub.

Il controllo delle versioni dei componenti crea una forma di contratto importante per gli aggiornamenti, in quanto chiarisce quando potrebbe essere necessario il refactoring di un elemento. Vedi anche la sezione Compatibilità delle personalizzazioni in un aggiornamento, che spiega quali considerazioni richiedono le diverse forme di personalizzazione per un aggiornamento.

Per evitare complicate migrazioni di contenuto, è importante non puntare mai direttamente ai componenti con versioni dalle risorse di contenuto. Come regola empirica, una proprietà sling:resourceType del contenuto non deve mai avere un numero di versione, altrimenti l’aggiornamento dei componenti richiederà il refactoring del contenuto. Il modo migliore per evitarlo è seguire il modello di componente proxy descritto sopra.

Interfacce di modello model-interfaces

Questo modello prevede che l’istruzione HTL data-sly-use punti a un’interfaccia Java, mentre anche l’implementazione del modello Sling si registra per il tipo di risorsa del componente.

In combinazione con il modello di componente proxy descritto sopra, questa forma di doppia associazione offre i seguenti validi punti di estensione:

Tutti gli elementi insieme putting-it-all-together

Di seguito è riportata una panoramica dell’intera struttura di associazione dei tipi di risorsa, come, ad esempio, il componente core Titolo. La panoramica illustra come un componente proxy specifico del sito consenta di risolvere il controllo delle versioni dei componenti per evitare che la risorsa di contenuto contenga un numero di versione. Mostra altresì come il file HTL title.html del componente utilizzi l’interfaccia di modello, mentre l’implementazione si associa alla versione specifica del componente tramite le annotazioni del modello Sling.

Di seguito è riportata un’altra panoramica che non mostra i dettagli del POJO (Plain Old Java Object) di implementazione, ma rivela come viene fatto riferimento ai modelli e criteri associati.

La proprietà cq:allowedTemplates indica quali modelli possono essere utilizzati per un sito e la proprietà cq:template indica qual è il modello associato a ciascuna pagina. Ogni modello consta di tre parti:

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 componenti HTL personalizzati con i modelli Sling per la logica e la corretta implementazione dei Componenti core con il modello proxy consigliato.

Articolo successivo: