Creare un componente personalizzato custom-component

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 sito di riferimento WKND tradizionale. Le immagini fornite dal sito di riferimento WKND vengono riutilizzate nell'SPA WKND. È possibile installare il pacchetto utilizzando Gestione pacchetti AEM.

Aprire la cartella ui.apps nell'IDE desiderato.

Passare a ui.apps/src/main/content/jcr_root/apps/wknd-spa-angular/components e creare una cartella denominata custom-component.

Creare un file denominato .content.xml sotto la cartella custom-component. Popolare 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 è un componente AEM.

jcr:title è il valore visualizzato agli autori di contenuti e componentGroup determina il raggruppamento di componenti nell'interfaccia utente di creazione.

Nella cartella custom-component creare un'altra cartella denominata _cq_dialog.

Sotto la cartella _cq_dialog creare un file denominato .content.xml e popolarlo con il seguente:

<?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 sopra riportato genera una semplice finestra di dialogo per Custom Component. La parte critica del file è il nodo <message> interno. Questa finestra di dialogo contiene un textfield semplice denominato Message e mantiene il valore del campo di testo in una proprietà denominata message.

Viene creato un modello Sling accanto a per esporre il valore della proprietà message tramite il modello JSON.

Con un componente AEM tradizionale, in genere è necessario uno script HTL. Poiché l’SPA esegue il rendering del componente, non è necessario alcuno script HTL.

Nell'IDE scelto aprire il modulo core. CustomComponent.java e CustomComponentImpl.java sono già stati creati e sottoposti a stub come parte del codice iniziale del capitolo.

Aprire l'interfaccia Java™ CustomComponent.java in core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/CustomComponent.java:

Si tratta dell’interfaccia Java™ 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 è un requisito affinché il modello Sling possa essere selezionato automaticamente dall'API del modello JSON.

L'interfaccia CustomComponent include un singolo metodo getter getMessage(). Questo è il metodo che espone il valore della finestra di dialogo dell’autore tramite il modello JSON. Nel modello JSON vengono esportati solo i metodi getter con parametri vuoti ().

Apri CustomComponentImpl.java alle core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/impl/CustomComponentImpl.java.

Implementazione dell'interfaccia CustomComponent. L'annotazione @Model identifica la classe Java™ come modello Sling. L'annotazione @Exporter consente la serializzazione e l'esportazione della classe Java™ tramite Sling Model Exporter.

Aggiornare 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 alla fine lo associa al componente Angular.

Aggiungere 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 quando si implementa l'interfaccia ComponentExporter ed espone il tipo di risorsa che consente il mapping al componente Angular.

Aggiornare il metodo getMessage() per restituire il valore della proprietà message persistente nella finestra di dialogo di authoring. Utilizzare l'annotazione @ValueMap 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 un’ulteriore "logica di business" per restituire il valore del messaggio in maiuscolo. Questo consente di vedere la differenza tra il valore non elaborato memorizzato dalla finestra di dialogo di authoring e il valore esposto dal modello Sling.

Nel modulo ui.frontend apri il file ui.frontend/src/app/components/custom/custom.component.ts

Osservare la riga @Input() message: string;. È previsto che il valore in maiuscolo trasformato sia mappato a questa variabile.

Importare l'oggetto MapTo dall'SDK JS dell'editor SPA AEM e utilizzarlo 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);

Aprire cutom.component.html e osservare che il valore di {{message}} è visualizzato sul lato di un tag <h2>.

Apri custom.component.css e aggiungi la seguente regola:

:host-context {
    display: block;
}

Affinché il segnaposto dell'editor AEM venga visualizzato correttamente quando il componente è vuoto, è necessario impostare :host-context o un altro <div> su display: block;.

Distribuisci gli aggiornamenti a un ambiente AEM locale dalla directory principale del progetto, utilizzando le tue competenze Maven:

$ cd aem-guides-wknd-spa
$ mvn clean install -PautoInstallSinglePackage

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'

Le due righe precedenti indicano che CustomComponentImpl è associato al componente wknd-spa-angular/components/custom-component e che è registrato tramite Sling Model Exporter.

Passa al modello per pagina SPA all'indirizzo http://localhost:4502/editor.html/conf/wknd-spa-angular/settings/wcm/templates/spa-page-template/structure.html.

Aggiornare il criterio Contenitore di layout per aggiungere il nuovo Custom Component come componente consentito:

Salvare le modifiche al criterio e osservare Custom Component come componente consentito:

Passa a http://localhost:4502/editor.html/content/wknd-spa-angular/us/en/home.html.

In modalità Edit, aggiungere Custom Component a Layout Container:

Apri la finestra di dialogo del componente e immetti un messaggio contenente alcune lettere minuscole.

Questa è la finestra di dialogo creata in base al file XML precedente nel capitolo.

Salva le modifiche. Il messaggio visualizzato deve essere scritto in maiuscolo.

Visualizza il modello JSON passando a 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 è impostato su tutte le lettere maiuscole in base alla logica aggiunta al modello Sling.