Scopri come creare un componente personalizzato da utilizzare con l’editor SPA AEM. Scopri come sviluppare le finestre di dialogo degli autori e i modelli Sling per estendere il modello JSON a un componente personalizzato.
I capitoli precedenti erano incentrati sullo sviluppo di componenti SPA e sulla loro mappatura su componenti core esistenti AEM. Questo capitolo si concentrerà su come creare ed estendere nuovi componenti AEM e manipolare il modello JSON gestito da AEM.
Un semplice Custom Component
illustra i passaggi necessari per creare un nuovo componente AEM.
Rivedi gli strumenti e le istruzioni necessari per configurare un ambiente di sviluppo locale.
Scarica il punto di partenza per questa esercitazione tramite Git:
$ git clone git@github.com:adobe/aem-guides-wknd-spa.git
$ cd aem-guides-wknd-spa
$ git checkout Angular/custom-component-start
Distribuisci la base di codice in un'istanza AEM locale utilizzando Maven:
$ mvn clean install -PautoInstallSinglePackage
Se utilizzi AEM 6.x aggiungi il profilo classic
:
$ mvn clean install -PautoInstallSinglePackage -Pclassic
Installa il pacchetto finito per il tradizionale sito di riferimento WKND. Le immagini fornite dal sito di riferimento WKND verranno riutilizzate nel SPA WKND. Il pacchetto può essere installato utilizzando Gestione pacchetti AEM.
Puoi sempre visualizzare il codice finito su GitHub o estrarre il codice localmente passando al ramo Angular/custom-component-solution
.
Un componente AEM è definito come un nodo e proprietà. Nel progetto questi nodi e proprietà sono rappresentati come file XML nel modulo ui.apps
. Quindi, crea il componente AEM nel modulo ui.apps
.
È utile un aggiornamento rapido sulle nozioni di base dei componenti AEM.
Nell’IDE che preferisci, apri la cartella ui.apps
.
Passa a ui.apps/src/main/content/jcr_root/apps/wknd-spa-angular/components
e crea una nuova cartella denominata custom-component
.
Crea un nuovo file denominato .content.xml
sotto la cartella custom-component
. Popolare il custom-component/.content.xml
con quanto segue:
<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
jcr:primaryType="cq:Component"
jcr:title="Custom Component"
componentGroup="WKND SPA Angular - Content"/>
jcr:primaryType="cq:Component"
- identifica che questo nodo sarà un componente AEM.
jcr:title
è il valore che verrà visualizzato agli autori di contenuti e componentGroup
determina il raggruppamento di componenti nell’interfaccia utente di authoring.
Sotto la cartella custom-component
, crea un’altra cartella denominata _cq_dialog
.
Sotto la cartella _cq_dialog
crea un nuovo file denominato .content.xml
e popolalo con i seguenti elementi:
<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:granite="http://www.adobe.com/jcr/granite/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
jcr:primaryType="nt:unstructured"
jcr:title="Custom Component"
sling:resourceType="cq/gui/components/authoring/dialog">
<content
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/container">
<items jcr:primaryType="nt:unstructured">
<tabs
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/tabs"
maximized="{Boolean}true">
<items jcr:primaryType="nt:unstructured">
<properties
jcr:primaryType="nt:unstructured"
jcr:title="Properties"
sling:resourceType="granite/ui/components/coral/foundation/container"
margin="{Boolean}true">
<items jcr:primaryType="nt:unstructured">
<columns
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns"
margin="{Boolean}true">
<items jcr:primaryType="nt:unstructured">
<column
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/container">
<items jcr:primaryType="nt:unstructured">
<message
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
fieldDescription="The text to display on the component."
fieldLabel="Message"
name="./message"/>
</items>
</column>
</items>
</columns>
</items>
</properties>
</items>
</tabs>
</items>
</content>
</jcr:root>
Il file XML di cui sopra genera una finestra di dialogo molto semplice per Custom Component
. La parte critica del file è il nodo interno <message>
. Questa finestra di dialogo conterrà un textfield
semplice denominato Message
e persisterà il valore del campo di testo in una proprietà denominata message
.
Verrà creato un modello Sling accanto a per esporre il valore della proprietà message
tramite il modello JSON.
Puoi visualizzare molti altri esempi di finestre di dialogo visualizzando le definizioni dei componenti core. È inoltre possibile visualizzare campi modulo aggiuntivi, come select
, textarea
, pathfield
, disponibili sotto /libs/granite/ui/components/coral/foundation/form
in CRXDE-Lite.
Con un componente AEM tradizionale, in genere è richiesto uno script HTL. Poiché il SPA eseguirà il rendering del componente, non è necessario alcuno script HTL.
I modelli Sling sono Java "POJO" (Plain Old Java Objects) basati su annotazioni che facilitano la mappatura dei dati da JCR alle variabili Java. Funzione Sling Modelstypical per incapsulare logiche aziendali complesse lato server per i componenti AEM.
Nel contesto dell’editor di SPA, i modelli Sling espongono il contenuto di un componente attraverso il modello JSON attraverso una funzione utilizzando Sling Model Exporter.
Nell’IDE che preferisci, apri il modulo core
. CustomComponent.java
e CustomComponentImpl.java
sono già stati creati e inseriti come parte del codice iniziale del capitolo.
Se si utilizza l'IDE di codice di Visual Studio, può essere utile installare estensioni per Java.
Apri l'interfaccia Java CustomComponent.java
in core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/CustomComponent.java
:
Questa è l’interfaccia Java che verrà implementata dal modello Sling.
Aggiorna CustomComponent.java
in modo che estenda l'interfaccia ComponentExporter
:
package com.adobe.aem.guides.wknd.spa.angular.core.models;
import com.adobe.cq.export.json.ComponentExporter;
public interface CustomComponent extends ComponentExporter {
public String getMessage();
}
L’implementazione dell’interfaccia ComponentExporter
richiede che il modello Sling venga automaticamente acquisito dall’API del modello JSON.
L'interfaccia CustomComponent
include un singolo metodo getter getMessage()
. Questo è il metodo che esporrà il valore della finestra di dialogo di authoring attraverso il modello JSON. Nel modello JSON verranno esportati solo i metodi getter con parametri vuoti ()
.
Apri CustomComponentImpl.java
in core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/impl/CustomComponentImpl.java
.
Questa è l’implementazione dell’ interfaccia CustomComponent
. L’annotazione @Model
identifica la classe Java come modello Sling. L’annotazione @Exporter
consente di serializzare ed esportare la classe Java tramite l’esportazione di modelli Sling.
Aggiorna la variabile statica RESOURCE_TYPE
in modo che punti al componente AEM wknd-spa-angular/components/custom-component
creato nell'esercizio precedente.
static final String RESOURCE_TYPE = "wknd-spa-angular/components/custom-component";
Il tipo di risorsa del componente è ciò che associa il modello Sling al componente AEM e, in ultima analisi, viene mappato al componente Angular.
Aggiungi il metodo getExportedType()
alla classe CustomComponentImpl
per restituire il tipo di risorsa del componente:
@Override
public String getExportedType() {
return CustomComponentImpl.RESOURCE_TYPE;
}
Questo metodo è necessario durante l’implementazione dell’interfaccia ComponentExporter
e mostrerà il tipo di risorsa che consente la mappatura al componente Angular.
Aggiorna il metodo getMessage()
per restituire il valore della proprietà message
persistente dalla finestra di dialogo dell’autore. Utilizza l’ @ValueMap
annotazione per mappare il valore JCR message
a una variabile Java:
import org.apache.commons.lang3.StringUtils;
...
@ValueMapValue
private String message;
@Override
public String getMessage() {
return StringUtils.isNotBlank(message) ? message.toUpperCase() : null;
}
Viene aggiunta una nuova "logica di business" per restituire il valore del messaggio in maiuscolo. Questo ci permetterà di vedere la differenza tra il valore non elaborato memorizzato dalla finestra di dialogo dell’autore e il valore esposto dal modello Sling.
Puoi visualizzare il file finito CustomComponentImpl.java qui.
Il codice di Angular per il componente personalizzato è già stato creato. Quindi, effettua alcuni aggiornamenti per mappare il componente Angular al componente AEM.
Nel modulo ui.frontend
apri il file ui.frontend/src/app/components/custom/custom.component.ts
Osserva la riga @Input() message: string;
. È previsto che il valore in maiuscolo trasformato venga mappato su questa variabile.
Importa l'oggetto MapTo
dall'SDK JS dell'editor SPA AEM e lo utilizza per eseguire il mapping al componente AEM:
+ import {MapTo} from '@adobe/cq-angular-editable-components';
...
export class CustomComponent implements OnInit {
...
}
+ MapTo('wknd-spa-angular/components/custom-component')(CustomComponent, CustomEditConfig);
Apri cutom.component.html
e osserva che il valore di {{message}}
verrà visualizzato accanto a un tag <h2>
.
Apri custom.component.css
e aggiungi la seguente regola:
:host-context {
display: block;
}
Affinché il segnaposto dell’editor di AEM venga visualizzato correttamente quando il componente è vuoto, è necessario impostare :host-context
o un altro <div>
su display: block;
.
Distribuisci tutti gli aggiornamenti a un ambiente AEM locale dalla directory principale della directory di progetto, utilizzando le tue competenze Maven:
$ cd aem-guides-wknd-spa
$ mvn clean install -PautoInstallSinglePackage
Quindi, accedi a AEM per verificare gli aggiornamenti e consentire l'aggiunta di Custom Component
al SPA.
Verifica la registrazione del nuovo modello Sling passando a http://localhost:4502/system/console/status-slingmodels.
com.adobe.aem.guides.wknd.spa.angular.core.models.impl.CustomComponentImpl - wknd-spa-angular/components/custom-component
com.adobe.aem.guides.wknd.spa.angular.core.models.impl.CustomComponentImpl exports 'wknd-spa-angular/components/custom-component' with selector 'model' and extension '[Ljava.lang.String;@6fb4a693' with exporter 'jackson'
Dovresti visualizzare le due righe precedenti che indicano che il CustomComponentImpl
è associato al componente wknd-spa-angular/components/custom-component
e che è registrato tramite l’esportatore di modelli Sling.
Passa al SPA modello di pagina in http://localhost:4502/editor.html/conf/wknd-spa-angular/settings/wcm/templates/spa-page-template/structure.html.
Aggiorna i criteri del Contenitore di layout per aggiungere il nuovo Custom Component
come componente consentito:
Salva le modifiche al criterio e osserva Custom Component
come componente consentito:
Quindi, crea il Custom Component
utilizzando l'editor di SPA AEM.
Passa a http://localhost:4502/editor.html/content/wknd-spa-angular/us/en/home.html.
In modalità Edit
, aggiungi Custom Component
a Layout Container
:
Apri la finestra di dialogo del componente e inserisci un messaggio contenente lettere minuscole.
Questa è la finestra di dialogo creata in base al file XML precedente nel capitolo.
Salva le modifiche. Il messaggio visualizzato è in maiuscolo.
Visualizzare il modello JSON andando su http://localhost:4502/content/wknd-spa-angular/us/en.model.json. Cerca wknd-spa-angular/components/custom-component
:
"custom_component_208183317": {
"message": "HELLO WORLD",
":type": "wknd-spa-angular/components/custom-component"
}
Il valore JSON viene impostato su tutte le lettere maiuscole in base alla logica aggiunta al modello Sling.
Congratulazioni, hai imparato a creare un componente AEM personalizzato e come funzionano i modelli e le finestre di dialogo Sling con il modello JSON.
Puoi sempre visualizzare il codice finito su GitHub o estrarre il codice localmente passando al ramo Angular/custom-component-solution
.
Estendere un componente core - Scopri come estendere un componente core esistente da utilizzare con l’editor di SPA AEM. Scopri come aggiungere proprietà e contenuto a un componente esistente è una tecnica potente per espandere le funzionalità di un’implementazione di AEM Editor SPA.