Custom Component

In the ui.apps module, navigate to /apps/wknd/components and create a folder named byline.

Inside the byline folder, add a file named .content.xml

Populate the .content.xml file with the following:

<?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="Byline"
    jcr:description="Displays a contributor's byline."
    componentGroup="WKND Sites Project - Content"
    sling:resourceSuperType="core/wcm/components/image/v2/image"/>

The above XML file provides the definition for the component, including the title, description, and group. The sling:resourceSuperType points to core/wcm/components/image/v2/image, which is the Core Image Component.

Inside the byline folder, add a file byline.html, which is responsible for the HTML presentation of the component. Naming the file the same as the folder is important, as it becomes the default script Sling uses to render this resource type.

Add the following code to the byline.html.

<!--/* byline.html */-->
<div data-sly-use.placeholderTemplate="core/wcm/components/commons/v1/templates.html">
</div>
<sly data-sly-call="${placeholderTemplate.placeholder @ isEmpty=true}"></sly>

Inside the byline folder, create a folder named _cq_dialog.

Inside the byline/_cq_dialog, add a file named .content.xml. This is the XML definition for the dialog. Add the following XML:

<?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" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
        jcr:primaryType="nt:unstructured"
        jcr:title="Byline"
        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}false">
                <items jcr:primaryType="nt:unstructured">
                    <asset
                            jcr:primaryType="nt:unstructured"
                            sling:hideResource="{Boolean}false"/>
                    <metadata
                            jcr:primaryType="nt:unstructured"
                            sling:hideResource="{Boolean}true"/>
                    <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">
                                            <name
                                                    jcr:primaryType="nt:unstructured"
                                                    sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
                                                    emptyText="Enter the contributor's name to display."
                                                    fieldDescription="The contributor's name to display."
                                                    fieldLabel="Name"
                                                    name="./name"
                                                    required="{Boolean}true"/>
                                            <occupations
                                                    jcr:primaryType="nt:unstructured"
                                                    sling:resourceType="granite/ui/components/coral/foundation/form/multifield"
                                                    fieldDescription="A list of the contributor's occupations."
                                                    fieldLabel="Occupations"
                                                    required="{Boolean}false">
                                                <field
                                                        jcr:primaryType="nt:unstructured"
                                                        sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
                                                        emptyText="Enter an occupation"
                                                        name="./occupations"/>
                                            </occupations>
                                        </items>
                                    </column>
                                </items>
                            </columns>
                        </items>
                    </properties>
                </items>
            </tabs>
        </items>
    </content>
</jcr:root>

These dialog node definitions use the Sling Resource Merger to control which dialog tabs are inherited from the sling:resourceSuperType component, in this case the Core Components’ Image component.

Inside the byline folder, create a folder named _cq_design_dialog.

Inside the byline/_cq_design_dialog, create a file named .content.xml. Update the file with the following: with the following XML. It is easiest to open up the .content.xml and copy/paste the XML below into it.

<?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="Byline"
    sling:resourceType="cq/gui/components/authoring/dialog">
    <content
            jcr:primaryType="nt:unstructured">
        <items jcr:primaryType="nt:unstructured">
            <tabs
                    jcr:primaryType="nt:unstructured">
                <items jcr:primaryType="nt:unstructured">
                    <properties
                            jcr:primaryType="nt:unstructured">
                        <items jcr:primaryType="nt:unstructured">
                            <content
                                    jcr:primaryType="nt:unstructured">
                                <items jcr:primaryType="nt:unstructured">
                                    <decorative
                                            jcr:primaryType="nt:unstructured"
                                            sling:hideResource="{Boolean}true"/>
                                    <altValueFromDAM
                                            jcr:primaryType="nt:unstructured"
                                            sling:hideResource="{Boolean}true"/>
                                    <titleValueFromDAM
                                            jcr:primaryType="nt:unstructured"
                                            sling:hideResource="{Boolean}true"/>
                                    <displayCaptionPopup
                                            jcr:primaryType="nt:unstructured"
                                            sling:hideResource="{Boolean}true"/>
                                    <disableUuidTracking
                                            jcr:primaryType="nt:unstructured"
                                            sling:hideResource="{Boolean}true"/>
                                </items>
                            </content>
                        </items>
                    </properties>
                    <features
                            jcr:primaryType="nt:unstructured">
                        <items jcr:primaryType="nt:unstructured">
                            <content
                                    jcr:primaryType="nt:unstructured">
                                <items jcr:primaryType="nt:unstructured">
                                    <accordion
                                            jcr:primaryType="nt:unstructured">
                                        <items jcr:primaryType="nt:unstructured">
                                            <orientation
                                                    jcr:primaryType="nt:unstructured"
                                                    sling:hideResource="{Boolean}true"/>
                                            <crop
                                                    jcr:primaryType="nt:unstructured"
                                                    sling:hideResource="{Boolean}true"/>
                                        </items>
                                    </accordion>
                                </items>
                            </content>
                        </items>
                    </features>
                </items>
            </tabs>
        </items>
    </content>
</jcr:root>

The basis for the preceding Policy dialog XML was obtained from the Core Components Image component.

Like in the Dialog configuration, Sling Resource Merger is used to hide irrelevant fields that are otherwise inherited from the sling:resourceSuperType, as seen by the node definitions with sling:hideResource="{Boolean}true" property.

Synchronize the changes in ui.apps with your IDE or using your Maven skills.

Navigate to the LA Skateparks folder in AEM Assets: http://localhost:4502/assets.html/content/dam/wknd/en/magazine/la-skateparks.

Upload the head shot for stacey-roswells.jpg to the folder.

Navigate to the LA Skatepark article at: http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html

From the left sidebar, drag and drop a Byline component on to bottom of the Layout Container of the opened article page.

Ensure that the left sidebar is open and visible, and the Asset Finder** is selected.

Select the Byline component placeholder, which in turn displays the action bar and tap the wrench icon to open the dialog.

With the dialog open, and the first tab (Asset) active, open the left sidebar, and from the asset finder, drag an image into the Image drop-zone. Search for “stacey” to find Stacey Roswells bio picture provided in the WKND ui.content package.

After adding an image, click on the Properties tab to enter the Name and Occupations.

When entering occupations, enter them in reverse alphabetical order so the alphabetizing business logic that is implemented in the Sling Model is verified.

Tap the Done button in the bottom right to save the changes.

AEM authors configure and author components via the dialogs. At this point, in the development of the Byline component the dialogs are included for collecting the data, however the logic to render the authored content has not yet been added. Therefore only the placeholder shows up.

After saving the dialog, navigate to CRXDE Lite and review how the component’s content is stored on the byline component content node under the AEM page.

Find the Byline component content node beneath the LA Skate Parks page, i.e /content/wknd/us/en/magazine/guide-la-skateparks/jcr:content/root/container/container/byline.

Notice the property names name, occupations, and fileReference are stored on the byline node.

Also, notice the sling:resourceType of the node is set to wknd/components/content/byline which is what binds this content node to the Byline component implementation.

Open the pom.xml file beneath <src>/aem-guides-wknd/core/pom.xml.

Find the dependency for aem-sdk-api - AEM as a Cloud Service Only

<dependency>
    <groupId>com.adobe.aem</groupId>
    <artifactId>aem-sdk-api</artifactId>
</dependency>

The aem-sdk-api contains all public Java™ APIs exposed by AEM. The aem-sdk-api is used by default when building this project. The version is maintained in the Parent reactor pom from the root of the project at aem-guides-wknd/pom.xml.

Find the dependency for the uber-jar - AEM 6.5/6.4 Only

...
    <dependency>
        <groupId>com.adobe.aem</groupId>
        <artifactId>uber-jar</artifactId>
        <classifier>apis</classifier>
    </dependency>
...

The uber-jar is only included when the classic profile is invoked, i.e mvn clean install -PautoInstallSinglePackage -Pclassic. Again, this is unique to this project. In a real-world project, generated from the AEM Project Archetype the uber-jar is the default if the version of AEM specified is 6.5 or 6.4.

The uber-jar contains all public Java™ APIs exposed by AEM 6.x. The version is maintained in the Parent reactor pom from the root of the project aem-guides-wknd/pom.xml.

Find the dependency for core.wcm.components.core:

 <!-- Core Component Dependency -->
    <dependency>
        <groupId>com.adobe.cq</groupId>
        <artifactId>core.wcm.components.core</artifactId>
    </dependency>

This is the complete public Java™ APIs exposed by AEM Core Components. AEM Core Components is a project maintained outside of AEM and therefore has a separate release cycle. For this reason, it is a dependency that needs to included separately and is not included with the uber-jar or aem-sdk-api.

Like the uber-jar, the version for this dependency is maintained in the Parent reactor pom file from aem-guides-wknd/pom.xml.

Later in this tutorial the Core Component Image class is used to display the image in the Byline component. It is necessary to have the Core Component dependency in order to build and compile the Sling Model.

Inside, the core module within the core/src/main/java/com/adobe/aem/guides/wknd/core/models folder create a file named Byline.java

Update Byline.java with the following methods:

package com.adobe.aem.guides.wknd.core.models;

import java.util.List;

/**
* Represents the Byline AEM Component for the WKND Site project.
**/
public interface Byline {
    /***
    * @return a string to display as the name.
    */
    String getName();

    /***
    * Occupations are to be sorted alphabetically in a descending order.
    *
    * @return a list of occupations.
    */
    List<String> getOccupations();

    /***
    * @return a boolean if the component has enough content to display.
    */
    boolean isEmpty();
}

The first two methods expose the values for the name and occupations for the Byline component.

The isEmpty() method is used to determine if the component has any content to render or if it is waiting to be configured.

Notice there is no method for the Image; this is reviewed later.

Java™ packages that contain public Java™ classes, in this case a Sling Model, must be versioned using the package’s package-info.java file.

Since the WKND source’s Java™ package com.adobe.aem.guides.wknd.core.models declares version of 1.0.0, and a non-breaking public interface and methods are being added, the version must be increased to 1.1.0. Open the file at core/src/main/java/com/adobe/aem/guides/wknd/core/models/package-info.java and update @Version("1.0.0") to @Version("2.1.0").

@Version("2.1.0")
package com.adobe.aem.guides.wknd.core.models;

import org.osgi.annotation.versioning.Version;

Create a folder named impl beneath core/src/main/java/com/adobe/aem/guides/core/models.

In the impl folder, create a file BylineImpl.java.

Open BylineImpl.java. Specify that it implements the Byline interface. Use the auto-complete features of the IDE or manually update the file to include the methods needed to implement the Byline interface:

package com.adobe.aem.guides.wknd.core.models.impl;
import java.util.List;
import com.adobe.aem.guides.wknd.core.models.Byline;

public class BylineImpl implements Byline {

    @Override
    public String getName() {
        // TODO Auto-generated method stub
        return null;
    }

    @Override
    public List<String> getOccupations() {
        // TODO Auto-generated method stub
        return null;
    }

    @Override
    public boolean isEmpty() {
        // TODO Auto-generated method stub
        return false;
    }
}

Add the Sling Model annotations by updating BylineImpl.java with the following class-level annotations. This @Model(..)annotation is what turns the class into a Sling Model.

import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.models.annotations.Model;
import org.apache.sling.models.annotations.DefaultInjectionStrategy;
...
@Model(
        adaptables = {SlingHttpServletRequest.class},
        adapters = {Byline.class},
        resourceType = {BylineImpl.RESOURCE_TYPE},
        defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
)
public class BylineImpl implements Byline {
    protected static final String RESOURCE_TYPE = "wknd/components/byline";
    ...
}

Let’s review this annotation and its parameters:

• The @Model annotation registers BylineImpl as a Sling Model when it is deployed to AEM.
• The adaptables parameter specifies that this model can be adapted by the request.
• The adapters parameter allows the implementation class to be registered under the Byline interface. This allows the HTL script to call the Sling Model via the interface (instead of the implementation directly). More details about adapters can be found here.
• The resourceType points to the Byline component resource type (created earlier) and helps to resolve the correct model if there are multiple implementations. More details about associating a model class with a resource type can be found here.

Update the outer div to reference the Byline Sling Model by its public interface:

<div data-sly-use.byline="com.adobe.aem.guides.wknd.core.models.Byline"
    data-sly-use.placeholderTemplate="core/wcm/components/commons/v1/templates.html"
    class="cmp-byline">
    ...
</div>

The Byline name can be added to the component by invoking the getName() method on the Byline Sling Model, or in HTL: ${byline.name}.

Update the h2 tag:

<h2 class="cmp-byline__name">${byline.name}</h2>

To join the list of occupations with ", ", the following code is used:

<p class="cmp-byline__occupations">${byline.occupations @ join=', '}</p>

Update the outer div to save an HTL variable named hasContent:

 <div data-sly-use.byline="com.adobe.aem.guides.wknd.core.models.Byline"
      data-sly-use.placeholderTemplate="core/wcm/components/commons/v1/templates.html"
      data-sly-test.hasContent="${!byline.empty}"
      class="cmp-byline">
      ...
</div>

Note the use of data-sly-test, the HTL test block is key, it both sets an HTL variable and renders/doesn’t render the HTML element it’s on. It is based on the result of the HTL expression evaluation. If “true”, the HTML element renders, else it does not render.

This HTL variable hasContent can now be reused to conditionally show/hide the placeholder.

Update the conditional call to the placeholderTemplate at the bottom of the file with the following:

<sly data-sly-call="${placeholderTemplate.placeholder @ isEmpty=!hasContent}"></sly>

Replace the div with a class of cmp-byline__image with the following:

<div class="cmp-byline__image"
    data-sly-resource="${ '.' @ resourceType = 'core/wcm/components/image/v2/image' }"></div>

This data-sly-resource, includes the current resource via the relative path '.', and forces the inclusion of the current resource (or the byline content resource) with the resource type of core/wcm/components/image/v2/image.

The Core Component resource type is used directly, and not via a proxy, because this is an in-script use, and it’s never persisted to the content.

Completed byline.html below:

<!--/* byline.html */-->
<div data-sly-use.byline="com.adobe.aem.guides.wknd.core.models.Byline"
    data-sly-use.placeholderTemplate="core/wcm/components/commons/v1/templates.html"
    data-sly-test.hasContent="${!byline.empty}"
    class="cmp-byline">
    <div class="cmp-byline__image"
        data-sly-resource="${ '.' @ resourceType = 'core/wcm/components/image/v2/image' }">
    </div>
    <h2 class="cmp-byline__name">${byline.name}</h2>
    <p class="cmp-byline__occupations">${byline.occupations @ join=', '}</p>
</div>
<sly data-sly-call="${placeholderTemplate.placeholder @ isEmpty=!hasContent}"></sly>

Deploy the code base to a local AEM instance. Since changes were made to core and ui.apps both modules need to be deployed.

$ cd aem-guides-wknd/ui.apps
$ mvn clean install -PautoInstallPackage

$ cd ../core
$ mvn clean install -PautoInstallBundle

To deploy to AEM 6.5/6.4 invoke the classic profile:

$ cd ../core
$ mvn clean install -PautoInstallBundle -Pclassic

CAUTION

You could also build the entire project from the root using the Maven profile autoInstallSinglePackage but this may overwrite the content changes on the page. This is because the ui.content/src/main/content/META-INF/vault/filter.xml has been modified for the tutorial starter code to cleanly overwrite the existing AEM content. In a real-world scenario, this is not an issue.

After deploying the update, navigate to the Ultimate Guide to LA Skateparkspage, or wherever you added the Byline component earlier in the chapter.

The image, name, and occupations now appear and an unstyled, but working Byline component is present.

Return to the IDE and the ui.frontend project under /src/main/webpack/components:

Create a file named _byline.scss.

Add the Byline implementations CSS (written as SCSS) into the _byline.scss:

.cmp-byline {
    $imageSize: 60px;

    .cmp-byline__image {
        float: left;

    /* This class targets a Core Component Image CSS class */
    .cmp-image__image {
        width: $imageSize;
        height: $imageSize;
        border-radius: $imageSize / 2;
        object-fit: cover;
        }
    }

    .cmp-byline__name {
        font-size: $font-size-medium;
        font-family: $font-family-serif;
        padding-top: 0.5rem;
        margin-left: $imageSize + 25px;
        margin-bottom: .25rem;
        margin-top:0rem;
    }

    .cmp-byline__occupations {
        margin-left: $imageSize + 25px;
        color: $gray;
        font-size: $font-size-xsmall;
        text-transform: uppercase;
    }
}

Open a terminal and navigate into the ui.frontend module.

Start the watch process with the following npm command:

$ cd ui.frontend/
$ npm run watch

Return to the browser and navigate to the LA SkateParks article. You should see the updated styles to the component.

TIP

You may need to clear the browser cache to ensure stale CSS is not being served, and refresh the page with the Byline component to get the full styled.