Developing a Custom Component for AEM Screens developing-a-custom-component-for-aem-screens

AEM 6.5 plus Latest Screens Feature Pack.

AEM Screens Player

Local Development Environment

Download and install the following packages using CRX Package Manager:

Get File

Get File
Optionally if working with Eclipse or another IDE download the below source package. Deploy the project to a local AEM instance by using the Maven command:

mvn -PautoInstallPackage clean install

Start HelloWorld SRC Screens We.Retail Run Project.

Get File

In CRX Package Manager, verify that the following two packages are installed:

1. screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip
2. screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip

Screens We.Retail Run Ui.Apps and Ui.Content packages installed by way of CRX Package Manager.

The screens-weretail-run.ui.apps package installs code beneath /apps/weretail-run.

This package contains the code responsible for rendering custom components for the project. This package includes component code and any JavaScript or CSS needed. This package also embeds screens-weretail-run.core-0.0.1-SNAPSHOT.jar which contains any Java™ code needed by the project.

Representation of the ui.apps code in CRXDE Lite

The Hello World component is just a placeholder. Over the course of the tutorial, functionality is added allowing an author to update the message displayed by the component.

The screens-weretail-run.ui.content package installs code beneath:

• /conf/we-retail-run
• /content/dam/we-retail-run
• /content/screens/we-retail-run

This package contains the starting content and configuration structure needed for the project. /conf/we-retail-run contains all configurations for the We.Retail Run project. /content/dam/we-retail-run includes starting digital assets for the project. /content/screens/we-retail-run contains the Screens content structure. The content beneath all of these paths is updated primarily in AEM. To promote consistency between environments (local, Dev, Stage, Prod) often a base content structure is saved in source control.

Navigate to the AEM Screens > We.Retail Run project:

From the AEM Start Menu, select the Screens the icon. Verify the We.Retail Run Project is seen.

In CRXDE-Lite http://localhost:4502/crx/de/index.jsp (or IDE of choice) navigate to /apps/weretail-run/components/content/helloworld.

Add the following properties to the helloworld component:

    jcr:title="Hello World"
    sling:resourceSuperType="foundation/components/parbase"
    componentGroup="We.Retail Run - Content"

Properties for /apps/weretail-run/components/content/helloworld

The Hello World component extends the foundation/components/parbase component so it can properly be used inside a sequence channel.

Create a file beneath /apps/weretail-run/components/content/helloworld named helloworld.html.

Populate the file with the following:

<!--/*

 /apps/weretail-run/components/content/helloworld/helloworld.html

*/-->

<!--/* production: preview authoring mode + unspecified mode (i.e. on publish) */-->
<sly data-sly-test.production="${wcmmode.preview || wcmmode.disabled}" data-sly-include="production.html" />

<!--/* edit: any other authoring mode, i.e. edit, design, scaffolding, etc. */-->
<sly data-sly-test="${!production}" data-sly-include="edit.html" />

Screens components require two different renderings depending on which authoring mode is being used:

1. Production: Preview or Publish mode (wcmmode=disabled)
2. Edit: used for all other authoring modes, i.e edit, design, scaffolding, developer…

helloworld.htmlacts as a switch, checking which authoring mode is active and redirecting to another HTL script. A common convention used by screens components is to have an edit.html script for Edit mode and a production.html script for Production mode.

Create a file beneath /apps/weretail-run/components/content/helloworld named production.html.

Populate the file with the following:

<!--/*
 /apps/weretail-run/components/content/helloworld/production.html

*/-->

<div data-duration="${properties.duration}" class="cmp-hello-world">
 <h1 class="cmp-hello-world__message">${properties.message}</h1>
</div>

The above is the production markup for the Hello World Component. A data-duration attribute is included since the component is used on a Sequence channel. The data-duration attribute is used by the sequence channel to know for how long a sequence item is to be displayed.

The component renders a div and an h1 tag with text. ${properties.message} is a portion of HTL script that outputs the contents of a JCR property that is named message. A dialog box is created later that allows a user to enter a value for the message property text.

Also note that BEM (Block Element Modifier) notation is used with the component. BEM is a CSS coding convention that makes it easier to create reusable components. BEM is the notation used by AEM’s Core Components.

Create a file beneath /apps/weretail-run/components/content/helloworld named edit.html.

Populate the file with the following:

<!--/*

 /apps/weretail-run/components/content/helloworld/edit.html

*/-->

<!--/* if message populated */-->
<div
 data-sly-test.message="${properties.message}"
 class="aem-Screens-editWrapper cmp-hello-world">
 <p class="cmp-hello-world__message">${message}</p>
</div>

<!--/* empty place holder */-->
<div data-sly-test="${!message}"
     class="aem-Screens-editWrapper cq-placeholder cmp-hello-world"
     data-emptytext="${'Hello World' @ i18n, locale=request.locale}">
</div>

The above is the edited markup for the Hello World Component. The first block displays an edited version of the component if the dialog message has been populated.

The second block is rendered if no dialog message has been entered. The cq-placeholder and data-emptytext render the label Hello World as a place holder in that case. The string for the label can be internationalized using i18n to support authoring in multiple locales.

Copy Screens Image Dialog to be used for the Hello World component.

It is easiest to start from an existing dialog and then make modifications.

1. Copy the dialog from: /libs/screens/core/components/content/image/cq:dialog
2. Paste the dialog beneath /apps/weretail-run/components/content/helloworld

Update Hello World dialog to include a tab for message.

Update the dialog so that it matches the following. The JCR node structure of the final dialog is presented below in 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="Hello World"
    sling:resourceType="cq/gui/components/authoring/dialog">
    <content
        jcr:primaryType="nt:unstructured"
        sling:resourceType="granite/ui/components/coral/foundation/tabs"
        size="L">
        <items jcr:primaryType="nt:unstructured">
            <message
                jcr:primaryType="nt:unstructured"
                jcr:title="Message"
                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns">
                <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="Message for component to display"
                                fieldLabel="Message"
                                name="./message"/>
                        </items>
                    </column>
                </items>
            </message>
            <sequence
                jcr:primaryType="nt:unstructured"
                jcr:title="Sequence"
                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns">
                <items jcr:primaryType="nt:unstructured">
                    <column
                        jcr:primaryType="nt:unstructured"
                        sling:resourceType="granite/ui/components/coral/foundation/container">
                        <items jcr:primaryType="nt:unstructured">
                            <duration
                                jcr:primaryType="nt:unstructured"
                                sling:resourceType="granite/ui/components/coral/foundation/form/numberfield"
                                defaultValue=""
                                fieldDescription="Amount of time the image is shown in the sequence, in milliseconds"
                                fieldLabel="Duration (milliseconds)"
                                min="0"
                                name="./duration"/>
                        </items>
                    </column>
                </items>
            </sequence>
        </items>
    </content>
</jcr:root>

The text field for the Message is saved to a property named message and that the number field for the Duration is saved to a property named duration. These two properties are both referenced in /apps/weretail-run/components/content/helloworld/production.html by HTL as ${properties.message} and ${properties.duration}.

Hello World - completed dialog

Create a folder for client-side libraries for the Hello World component.

Beneath /apps/weretail-run/components/content/helloworld, create a folder named clientlibs.

Beneath the clientlibs folder, create a node named shared of type cq:ClientLibraryFolder.

Add the following properties to the shared client library:

• allowProxy | Boolean | true

• categories| String[] | cq.screens.components

Properties for /apps/weretail-run/components/content/helloworld/clientlibs/shared

The categories property is a string that identifies the client library. The cq.screens.componentscategory is used in both Edit and Preview/Production mode. Therefore any CSS/JS defined in the sharedclientlib is loaded in all modes.

It is a best practice to never expose any paths directly to /apps in a production environment. The allowProxy property ensures the client library CSS and JS is referenced via a prefix of/etc.clientlibs.

Create file named css.txt beneath the shared folder.

Populate the file with the following:

#base=css

styles.less

Create a folder named css beneath the shared folder. Add a file named style.less beneath the css folder. The structure of the client libraries should now look like this:

Instead of writing CSS directly, this tutorial uses LESS. LESS is a popular CSS pre-compiler that supports CSS variables, mixins, and functions. AEM client libraries natively support LESS compilation. Sass or other pre-compilers can be used but must be compiled outside of AEM.

Populate /apps/weretail-run/components/content/helloworld/clientlibs/shared/css/styles.less with the following:

/**
    Shared Styles
   /apps/weretail-run/components/content/helloworld/clientlibs/shared/css/styles.less

**/

.cmp-hello-world {
    background-color: #fff;

 &__message {
  color: #000;
  font-family: Helvetica;
  text-align:center;
 }
}

Copy and paste the shared client library folder to create a client library that is named production.

Copy the shared client library to create a production client library.

Update the categories property of the production client library to be cq.screens.components.production.

This ensures that the styles are only loaded when in Preview/Production mode.

Properties for /apps/weretail-run/components/content/helloworld/clientlibs/production.

Populate /apps/weretail-run/components/content/helloworld/clientlibs/production/css/styles.less with the following:

/**
    Production Styles
   /apps/weretail-run/components/content/helloworld/clientlibs/production/css/styles.less

**/
.cmp-hello-world {

    height: 100%;
    width: 100%;
    position: fixed;

 &__message {

  position: relative;
  font-size: 5rem;
  top:25%;
 }
}

The above styles display the message centered in the middle of the screen, but only in Production mode.

In CRXDE Lite http://localhost:4502/crx/de/index.jsp#/apps/settings/wcm/designs, navigate to /apps/settings/wcm/designs.

Create a node beneath the designs folder, named we-retail-run with a type of cq:Page.

Beneath the we-retail-run page, add another node named jcr:content of type nt:unstructured. Add the following properties to the jcr:content node:

Design Page at /apps/settings/wcm/designs/we-retail-run.

From the AEM Start Menu, navigate to Screens > We.Retail Run > and select Channels.

Select the Create button

1. Choose Create Entity

In the Create wizard:

Template Step - choose Sequence Channel

1. Properties Step

• Basic Tab > Title = Idle Channel
• Channel Tab > check Make channel online

Open the page properties for the Idle Channel.

Update the Design field so that it points to /apps/settings/wcm/designs/we-retail-run, the design page created in the previous section.

Design config pointing to /apps/settings/wcm/designs/we-retail-run

Edit the newly created Idle Channel so you can open it.

Switch the page mode to Design Mode.

1. Select the wrench Icon in the Parsys so you can configure the allowed components.

2. Select the Screens group and the We.Retail Run - Content group.

Switch the page mode to Edit. The Hello World component can now be added to the page and combined with other sequence channel components.

In CRXDE Lite http://localhost:4502/crx/de/index.jsp#/apps/settings/wcm/designs/we-retail-run/jcr%3Acontent/sequencechannel/par, navigate to /apps/settings/wcm/designs/we-retail-run/jcr:content/sequencechannel/par. Notice the components property now includes group:Screens, group:We.Retail Run - Content.

Design configuration under /apps/settings/wcm/designs/we-retail-run