Getting Started with AEM Sites Chapter 4 - Developing with the Style System

Covers using the Style System to extend Core Components with brand-specific CSS and advanced policy configurations of the Template Editor. Content Fragments are also integrated to create long form article text.

This is Chapter 4 of the multi-part tutorial. Chapter 3 can be found here and an overview can be found here.

You can check out the finished code on GitHub or you can download the solution package:

Download

Obter arquivo

WKND Solution Package (Chapters 1-8)

In this chapter we will use the Style System feature and Editable Templates to create a unified look and feel for the Article Template. To start, we will identify areas of the article mockup that will map to AEM components.

Breadcrumb

Configurable start level
Option to show hidden navigation items
Exclude the current page from the breadcrumb

Content Fragment

Allow for article text (copy) to be created and managed independently of a page
Promotes reuse and variations for cross-channel

Image

Smart loading of optimal rendition
In-place editing, cropping, rotating, and resizing
Image title, description, accessibility text and link

List

Multiple sources:
- List page children
- List tagged items
- List query result
- List static items
Ordering, pagination and limit
Styles

Text

In-place editing
Rich Text authoring

Title

In-place editing
Use the Page title with option to override the text

The Core Components provide all the above functionality. We will focus on styling the components to match the mockups.

The Style System allows developers and template editors to create multiple visual variations of a component. Authors can then in turn decide which style to use when composing a page. We will leverage the Style System throughout the rest of the tutorial to achieve several unique styles, while leveraging Core Components in a low code approach.

The general idea with the Style System is that authors can choose various styles of how a component should look. The "styles" are backed by additional CSS classes that are injected into the outer div of a component. In the client libraries CSS rules are added based on these style classes so that the component changes appearance.

You can find detailed documentation for Style System here. There is also a great video overview for using the Style System.

At this point the Title Component has been proxied into the project under /apps/wknd/components/content/title. We will add styles for the Title Component in the clientlib-site library: /apps/wknd/clientlibs/clientlib-site/components

The mockups contain a unique style for the Title component with an underline. Instead of creating 2 components or modifying the component dialog, the Style System can be used to allow authors the option to add an underline style.

Observação:

It is considered a best practice to always tightly scope styles to the target component. This ensures that extra styles don't affect other areas of the page.

All Core Components adhere to BEM notation. It is a best practice to target the outer CSS class when creating a default style for a component. Another best practice is to target class names specified by the Core Component BEM notation rather than HTML elements.

Title Component BEM Notation

BLOCK cmp-title
    ELEMENT cmp-title__text

In the previous chapter, some default styles were imported for the Title component. In the ui.apps module beneath /apps/wknd/clientlibs/clientlib-site/components/title. There is currently a default style defined by default.less:

/* WKND Title Default style */
 
.cmp-title {
     
    h1, h2, h3, h4 {
        font-family: @font-family-serif;
    }

    h1 {
        font-size: 48px;

        @media (max-width: @screen-medium) {
            font-size: @font-size-h1;
        }
    }
    
}

Create a file named underline.less beneath the styles folder in the previous step: /apps/wknd/clientlibs/clientlib-site/components/title/styles/underline.less

Add the following code:

/* WKND Title Underline style */

.cmp-title--underline {
	
	.cmp-title {
		.cmp-title__text {
			&:after {
			display: block;
		    width: 84px;
		    padding-top: 8px;
		    content: '';
		    border-bottom: 2px solid @brand-primary;
			}
		}
	}
}

This will add a partial underline beneath the title component with the WKND's brand primary color (yellow).

Update /apps/wknd/clientlibs/clientlib-site/components/title/title.less with the following code to inculde the default and underline styles:

/* WKND Title Styles */

@import (once) "styles/default.less";
@import (once) "styles/underline.less";

Deploy the updated code base to a local AEM instance.

In AEM navigate to the Article Page Template:

http://localhost:4502/editor.html/conf/wknd/settings/wcm/templates/article-page-template/structure.html

Click the Title Component in the Layout Container to open its policy configuration:

Update the Policy with the following values:

Policy Title * : WKND Title - Article

Properties > Sizes > Check all sizes

Properties > Styles Tab > Add a new style

Underline : cmp-title--underline

Notice how cmp-title--underline added in the template policy matches top level CSS class rule specified in the underline.less file.

You should now be able to add a new Title component to the a page and then apply the Underline style to the component. Navigate to: http://localhost:4502/editor.html/content/wknd/en/first-article-page.html

View the HTML source of the Title Component when no style is applied:

<div class="title aem-GridColumn aem-GridColumn--default--12">
    <div class="cmp-title">
        <h2 class="cmp-title__text">New paragraph</h2>
    </div>
</div>

HTML source of the Title component when the Underline style is applied:

<div class="title cmp-title--underline aem-GridColumn aem-GridColumn--default--12">
    <div class="cmp-title">
        <h2 class="cmp-title__text">New paragraph</h2>
    </div>
</div>

Note that CSS classes applied through the Style System always populate the outer div surrounding the component.

Next we will add some additional styles to the text component so that authors are able to create a Quote Block style, in addition to standard article text.

Text Component BEM Notation

BLOCK cmp-text
    ELEMENT cmp-text__paragraph (only present if text is NOT Rich Text)

Beneath /apps/wknd/clientlibs/clientlib-site/components/text/styles create a new file named quote.less.

Populate /apps/wknd/clientlibs/clientlib-site/components/text/styles/quote.less with the following:

/* WKND Text Quote style */

.cmp-text--quote {

     	background-color:@brand-secondary;
   	 	padding: 1em 3em;
    	margin: 1em 0em;
   	 	
   	 	blockquote {
   	 		margin: 0;
   	 		font-size: 36px;
   	 		border: none;
   	 		padding: 14px 0px;
   	 	}
   	 	
   	 	u {
   	 		text-decoration: none;
   	 		font-family: @font-family-sans-serif;
   	 		&:before {
                border-top: 2px solid @brand-primary;
                content: '';
                display: block;
                width: 80px;
   	 		}
   	 	}
}

Update /apps/wknd/clientlibs/clientlib-site/components/text/text.less to include the default.less and quote.less files:

/* WKND Text Styles */


@import (once) "styles/default.less";
@import (once) "styles/quote.less";

Deploy the updated Text LESS to AEM

In AEM navigate to the Article Page Template:

http://localhost:4502/editor.html/conf/wknd/settings/wcm/templates/article-page-template/structure.html

Click the Text Component in the Layout Container to open its policy configuration. Configure the following:

Policy Title * = WKND Text - Article
Plugins > Formatting > Check Show underline option
Plugins > Paragraph Styles > Check Enable paragraph styles. Remove all elements except for Paragraph and Quote
Styles > Add a new Style named Quote Block with a value of cmp-text--quote

Navigate to a page and create a new text component:

Edit the text component (pencil icon)
Expand the RTE to full screen
Use the Paragraph dropdown to create a Block Quote and add a famous quote.
On a new line below the Block Quote create a paragraph element and add the name of the author
Apply the Underline RTE style to the Author Name
Save changes
Change the Style to Quote Block style

The List component as offered from the Core Component will be used to populate an Up Next list of articles. A List component will also be made a fixed part of the Article Page Template to promote consistency across Article Pages. The List component can be used for other parts of the site so a unique style will be created for the Up Next variation.

List BEM Notation:

BLOCK cmp-list
    ELEMENT cmp-list__item
    ELEMENT cmp-list__item-link
    ELEMENT cmp-list__item-title
    ELEMENT cmp-list__item-date

Beneath /apps/wknd/clientlibs/clientlib-site/components:

Create a new folder named list
Create a new file named list.less
Create a new folder named styles beneath the list folder
In the styles folder create a file named default.less
In the styles folder create a file named upnext.less

Populate default.less with the following:

/* WKND List Default Style */
     
     
.cmp-list {
     
    float:left;
    padding:0;
     
    .cmp-list__item {
        list-style: none;
        float:left;
        width:100%;
        margin-bottom:1em;
    }
     
    .cmp-list__item-link {
        font-weight: 600;
        float:left;
        padding: 0.5rem 1rem;
         
        &:hover {
            background: @brand-secondary;
        }
    }
     
    .cmp-list__item-title {
        width:100%;
        float:left;
    }
     
    .cmp-list__item-date {
        width:100%;
        float:left;
        color: @gray-light;
        font-size: @font-size-small; 
    }
     
}

Populate upnext.less with the following:

/* WKND List Up Next Style */
     
.cmp-list--upnext {
     
    .cmp-list {
             
            padding-left: 0em;
             
            .cmp-list__item {
                list-style: none;
                float:left;
                width:100%; 
                margin-bottom:1em;
            }
             
            .cmp-list__item-link {
                font-weight: normal;
                height: 120px;
                border-left: 6px solid @brand-secondary;
                 
                &:hover {
                    background: @brand-primary;
                    border-color: @text-color;
                }
                 
            }
             
            .cmp-list__item-title {
                color: @text-color;
                padding: 5px;
                text-transform: uppercase;
                 
            }
             
            .cmp-list__item-date {
                color: @gray-light;
                font-size: @font-size-xsmall; 
                padding: 5px;
                text-transform: uppercase;
            }
             
        }
}

Update list.less with the following to include the default and upnext styles:

/* WKND List Styles */

@import (once) "styles/default.less";
@import (once) "styles/upnext.less";

Update main.less to import list.less

Add a line to /apps/wknd/clientlibs/clientlib-site/main.less file to import the list.less file:

/* Component Styles */
@import "components/breadcrumb/breadcrumb.less";
@import "components/contentfragment/contentfragment.less";
@import "components/header/header.less";
@import "components/image/image.less";
@import "components/layout-container/layout-container.less";
/* add list.less */
@import "components/list/list.less";
@import "components/text/text.less";
@import "components/title/title.less";

Deploy code to AEM

In AEM navigate to the Article Page Template:

http://localhost:4502/editor.html/conf/wknd/settings/wcm/templates/article-page-template/structure.html

Click the policy icon for the List Component in the Layout Container to open its policy configuration. Configure the following:

Policy Title * = WKND List - Article
List Settings > Date Format > EEEE, d MMM y
Styles > Add a new Style named Up Next with a value of cmp-list--upnext

Navigate to a page and add a List Component

Drag + Drop a List Component on to the page
Click the wrench icon to configure the List component
List Settings > Build List Using > Fixed List
1. Under Options for Fixed List > Add a couple of pages
Item Settings > Check Link Items, Show date

Several dynamic sources can be configured for the List component including:

Child pages
Tagged items
Query results.

Full configuration details can be found in the List Component README.

Toggle List Styles

At this point, you may have noticed that the "body" of the Article template is spanning the full width of the page. The Layout Container, which we configued in Chapter 2, represents the body of the article and is used to allow authors to add components. We can use the Style System with the Layout Container to create a new, fixed-width style to restrict the body of the pages.

Beneath /apps/wknd/clientlibs/clientlib-site/components perform the following tasks to create a new structure to contain Layout Container styles:

Create a new folder named: layout-container.
Beneath this folder create a file named: layout-container.less
Beneath the layout-container folder create a new folder named: styles.
In the styles folder create a file named fixed-width.less

Populate fixed-width.less with the following:

/* WKND Layout Container - fixed-width.less */

.cmp-layout-container--fixed {
  display:block;
  max-width:  @max-width !important;
  float: unset !important;
  margin: 0 auto !important;
  padding: 0 @gutter-padding;
  clear: both !important; 

  @media (max-width: @screen-medium) {
    padding: 0 !important;
  }
  
}

The above snippet will center and restrict the Layout Container, that has a class of .cmp-layout-container--fixed to a max-width using a LESS variable, @max-width. This variable is defined in the variables.less file and is set to: 1164px.

Populate layout-container.less with the following:

/* WKND Layout Container Styles */

@import (once) "styles/fixed-width.less";

Next update /apps/wknd/clientlibs/clientlib-site/main.less to include the layout-container.less file:

Update main.less with the following:

/* Component Styles */
@import "components/breadcrumb/breadcrumb.less";
@import "components/contentfragment/contentfragment.less";
@import "components/header/header.less";
@import "components/image/image.less";
/* add import of layout-container.less */
@import "components/layout-container/layout-container.less";
@import "components/text/text.less";
@import "components/title/title.less";

Deploy code to AEM

If you have been editing the code base within Eclipse or another IDE, deploy the code to AEM.

In AEM navigate to the Article Page Template:

http://localhost:4502/editor.html/conf/wknd/settings/wcm/templates/article-page-template/structure.html

Click the Layout Container Component and then click it's policy icon to open up the Layout Container policy dialog:

The current policy title is WKND Content.

Update the Styles tab:

Styles > Add a new Style named Default with no value
Styles > Add a new Style named Fixed Width with a value: cmp-layout-container--fixed

Finally, test out the Fixed Width style on the layout container.

Cuidado:

If you view a page created by the Article Template, you might notice that the page's Layout Container does not have a fixed width. At the end of this chapter we will make some large updates to the Article Template to ensure that all pages created from this template has a fixed width.

For the article body we will leverage AEM Content Fragments. Content Fragments are de-coupled from the presentation layer and promote reuse of content across channels. The editorial UI of Content Fragments lends itself to working with large amounts of text. We will add a component to the WKND application to be able to reference Content Fragments into an article page. To view an overview of Content Fragments click here.

Update aem-guides-wknd/pom.xml to include Core Components Extension dependency

The Content Fragment component is a separate module of AEM Core Components. The paren pom.xml must be updated to ensure it is available on AEM.

Add the following dependency to aem-guides-wkn/pom.xml:

//pom.xml

...
<dependencies>
...
<dependency>
    <groupId>com.adobe.cq</groupId>
    <artifactId>core.wcm.components.extension</artifactId>
    <type>zip</type>
    <version>1.0.6</version>
</dependency>
...
</dependencies>

Update aem-guides-wknd/ui.apps/pom.xml to include Core Components Extension as a sub package

Make the following updates to the ui.apps/pom.xml:

// ui.apps/pom.xml

...

<dependencies>
...
    <dependency>
        <groupId>com.adobe.cq</groupId>
	<artifactId>core.wcm.components.extension</artifactId>
	<type>zip</type>
    </dependency>
...
</dependencies>

// ui.apps/pom.xml

<plugins>
...
<!-- ====================================================================== -->
            <!-- V A U L T   P A C K A G E   P L U G I N S                              -->
            <!-- ====================================================================== -->
            <plugin>
                <groupId>org.apache.jackrabbit</groupId>
                <artifactId>filevault-package-maven-plugin</artifactId>
                <extensions>true</extensions>
                <configuration>
                    <embeddeds>
                        <embedded>
                            <groupId>com.adobe.aem.guides</groupId>
                            <artifactId>aem-guides-wknd.core</artifactId>
                            <target>/apps/wknd/install</target>
                        </embedded>
                    </embeddeds>
                    <subPackages>
                        <subPackage>
                            <groupId>com.adobe.cq</groupId>
                            <artifactId>core.wcm.components.all</artifactId>
                            <filter>true</filter>
                        </subPackage>
                        <subPackage>
                        	<groupId>com.adobe.cq</groupId>
				<artifactId>core.wcm.components.extension</artifactId>
            			<filter>true</filter>
                        </subPackage>
                    </subPackages>
                </configuration>
            </plugin>
...
</plugins>

Proxy Core Component Content Fragment component

There is a Content Fragment reference component in AEM Core Components. It was not included automatically by the AEM project archetype. Manually proxy the component into the WKND code base.

Create a cq:Component node named contentfragment beneath /apps/wknd/components/content.

Add the following properties to the node:

Name	Type	Value
componentGroup	String	WKND.Content
jcr:description	String	Displays content from a referenced Content Fragment
jcr:title	String	Content Fragment
jcr:primaryType	Name	cq:Component
sling:resourceSuperType	String	core/wcm/extension/components/contentfragment/v1/contentfragment
cq:isContainer	Booean	true

<?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"
    cq:isContainer="{Boolean}true"
    jcr:primaryType="cq:Component"
    componentGroup="WKND.Content"
    sling:resourceSuperType="core/wcm/extension/components/contentfragment/v1/contentfragment"
    jcr:title="Content Fragment"
    jcr:description="Displays content from a referenced Content Fragment"/>

View styles for the Content Fragment component

In the previous chapter, as part of the import, some default styles for the Content Fragment component were included beneath /apps/wknd/clientlibs/clientlib-site/components/contentfragment :

/* WKND Content Fragment style - default.less */

.cmp-contentfragment {
	
	font-family: @font-family-serif;
	
    p {
    	text-align: justify;
    	font-size: 20px;
    	line-height: (@line-height-base + 1);
    }
}

Deploy the code base to a local AEM instance. Since major changes were made to the POM files, perform a full Maven build from the project's root directory:

$ cd aem-guides-wknd
$ mvn -PautoInstallPackage -Padobe-public clean install

Notice that in Package Manager two additional packages are installed for the Content Fragment extension:

Enable the Content Fragment by updating the Layout Container Policy

Navigate to the Article Page Template: http://localhost:4502/editor.html/conf/wknd/settings/wcm/templates/article-page-template/structure.html
Select the main Layout Container and click its Policy Icon
Update the Allowed Components to include the Content Fragment component under WKND.Content

Add Content Fragment to a Page

The Content Fragment component should now be enabled and allowed to be added to a page.

Empty Content Fragment component added to a page.

Author a Content Fragment (optional)

You can create a new Content Fragment by navigating to http://localhost:4502/assets.html/content/dam and clicking the Create button > Content Fragment from the dropdown. More information about authoring Content Fragments.

Content Fragment author UI.

Reference Content Fragment on the Page

Navigate back to the content page in which the Content Fragment component was added (Step 4). Click the Wrench icon to bring up the dialog. Using the path finder you can navigate and select an existing content fragment from the DAM. Optionally you can use the Asset Finder filter to restict the assets to only Content Fragments and Drag+Drop one of the Content Fragments on to the component.

Editing the Content Fragment component dialog to reference a content fragment.

You will notice that each paragraph of the Content Fragment has a drop-zone to embed additional components within the Content Fragment. You will also notice that the content of the Content Fragment is read-only. This is by design so that the Content Fragment can only be updating by editing the original fragment.

Now that we have some more components to work with we can start to add some more structure to our Article Template. The powerful feature of Editable Templates is the flexibility to make some components of the page fixed and standard across all pages, while making other components editable at the page level. It is important to find a balance between what is editable at the page level and what needs to be managed at the template level.

Below is a diagram of the Article Template sliced into what is fixed, fixed and unlocked and what is fully editable.

Article Template component architecture

The following videos show how we can implement the above requirements with AEM's Template Editor and then author an article page:

If you get stuck or have additional questions make sure to check out the Experience League forums for AEM or view existing GitHub issues.

Didn't find what you were looking for? Think you found an error? Please file a GitHub issue for the WKND project.

Next part in the tutorial:

Getting Started with AEM Sites Chapter 5 - Navigation and Search
View the finished code on GitHub or download the finished package for this part of the tutorial:

Download

Obter arquivo

WKND Solution Package (Chapters 1-8)

As publicações do Twitter™ e do Facebook não são cobertas pelos termos do Creative Commons.

Avisos legais | Política de privacidade online

Getting Started with AEM Sites Chapter 4 - Developing with the Style System

Prerequisites

Article Template Planning

Style System

Title Component

Text Component

List Component

Layout Container

Content Fragment Component

Putting It Together

Help!

Next Steps

Pergunte à comunidade

Fale conosco