Erweitern einer AEM Screens-Komponente
Im folgenden Tutorial werden die Schritte und Best Practices für die Erweiterung der vordefinierten AEM Screens-Komponenten erläutert. Die Bildkomponente wird erweitert und eine Überlagerung mit einem bearbeitbaren Text wird hinzugefügt.
Überblick overview
Dieses Tutorial richtet sich an Entwicklerinnen und Entwickler, die neu bei AEM Screens sind. In diesem Tutorial wird die Screens-Bildkomponente erweitert und eine Poster-Komponente erstellt. Ein Titel, eine Beschreibung und ein Logo werden auf einem Bild überlagert, um ein überzeugendes Erlebnis in einem Sequenzkanal zu schaffen.
Eine Custom Poster-Komponente wird durch Erweitern der Bildkomponente erstellt.
Voraussetzungen prerequisites
Um diese Anleitung abzuschließen, benötigen Sie Folgendes:
- AEM 6.5 + das neueste Screens Feature Pack
- AEM Screens-Player
- Lokale Entwicklungsumgebung
Die Tutorial-Schritte und Screenshots basieren auf CRXDE Lite. Eclipse- oder IntelliJ-IDEs können ebenfalls verwendet werden, um das Tutorial abzuschließen. Weitere Informationen zur Verwendung einer IDE zur Entwicklung mit AEM finden Sie hier.
Projekt-Setup project-setup
Der Quell-Code eines Screens-Projekts wird normalerweise als Maven-Projekt mit mehreren Modulen verwaltet. Um das Tutorial zu beschleunigen, wurde ein Projekt mithilfe des AEM-Projektarchetyps 13 vorgeneriert. Weitere Informationen zum Erstellen eines Projekts mit einem Maven-Archetyp für AEM-Projekte finden Sie hier.
- Laden Sie die folgenden Pakete herunter und installieren Sie diese mit CRX Package Manage
http://localhost:4502/crx/packmgr/index.jsp)r:
Datei abrufen
Wenn Sie mit Eclipse oder einer anderen IDE arbeiten, laden Sie optional das folgende Quellpaket herunter. Stellen Sie das Projekt mithilfe des Maven-Befehls in einer lokalen AEM-Instanz bereit:
mvn -PautoInstallPackage clean install
SRC – Ausgangsprojekt „We.Retail Run“ für AEM Screens
-
Im CRX Package Manager
http://localhost:4502/crx/packmgr/index.jspwerden die folgenden zwei Pakete installiert:screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zipscreens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip
Über CRX Package Manager installierte
We.Retail Run Ui.Apps- undUi.Content-Pakete für AEM Screens
Erstellen der Poster-Komponente poster-cmp
Die Poster-Komponente erweitert die vorkonfigurierte AEM Screens-Bildkomponente. Ein Sling-Mechanismus sling:resourceSuperType wird verwendet, um die Kernfunktionalität der Bildkomponente zu erben, ohne dass Kopieren und Einfügen erforderlich ist. Weitere Informationen zu den Grundlagen der Sling-Anforderungsverarbeitung finden Sie hier.
Die Poster-Komponente wird im Vollbildmodus im Vorschau-/Produktionsmodus wiedergegeben. Im Bearbeitungsmodus ist es wichtig, die Komponente unterschiedlich zu rendern, um das Authoring des Sequenzkanals zu erleichtern.
-
Erstellen Sie in CRXDE-Lite
http://localhost:4502/crx/de/index.jsp(oder einer IDE Ihrer Wahl) unterhalb von/apps/weretail-run/components/contenteinecq:Componentnamensposter.Fügen Sie der Komponente
posterdie folgenden Eigenschaften hinzu: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"/>
Eigenschaften für /apps/weretail-run/components/content/poster
Durch Festlegen der Eigenschaft
sling:resourceSuperTypeaufscreens/core/components/content/imageerbt die Poster-Komponente effektiv alle Funktionen der Bildkomponente. Entsprechende Knoten und Dateien unterscreens/core/components/content/imagekönnen unter der Komponenteposterhinzugefügt werden, um die Funktionalität zu überschreiben und zu erweitern. -
Kopieren Sie den Knoten
cq:editConfigunter/libs/screens/core/components/content/image. Fügen Sie diecq:editConfigunterhalb der Komponente/apps/weretail-run/components/content/posterein.Aktualisieren Sie auf dem Knoten
cq:editConfig/cq:dropTargets/image/parametersdie Eigenschaftsling:resourceTypeso, dass sie gleichweretail-run/components/content/posterist.
Im Folgenden finden Sie die XML-Darstellung von
cq:editConfig: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> -
Kopieren Sie das Dialogfeld
imagevon „WCM Foundation“, um es für die Komponenteposterzu verwenden.Es ist am einfachsten, von einem vorhandenen Dialogfeld aus zu starten und dann Änderungen vorzunehmen.
- Kopieren Sie das Dialgofeld aus
/libs/wcm/foundation/components/image/cq:dialog - Fügen Sie das Dialogfeld hier ein:
/apps/weretail-run/components/content/poster
Kopiertes Dialogfeld von
/libs/wcm/foundation/components/image/cq:dialognach/apps/weretail-run/components/content/posterDie AEM Screens-Komponente
imageist der WCM Foundation-Komponenteimageübergeordnet. Daher erbt dieposter-Komponente die Funktionalität von beiden. Das Dialogfeld für die Poster-Komponente besteht aus einer Kombination der Dialogfelder „Screens“ und „Foundation“. Die Funktionen desSling Resource Mergerwerden verwendet, um irrelevante Dialogfelder und Registerkarten auszublenden, die von den übertypisierten Komponenten übernommen werden. - Kopieren Sie das Dialgofeld aus
-
Aktualisieren Sie
cq:dialogunterhalb von/apps/weretail-run/components/content/postermit den folgenden in XML dargestellten Änderungen: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>Die Eigenschaft
sling:hideChildren="[linkURL,size]" wird auf dem Knotenitemsverwendet, um sicherzustellen, dass die Felder linkURL und size aus dem Dialogfeld ausgeblendet werden. Es genügt nicht, diese Knoten aus dem Poster-Dialogfeld zu entfernen. Mit der Eigenschaftsling:hideResource="{Boolean}true"auf der Registerkarte „Erreichbarkeit“ wird die gesamte Registerkarte ausgeblendet.Dem Dialogfeld werden die beiden Auswahlfelder „Textposition“ und „Textfarbe“ hinzugefügt, damit Autorinnen und Autoren die Textposition und Farbe des Titels und der Beschreibung steuern können.
Poster – Struktur des endgültigen Dialogfelds
An dieser Stelle kann eine Instanz der Komponente
posterim ProjektWe.RetailRun zur Seite Idle Channel hinzugefügt werden:http://localhost:4502/editor.html/content/screens/we-retail-run/channels/idle-channel.edit.html.
Felder des Poster-Dialogfelds
-
Erstellen Sie unter
/apps/weretail-run/components/content/postereine Datei mit dem Namenproduction.html.Füllen Sie die Datei mit folgendem Inhalt:
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>Das Produktions-Markup für die Poster-Komponente ist direkt hier vorstehend zu sehen. Das HTL-Skript überschreibt
screens/core/components/content/image/production.html.image.jsist ein Server-seitiges Skript, das ein POJO-ähnliches Bildobjekt erstellt. Das Bildobjekt kann dann aufgerufen werden, umsrcals eingebettetes Hintergrundbild wiederzugeben.The h1- und h2-Tags werden hinzugefügt, um den Titel und die Beschreibung anhand der Komponenteneigenschaften anzuzeigen:${properties.jcr:title}und${properties.jcr:description}.Die
h1- undh2-Tags werden von einem Div-Wrapper mit drei CSS-Klassen mit Varianten voncmp-poster__textumgeben. Der Wert für die EigenschaftentextPositionundtextColorwird verwendet, um die CSS-Klasse zu ändern, die anhand der Dialogfeldauswahl des Autors wiedergegeben wird. Im nächsten Abschnitt werden CSS aus Client-Bibliotheken geschrieben, um diese Änderungen in der Anzeige zu aktivieren.Ein Logo ist auch als Überlagerung in der Komponente enthalten. In diesem Beispiel ist der Pfad zum
We.Retail-Logo im DAM fest kodiert. Je nach Nutzungsszenario ist es möglicherweise sinnvoller, ein neues Dialogfeld zu erstellen, in dem der Logo-Pfad als dynamischer Wert eingegeben wird.Beachten Sie außerdem, dass die BEM-Notation (Block Element Modifier) mit der Komponente verwendet wird. BEM ist eine CSS-Kodierungskonvention, die die Erstellung wiederverwendbarer Komponenten erleichtert. BEM ist die Notation, die von den AEM-Kernkomponenten verwendet wird.
-
Erstellen Sie unter
/apps/weretail-run/components/content/postereine Datei mit dem Namenedit.html.Füllen Sie die Datei mit folgendem Inhalt:
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>Das bearbeitete-Markup für die Poster-Komponente wird direkt oben angezeigt. Das HTL-Skript überschreibt
/libs/screens/core/components/content/image/edit.html. Das Markup ähnelt demproduction.html-Markup und zeigt den Titel und die Beschreibung über dem Bild an.Der
aem-Screens-editWrapperwird hinzugefügt, damit die Komponente im Editor nicht bildschirmfüllend dargestellt wird. Das Attributdata-emptytextstellt sicher, dass ein Platzhalter angezeigt wird, wenn kein Bild oder Inhalt eingefügt wurde.
Erstellen Client-seitiger Bibliotheken clientlibs
Client-seitige Bibliotheken bieten einen Mechanismus zum Organisieren und Verwalten von CSS- und JavaScript-Dateien, die für eine AEM-Implementierung erforderlich sind. Weitere Informationen zur Verwendung Client-seitiger Bibliotheken finden Sie hier.
AEM Screens-Komponenten werden im Bearbeitungsmodus anders als im Vorschaumodus/Produktionsmodus dargestellt. Es werden zwei Gruppen von Client-Bibliotheken erstellt, eine für den Bearbeitungsmodus und eine für die Vorschau/Produktion.
-
Erstellen Sie einen Ordner für Client-seitige Bibliotheken für die Poster-Komponente.
Erstellen Sie unter
/apps/weretail-run/components/content/postereinen Ordner mit dem Namenclientlibs.
-
Erstellen Sie unter dem Ordner
clientlibseinen neuen Knoten namenssharedvom Typcq:ClientLibraryFolder.
-
Fügen Sie der freigegebenen Client-Bibliothek die folgenden Eigenschaften hinzu:
allowProxyBooleantruecategoriesString[]cq.screens.components
Eigenschaften für /apps/weretail-run/components/content/poster/clientlibs/shared
Die Eigenschaft
categoriesist eine Zeichenfolge, die die Client-Bibliothek identifiziert. Die Kategoriecq.screens.componentswird sowohl im Bearbeitungs- als auch im Vorschau-/Produktionsmodus verwendet. Daher wird jedes in der Clientlibshareddefinierte CSS/JS in allen Modi geladen.Es empfiehlt sich, in einer Produktionsumgebung niemals Pfade direkt zu
/appsbereitzustellen. Die EigenschaftallowProxystellt sicher, dass auf das CSS/JS der Client-Bibliothek über ein Präfix/etc.clientlibsverwiesen wird. Weitere Informationen über die Eigenschaft „allowProxy“ finden Sie hier. -
Erstellen Sie eine Datei mit dem Namen
css.txtunter dem freigegebenen Ordner.Füllen Sie die Datei mit folgendem Inhalt:
code language-none #base=css styles.less -
Erstellen Sie einen Ordner mit dem Namen
cssunter dem Ordnershared. Fügen Sie eine Datei mit dem Namenstyle.lessunter dem Ordnercsshinzu. Die Struktur der Client-Bibliotheken sollte jetzt wie folgt aussehen:
Anstatt CSS direkt zu schreiben, verwendet dieses Tutorial LESS. LESS ist ein beliebter CSS-Precompiler, der CSS-Variablen, Mixins und Funktionen unterstützt. AEM-Client-Bibliotheken unterstützen nativ die LESS-Kompilierung. Sie können Sass oder andere Pre-Compiler verwenden, müssen sie jedoch außerhalb von AEM kompilieren.
-
Füllen Sie
/apps/weretail-run/components/content/poster/clientlibs/shared/css/styles.lesswie folgt: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 Für die Schriftfamilien werden Google Web Fonts verwendet. Web Fonts erfordern eine Internet-Verbindung, und nicht alle AEM Screens-Implementierungen verfügen über eine zuverlässige Verbindung. Die Planung des Offline-Modus ist ein wichtiger Aspekt bei AEM Screens-Bereitstellungen. -
Kopieren Sie den Client-Bibliotheksordner
shared. Fügen Sie ihn als gleichrangiges Element ein und benennen Sie ihn inproductionum.
-
Ändern Sie den Wert der Eigenschaft
categoriesder Produktions-Client-Bibliothek incq.screens.components.production..Die Kategorie
cq.screens.components.productionstellt sicher, dass die Stile nur im Vorschau-/Produktionsmodus geladen werden.
Eigenschaften für /apps/weretail-run/components/content/poster/clientlibs/production
-
Füllen Sie
/apps/weretail-run/components/content/poster/clientlibs/production/css/styles.lesswie folgt: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; } }Die oben genannten Stile zeigen den Titel und die Beschreibung an einer absoluten Position auf dem Bildschirm an. Der Titel wird größer als die Beschreibung angezeigt. Die BEM-Notation der Komponente macht es sehr einfach, die Formatvorlagen innerhalb der Klasse cmp-poster sorgfältig zu definieren.
Mit einer dritten Client-Bibliothekskategorie, cq.screens.components.edit, könnten nur bearbeitbare spezifische Stile zur Komponente hinzugefügt werden.
cq.screens.componentscq.screens.components.editcq.screens.components.productionHinzufügen einer Poster-Komponente zu einem Sequenzkanal add-sequence-channel
Die Poster-Komponente wird in einem Sequenzkanal verwendet. Das Startpaket für dieses Tutorial enthielt einen inaktiven Kanal. Der inaktive Kanal (Idle Channel) ist so vorkonfiguriert, dass Komponenten der Gruppe We.Retail Run - Content zugelassen werden. Die Gruppe der Poster-Komponente ist auf We.Retail Run - Content eingestellt und kann dem Kanal hinzugefügt werden.
-
Öffnen Sie den inaktiven Kanal des Projekts „
We.RetailRun“:http://localhost:4502/editor.html/content/screens/we-retail-run/channels/idle-channel.edit.html -
Ziehen Sie eine neue Instanz der Poster-Komponente aus der Seitenleiste auf die Seite.
-
Bearbeiten Sie das Dialogfeld der Poster-Komponente, um ein Bild, einen Titel und eine Beschreibung hinzuzufügen. Verwenden Sie die Optionen „Textposition“ und „Textfarbe“, um sicherzustellen, dass der Titel/die Beschreibung über dem Bild lesbar ist.
-
Um mehrere Poster-Komponenten hinzuzufügen, wiederholen Sie die oben beschriebenen Schritte. Fügen Sie Übergänge zwischen den Komponenten hinzu.
Zusammenfassung putting-it-all-together
Das folgende Video zeigt die fertige Komponente und wie sie einem Sequenzkanal hinzugefügt werden kann. Der Kanal wird dann einer Standortsanzeige hinzugefügt und letztendlich einem Screens-Player zugewiesen.
Fertiger Code finished-code
Unten finden Sie den fertigen Code aus dem Tutorial. screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip und screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip sind kompilierte AEM-Pakete. SRC-screens-weretail-run-0.0.1.zip ist der nicht kompilierte Quell-Code, der mithilfe von Maven bereitgestellt werden kann.
SRC – fertiges Projekt „We.Retail Run“ für AEM Screens