Estensione di un componente AEM Screens
Il seguente tutorial illustra i passaggi e le best practice per l’estensione dei componenti AEM Screens forniti con il prodotto. Il componente Immagine viene esteso per aggiungere una sovrapposizione di testo modificabile.
Panoramica overview
Questo tutorial è destinato agli sviluppatori che hanno poca esperienza con AEM Screens. In questa esercitazione, il componente Immagine Screens viene esteso per creare un componente Poster. Un titolo, una descrizione e un logo sono sovrapposti su un’immagine per creare un’esperienza coinvolgente in un canale Sequenza.
Un componente Custom Poster
viene creato estendendo il componente Immagine.
Prerequisiti prerequisites
Per completare questa esercitazione, sono necessari i seguenti elementi:
- AEM 6.5 + Feature Pack Screens più recente
- Lettore AEM Screens
- Ambiente di sviluppo locale
I passaggi del tutorial e le schermate vengono eseguiti utilizzando CRXDE-Lite. Per completare l'esercitazione è inoltre possibile utilizzare le IDE Eclipse o IntelliJ. Ulteriori informazioni sull'utilizzo di un IDE per sviluppare con AEM sono disponibili qui.
Configurazione del progetto project-setup
Il codice sorgente di un progetto Screens viene in genere gestito come progetto Maven con più moduli. Per accelerare l'esercitazione, è stato pregenerato un progetto utilizzando AEM Project Archetype 13. Ulteriori dettagli sulla creazione di un progetto con Archetipo progetto AEM Maven sono disponibili qui.
- Scarica e installa i seguenti pacchetti utilizzando Gestione pacchetti CRX
http://localhost:4502/crx/packmgr/index.jsp)r:
Ottieni file
Facoltativamente, se si lavora con Eclipse o un altro IDE, scaricare il pacchetto di origine seguente. Distribuisci il progetto in un’istanza AEM locale utilizzando il comando Maven:
mvn -PautoInstallPackage clean install
SRC Avvia Screens We.Retail
Esegui progetto
-
In Gestione pacchetti CRX
http://localhost:4502/crx/packmgr/index.jsp
sono installati i due pacchetti seguenti:screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip
screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip
Pacchetti AEM Screens
We.Retail Run Ui.Apps
eUi.Content
installati tramite Gestione pacchetti CRX
Creare il componente Poster poster-cmp
Il componente Poster estende il componente immagine predefinito di AEM Screens. Un meccanismo Sling, sling:resourceSuperType
, viene utilizzato per ereditare le funzionalità di base del componente Immagine senza dover copiare e incollare. Ulteriori informazioni sulle nozioni di base di Elaborazione richieste Sling sono disponibili qui.
Il componente Poster viene riprodotto a schermo intero in modalità anteprima/produzione. In modalità di modifica, è importante eseguire il rendering del componente in modo diverso per facilitare l’authoring del canale Sequenza.
-
In CRXDE-Lite
http://localhost:4502/crx/de/index.jsp
(o IDE scelto) sotto a/apps/weretail-run/components/content
crea uncq:Component
denominatoposter
.Aggiungi le seguenti proprietà al componente
poster
:code language-xml <?xml version="1.0" encoding="UTF-8"?> <jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0" xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" jcr:primaryType="cq:Component" jcr:title="Poster" sling:resourceSuperType="screens/core/components/content/image" componentGroup="We.Retail Run - Content"/>
Proprietà per /apps/weretail-run/components/content/poster
Impostando la proprietà
sling:resourceSuperType
suscreens/core/components/content/image
, il componente Poster eredita tutte le funzionalità del componente Immagine. I nodi e i file equivalenti trovati sottoscreens/core/components/content/image
possono essere aggiunti sotto il componenteposter
per ignorare ed estendere la funzionalità. -
Copia il nodo
cq:editConfig
sotto/libs/screens/core/components/content/image
. Incollacq:editConfig
sotto il componente/apps/weretail-run/components/content/poster
.Nel nodo
cq:editConfig/cq:dropTargets/image/parameters
, aggiornare la proprietàsling:resourceType
in modo che sia uguale aweretail-run/components/content/poster
.Rappresentazione XML di
cq:editConfig
rappresentata di seguito:code language-xml <?xml version="1.0" encoding="UTF-8"?> <jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0" xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0" jcr:primaryType="cq:EditConfig"> <cq:dropTargets jcr:primaryType="nt:unstructured"> <image jcr:primaryType="cq:DropTargetConfig" accept="[image/.*]" groups="[media]" propertyName="./fileReference"> <parameters jcr:primaryType="nt:unstructured" sling:resourceType="weretail-run/components/content/poster" imageCrop="" imageMap="" imageRotate=""/> </image> </cq:dropTargets> </jcr:root>
-
Copia la finestra di dialogo WCM Foundation
image
da utilizzare per il componenteposter
.È più semplice iniziare da una finestra di dialogo esistente e quindi apportare modifiche.
- Copia la finestra di dialogo da:
/libs/wcm/foundation/components/image/cq:dialog
- Incolla la finestra di dialogo sotto
/apps/weretail-run/components/content/poster
Finestra di dialogo copiata da
/libs/wcm/foundation/components/image/cq:dialog
a/apps/weretail-run/components/content/poster
Il componente AEM Screens
image
è stato sovrascritto al componente WCM Foundationimage
. Pertanto, il componenteposter
eredita la funzionalità da entrambi. La finestra di dialogo per il componente poster è costituita da una combinazione delle finestre di dialogo Screens e Foundation. Le funzionalità di Sling Resource Merger vengono utilizzate per nascondere le schede e i campi di dialogo irrilevanti ereditati dai componenti sovrascritti. - Copia la finestra di dialogo da:
-
Aggiorna
cq:dialog
sotto/apps/weretail-run/components/content/poster
con le seguenti modifiche rappresentate in XML:code language-xml <?xml version="1.0" encoding="UTF-8"?> <jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0" xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0" jcr:primaryType="nt:unstructured" jcr:title="Poster" sling:resourceType="cq/gui/components/authoring/dialog"> <content jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/foundation/container"> <layout jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/foundation/layouts/tabs" type="nav"/> <items jcr:primaryType="nt:unstructured"> <image jcr:primaryType="nt:unstructured" jcr:title="Elements" sling:resourceType="granite/ui/components/foundation/section"> <layout jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/foundation/layouts/fixedcolumns" margin="{Boolean}false"/> <items jcr:primaryType="nt:unstructured"> <column jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/foundation/container"> <items jcr:primaryType="nt:unstructured" sling:hideChildren="[linkURL,size]"> <file jcr:primaryType="nt:unstructured" sling:resourceType="cq/gui/components/authoring/dialog/fileupload" autoStart="{Boolean}false" class="cq-droptarget" fieldLabel="Image asset" fileNameParameter="./fileName" fileReferenceParameter="./fileReference" mimeTypes="[image]" multiple="{Boolean}false" name="./file" title="Upload Image Asset" uploadUrl="${suffix.path}" useHTML5="{Boolean}true"/> <title jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/foundation/form/textfield" fieldLabel="Title" name="./jcr:title"/> <description jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/foundation/form/textarea" fieldLabel="Description" name="./jcr:description"/> <position jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/coral/foundation/form/click" fieldLabel="Text Position" name="./textPosition"> <items jcr:primaryType="nt:unstructured"> <left jcr:primaryType="nt:unstructured" text="Left" value="left"/> <center jcr:primaryType="nt:unstructured" text="Center" value="center"/> <right jcr:primaryType="nt:unstructured" text="Right" value="right"/> </items> </position> <color jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/coral/foundation/form/click" fieldLabel="Text Color" name="./textColor"> <items jcr:primaryType="nt:unstructured"> <light jcr:primaryType="nt:unstructured" text="Light" value="light"/> <dark jcr:primaryType="nt:unstructured" text="Dark" value="dark"/> </items> </color> </items> </column> </items> </image> <accessibility jcr:primaryType="nt:unstructured" sling:hideResource="{Boolean}true"/> </items> </content> </jcr:root>
La proprietà
sling:hideChildren
="[linkURL,size]
" è utilizzata nel nodoitems
per garantire che i campi linkURL e size siano nascosti nella finestra di dialogo. La rimozione di questi nodi dalla finestra di dialogo del poster non è sufficiente. La proprietàsling:hideResource="{Boolean}true"
nella scheda Accesso facilitato viene utilizzata per nascondere l'intera scheda.Nella finestra di dialogo, Posizione testo e Colore testo, vengono aggiunti due campi di clic per consentire agli autori di controllare la posizione del testo e il colore del Titolo e della Descrizione.
Poster - Struttura del dialogo finale
A questo punto, è possibile aggiungere un'istanza del componente
poster
alla pagina Canale inattivo nel progetto di esecuzioneWe.Retail
:http://localhost:4502/editor.html/content/screens/we-retail-run/channels/idle-channel.edit.html
.Campi finestra di dialogo poster
-
Crea un file sotto
/apps/weretail-run/components/content/poster
denominatoproduction.html.
Compila il file con quanto segue:
code language-xml <!--/* /apps/weretail-run/components/content/poster/production.html */--> <div data-sly-use.image="image.js" data-duration="${properties.duration}" class="cmp-poster" style="background-image: url(${request.contextPath @ context='uri'}${image.src @ context='uri'});"> <div class="cmp-poster__text cmp-poster__text--${properties.textPosition @ context='attribute'} cmp-poster__text--${properties.textColor @ context='attribute'}"> <h1 class="cmp-poster__title">${properties.jcr:title}</h1> <h2 class="cmp-poster__description">${properties.jcr:description}</h2> </div> <img class="cmp-poster__logo" src="/content/dam/we-retail-run/logos/we-retail-run_dark.png" alt="we-retail-logo" /> </div>
Il markup di produzione per il componente Poster è visualizzato direttamente qui sopra. Lo script HTL sostituisce
screens/core/components/content/image/production.html
.image.js
è uno script sul lato server che crea un oggetto immagine simile a POJO. È quindi possibile chiamare l'oggetto Image per eseguire il rendering disrc
come immagine di sfondo in linea.I tag
The h1
e h2 aggiunti visualizzano il Titolo e la Descrizione in base alle proprietà del componente:${properties.jcr:title}
e${properties.jcr:description}
.Intorno ai tag
h1
eh2
è presente un wrapper div con tre classi CSS con varianti di "cmp-poster__text
". Il valore per le proprietàtextPosition
etextColor
viene utilizzato per modificare la classe CSS sottoposta a rendering in base alla selezione della finestra di dialogo dell'autore. Nella sezione successiva vengono scritti file CSS provenienti dalle librerie client per abilitare queste modifiche nella visualizzazione.Un logo viene incluso anche come sovrapposizione nel componente. In questo esempio, il percorso del logo
We.Retail
è hardcoded in DAM. A seconda del caso d’uso, potrebbe essere più logico creare un campo di dialogo per rendere il percorso del logo un valore popolato dinamicamente.Si noti inoltre che con il componente viene utilizzata la notazione BEM (Block Element Modifier). BEM è una convenzione di codifica CSS che semplifica la creazione di componenti riutilizzabili. BEM è la notazione utilizzata da Componenti core dell'AEM.
-
Crea un file sotto
/apps/weretail-run/components/content/poster
denominatoedit.html.
Compila il file con quanto segue:
code language-xml <!--/* /apps/weretail-run/components/content/poster/edit.html */--> <div class="aem-Screens-editWrapper ${image.cssClass} cmp-poster" data-sly-use.image="image.js" data-emptytext="${'Poster' @ i18n, locale=request.locale}"> <img class="cmp-poster__image" src="${request.contextPath}${image.src @ context='uri'}" width="100%" /> <div class="cmp-poster__text cmp-poster__text--${properties.textPosition @ context='attribute'} cmp-poster__text--${properties.textColor @ context='attribute'}"> <p class="cmp-poster__title">${properties.jcr:title}</p> <p class="cmp-poster__description">${properties.jcr:description}</p> </div> </div>
Il markup edit per il componente Poster è visualizzato direttamente sopra. Lo script HTL sostituisce
/libs/screens/core/components/content/image/edit.html
. Il markup è simile al markupproduction.html
e visualizza il titolo e la descrizione sopra l'immagine.aem-Screens-editWrapper
viene aggiunto in modo che il componente non venga renderizzato a schermo intero nell'editor. L'attributodata-emptytext
garantisce che venga visualizzato un segnaposto quando non è stata compilata alcuna immagine o contenuto.
Creare librerie lato client clientlibs
Le librerie lato client forniscono un meccanismo per organizzare e gestire i file CSS e JavaScript necessari per un’implementazione AEM. Ulteriori informazioni sull'utilizzo di Librerie lato client sono disponibili qui.
Il rendering dei componenti di AEM Screens varia in modalità Modifica rispetto alla modalità Anteprima/Produzione. Vengono creati due set di librerie client, uno per la modalità di modifica e l’altro per l’anteprima/produzione.
-
Crea una cartella per le librerie lato client per il componente Poster.
Sotto
/apps/weretail-run/components/content/poster
, creare una cartella denominataclientlibs
. -
Nella cartella
clientlibs
creare un nodo denominatoshared
di tipocq:ClientLibraryFolder.
-
Aggiungi le seguenti proprietà alla libreria client condivisa:
allowProxy
| Booleano |true
categories
| Stringa[] |cq.screens.components
Proprietà per /apps/weretail-run/components/content/poster/clientlibs/shared
La proprietà
categories
è una stringa che identifica la libreria client. La categoriacq.screens.components
viene utilizzata sia in modalità Modifica che Anteprima/Produzione. Pertanto, qualsiasi CSS/JS definito nella libreria clientshared
viene caricato in tutte le modalità.Come best practice, non esporre mai percorsi direttamente a
/apps
in un ambiente di produzione. La proprietàallowProxy
garantisce che venga fatto riferimento alla libreria client CSS e JS tramite il prefisso/etc.clientlibs
. Ulteriori informazioni sulla proprietà allowProxy sono disponibili qui. -
Crea il file denominato
css.txt
sotto la cartella condivisa.Compila il file con quanto segue:
code language-none #base=css styles.less
-
Creare una cartella denominata
css
sotto la cartellashared
. Aggiungere un file denominatostyle.less
sotto la cartellacss
. La struttura delle librerie client ora dovrebbe essere simile alla seguente:Invece di scrivere direttamente CSS, questa esercitazione utilizza MENO. LESS è un popolare precompilatore CSS che supporta variabili, mixin e funzioni CSS. Le librerie client AEM supportano in modo nativo la compilazione LESS. È possibile utilizzare gli Sass o altri precompilatori, ma questi devono essere compilati al di fuori dell’AEM.
-
Popolare
/apps/weretail-run/components/content/poster/clientlibs/shared/css/styles.less
con quanto segue:code language-css /* /apps/weretail-run/components/content/poster/clientlibs/shared/css/styles.less Poster component - Shared Style */ @import url('https://fonts.googleapis.com/css?family=Fjalla+One|Open+Sans:400i'); @text-light-color: #fff; @text-dark-color: #000; @title-font-family: 'Fjalla One', sans-serif; @description-font-family: 'Open Sans', sans-serif; .cmp-poster { &__text { position: absolute; color: @text-light-color; top: 0; text-align:center; width: 100%; &--left { text-align: left; margin-left: 1em; } &--right { text-align: right; margin-right: 1em; } &--dark { color: @text-dark-color; } } &__title { font-weight: bold; font-family: @title-font-family; font-size: 1.2em; } &__description { font-style: italic; font-family: @description-font-family; } }
note note NOTE I Web Fonts Google vengono utilizzati per le famiglie di caratteri. I Web Fonts richiedono connettività Internet e non tutte le implementazioni AEM Screens dispongono di una connessione affidabile. La pianificazione della modalità offline è un aspetto importante per le distribuzioni AEM Screens. -
Copia la cartella della libreria client
shared
. Incollalo come elemento di pari livello e rinominalo inproduction
. -
Aggiorna la proprietà
categories
della libreria client di produzione incq.screens.components.production.
La categoria
cq.screens.components.production
garantisce che gli stili vengano caricati solo in modalità Anteprima/Produzione.Proprietà per /apps/weretail-run/components/content/poster/clientlibs/production
-
Popolare
/apps/weretail-run/components/content/poster/clientlibs/production/css/styles.less
con quanto segue:code language-css /* /apps/weretail-run/components/content/poster/clientlibs/production/css/styles.less Poster component - Production Style */ .cmp-poster { background-size: cover; height: 100%; width: 100%; position:absolute; &__text { top: 2em; &--left { width: 40%; top: 5em; } &--right { width: 40%; right: 1em; } } &__title { font-size: 5rem; font-weight: 900; margin: 0.1rem; } &__description { font-size: 2rem; margin: 0.1rem; font-weight: 400; } &__logo { position: absolute; max-width: 200px; top: 1em; left: 0; } }
Gli stili di cui sopra visualizzano il Titolo e la Descrizione in una posizione assoluta sullo schermo. Il titolo viene visualizzato più grande della descrizione. La notazione BEM del componente consente di definire con attenzione gli stili all'interno della classe cmp-poster.
È possibile utilizzare una terza categoria di librerie client: cq.screens.components.edit
per aggiungere al componente Modifica solo stili specifici.
cq.screens.components
cq.screens.components.edit
cq.screens.components.production
Aggiungi componente poster a un canale sequenza add-sequence-channel
Il componente Poster viene utilizzato su un canale Sequenza. Il pacchetto iniziale di questa esercitazione includeva un canale inattivo. Il canale inattivo è preconfigurato per consentire i componenti del gruppo We.Retail Run - Content
. Il gruppo del componente Poster è impostato su We.Retail Run - Content
ed è disponibile per essere aggiunto al canale.
-
Aprire il canale di inattività dal progetto di esecuzione
We.Retail
:http://localhost:4502/editor.html/content/screens/we-retail-run/channels/idle-channel.edit.html
-
Trascina nella pagina una nuova istanza del componente Poster dalla barra laterale.
-
Modifica la finestra di dialogo del componente Poster per aggiungere un’immagine, un titolo, una descrizione. Utilizza le opzioni Posizione testo e Colore testo per garantire che Titolo/Descrizione sia leggibile sull’immagine.
-
Per aggiungere alcuni componenti Poster, ripetere i passaggi precedenti. Aggiungi transizioni tra i componenti.
Tutti gli elementi insieme putting-it-all-together
Il video seguente mostra il componente finito e come può essere aggiunto a un canale Sequenza. Il canale viene quindi aggiunto a una visualizzazione Posizione e infine assegnato a un lettore Screens.
Codice finito finished-code
Di seguito è riportato il codice finito dell'esercitazione. screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip e screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip sono i pacchetti AEM compilati. SRC-screens-weretail-run-0.0.1.zip è il codice sorgente non compilato che può essere distribuito utilizzando Maven.
SRC Final AEM Screens We.Retail
Esegui progetto