Style AEM CIF Core Components style-aem-cif-core-components
The CIF Venia Project is a reference code base for using CIF Core Components. In this tutorial, you inspect the Venia reference project and understand how CSS and JavaScript used by AEM CIF Core components are organized. You also create a style using CSS to update the default style of the Product Teaser component.
What You Will Build
In this tutorial, a new style is implemented for the Product Teaser component that resembles a card. Lessons learned in the tutorial can be applied to other CIF Core Components.
Prerequisites prerequisites
A local development environment is required to complete this tutorial. This environment includes a running instance of AEM that is configured and connected to an Adobe Commerce instance. Review the requirements and steps for setting up a local development with AEM as a Cloud Service SDK.
Clone the Venia Project clone-venia-project
You are going to clone the Venia Project, and then override the default styles.
-
Run the following git command so you can clone the project:
code language-shell $ git clone git@github.com:adobe/aem-cif-guides-venia.git
-
Build and deploy the project to a local instance of AEM:
code language-shell $ cd aem-cif-guides-venia/ $ mvn clean install -PautoInstallPackage,cloud
-
Add the necessary OSGi configurations so you can connect your AEM instance to an Adobe Commerce instance or add the configurations to the created project.
-
At this point, you should have a working version of a storefront that is connected to an Adobe Commerce instance. Navigate to the
US
>Home
page at: http://localhost:4502/editor.html/content/venia/us/en.html.You should see that the storefront currently is using the Venia theme. Expanding the Main Menu of the storefront, you should see various categories, indicating that the connection to Adobe Commerce is working.
Client Libraries and ui.frontend Module introduction-to-client-libraries
The CSS and JavaScript responsible for rendering the theme/styles of the storefront is managed in AEM by a client library or “clientlibs” for short. Client libraries provide a mechanism to organize CSS and JavaScript in a project’s code and then deliver onto the page.
Brand-specific styles can be applied to AEM CIF Core Components by adding and overriding the CSS managed by these client libraries. Understanding how client libraries are structured and included on the page is critical.
The ui.frontend is a dedicated webpack project to manage all front-end assets for a project. This webpack lets front-end developers use any number of languages and technologies like TypeScript, Sass, and much more.
The ui.frontend
module is also a Maven module and integrated with the larger project by using an NPM module the aem-clientlib-generator. During a build, the aem-clientlib-generator
copies the compiled CSS and JavaScript files into a Client Library in the ui.apps
module.
Compiled CSS and JavaScript are copied from the ui.frontend
module into the ui.apps
module as a client library during a Maven build
Update the Teaser Style ui-frontend-module
Next, make a small change to the Teaser style to see how the ui.frontend
module and client libraries work. Use the IDE of your choice to import the Venia project. Screenshots used are from the Visual Studio Code IDE.
-
Navigate and expand the ui.frontend module and expand the folder hierarchy to:
ui.frontend/src/main/styles/commerce
:Notice that there are multiple Sass (
.scss
) files beneath the folder. These files are the Commerce-specific styles for each of the Commerce components. -
Open the file
_productteaser.scss
. -
Update the
.item__image
rule and modify the border rule:code language-scss .item__image { border: #ea00ff 8px solid; /* <-- modify this rule */ display: block; grid-area: main; height: auto; opacity: 1; transition-duration: 512ms; transition-property: opacity, visibility; transition-timing-function: ease-out; visibility: visible; width: 100%; }
The above rule should add a bold pink border to the Product Teaser Component.
-
Open a new terminal window and navigate to the
ui.frontend
folder:code language-shell $ cd <project-location>/aem-cif-guides-venia/ui.frontend
-
Run the following Maven command:
code language-shell $ mvn clean install ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 29.497 s [INFO] Finished at: 2020-08-25T14:30:44-07:00 [INFO] ------------------------------------------------------------------------
Inspect the terminal output. Notice that the Maven command ran several NPM scripts including
npm run build
. Thenpm run build
command is defined in thepackage.json
file and compiles the webpack project and triggers the client library generation. -
Inspect the file
ui.frontend/dist/clientlib-site/site.css
:The file is the compiled and minified version of all the Sass files in the project.
note note NOTE Files like this are ignored from source control since they should be generated during build time. -
Inspect the file
ui.frontend/clientlib.config.js
.code language-js /* clientlib.config.js*/ ... // Config for `aem-clientlib-generator` module.exports = { context: BUILD_DIR, clientLibRoot: CLIENTLIB_DIR, libs: [ { ...libsBaseConfig, name: 'clientlib-site', categories: ['venia.site'], dependencies: ['venia.dependencies', 'aem-core-cif-react-components'], assets: { ...
This configuration file is for aem-clientlib-generator and determines where and how the compiled CSS and JavaScript are transformed into an AEM client library.
-
In the
ui.apps
module, inspect the file:ui.apps/src/main/content/jcr_root/apps/venia/clientlibs/clientlib-site/css/site.css
:This file is
site.css
copied into theui.apps
project. It is now part of a client library namedclientlib-site
with a category ofvenia.site
. Once the file is part of theui.apps
module it can be deployed to AEM.note note NOTE Files like this are also ignored from source control since they should be generated during build time. -
Next inspect the other client libraries generated by the project:
These client libraries are not managed by the
ui.frontend
module. Instead these client libraries include CSS and JavaScript dependencies provided by Adobe. The definition for these client libraries is in the.content.xml
file beneath each folder.clientlib-base - An empty client library that simply embeds the necessary dependencies from AEM Core Components. The category is
venia.base
.clientlib-cif - An empty client library that simply embeds the necessary dependencies from AEM CIF Core Components. The category is
venia.cif
.clientlib-grid - Includes the CSS to enable AEM’s Responsive Grid feature. Using the AEM grid enables Layout Mode in the AEM Editor and gives content authors the ability to resize components. The category is
venia.grid
and is embedded in thevenia.base
library. -
Inspect the files
customheaderlibs.html
andcustomfooterlibs.html
beneathui.apps/src/main/content/jcr_root/apps/venia/components/page
:These scripts include venia.base and venia.cif libraries as a part of all pages.
note note NOTE Only the base libraries are “hard-coded” as part of the page scripts. venia.site
is not included in these files and instead included as part of the page template for greater flexibility. This process is inspected later. -
From the terminal, build and deploy the entire project to a local instance of AEM:
code language-shell $ cd aem-cif-guides-venia/ $ mvn clean install -PautoInstallPackage,cloud
Author a Product Teaser author-product-teaser
Now that the code updates have been deployed, add an instance of the Product Teaser component to the home page of the site using the AEM authoring tools. Do so lets us view the updated styles.
-
Open a new browser tab and navigate to the Home Page of the site: http://localhost:4502/editor.html/content/venia/us/en.html.
-
Expand the Asset finder (the side rail) in Edit mode. Switch the Asset filter to Products.
-
Drag and drop a new Product onto the home page in the main Layout Container:
You should see that the Product Teaser now has a bright pink border based on the CSS rule change created earlier.
Verify Client Libraries on the Page verify-client-libraries
Next verify the inclusion of the client libraries on the page.
-
Navigate to the Home Page of the site: http://localhost:4502/editor.html/content/venia/us/en.html.
-
Select the Page Information menu and click View as Published:
This page opens without any of the AEM author JavaScript loaded, as it would appear on the published site. Notice that the url has the query parameter
?wcmmode=disabled
appended. When developing CSS and JavaScript, it is a good practice to use this parameter to simplify the page without anything from AEM author. -
View the page source and you should be able to identify several client libraries are included:
code language-html <!DOCTYPE html> <html lang="en-US"> <head> ... <link rel="stylesheet" href="/etc.clientlibs/venia/clientlibs/clientlib-base.min.css" type="text/css"> <link rel="stylesheet" href="/etc.clientlibs/venia/clientlibs/clientlib-site.min.css" type="text/css"> </head> ... <script type="text/javascript" src="/etc.clientlibs/venia/clientlibs/clientlib-site.min.js"></script> <script type="text/javascript" src="/etc.clientlibs/core/wcm/components/commons/site/clientlibs/container.min.js"></script> <script type="text/javascript" src="/etc.clientlibs/venia/clientlibs/clientlib-base.min.js"></script> <script type="text/javascript" src="/etc.clientlibs/core/cif/clientlibs/common.min.js"></script> <script type="text/javascript" src="/etc.clientlibs/venia/clientlibs/clientlib-cif.min.js"></script> </body> </html>
Client libraries when delivered to the page are prefixed with
/etc.clientlibs
and are served via a proxy to avoid exposing anything sensitive in/apps
or/libs
.Notice
venia/clientlibs/clientlib-site.min.css
andvenia/clientlibs/clientlib-site.min.js
. These files are the compiled CSS and JavaScript files derived from theui.frontend
module.
Client Library Inclusion with Page Templates client-library-inclusion-pagetemplates
There are several options for how to include a client-side library. Next inspect how the generated project includes the clientlib-site
libraries via Page Templates.
-
Navigate to the Home Page of the site within the AEM Editor: http://localhost:4502/editor.html/content/venia/us/en.html.
-
Select the Page Information menu and click Edit Template:
The Landing Page template is opened that the Home page is based on.
note note NOTE To view all available templates from the AEM Start screen, navigate to Tools > General > Templates. -
In the upper left-hand corner, select the Page Information icon and click Page Policy.
-
The Page Policy is opened for the Landing Page template:
On the right-hand side, you can see a listing of Client Libraries categories that are included on all pages that use this template.
venia.dependencies
- Provides any vendor libraries thatvenia.site
depends on.venia.site
- The category forclientlib-site
that theui.frontend
module generates.
Notice that other templates use the same policy, Content Page, Landing Page, and so on. By reusing the same policy, it ensures that the same client libraries are included on all pages.
The advantage of using Templates and Page policies to manage the inclusion of client libraries is that you can change the policy per template. For example, perhaps you are managing two different brands within the same AEM instance. Each brand has its own unique style or theme but the base libraries and code are the same. Another example, if you had a larger client library that you only wanted to appear on certain pages, you could make a unique page policy just for that template.
Local Webpack Development local-webpack-development
In the previous exercise, an update was made to a Sass file in the ui.frontend
module and then after performing a Maven build the changes are deployed to AEM. Next, you look at using a webpack-dev-server to rapidly develop the front-end styles.
The webpack-dev-server proxies images and some of the CSS/JavaScript from the local instance of AEM but allows the developer to modify the styles and JavaScript in the ui.frontend
module.
-
In the browser navigate to the Home page and View as Published: http://localhost:4502/content/venia/us/en.html?wcmmode=disabled.
-
View the source of the page and the copy the raw HTML of the page.
-
Return to the IDE of your choice beneath the
ui.frontend
module open the file:ui.frontend/src/main/static/index.html
-
Overwrite the contents of
index.html
and paste the HTML copied in the previous step. -
Find the “includes” for
clientlib-site.min.css
,clientlib-site.min.js
, and remove them.code language-html <head> <!-- remove this link --> <link rel="stylesheet" href="/etc.clientlibs/venia/clientlibs/clientlib-base.min.css" type="text/css"> ... </head> <body> ... <!-- remove this link --> <script type="text/javascript" src="/etc.clientlibs/venia/clientlibs/clientlib-site.min.js"></script> </body>
These “includes” are removed because they represent the compiled version of the CSS and JavaScript generated by the
ui.frontend
module. Leave the other client libraries as they are going to be proxied from the running AEM instance. -
Open a new terminal window and navigate into the
ui.frontend
folder. Run the commandnpm start
:code language-shell $ cd ui.frontend $ npm start
This command starts the webpack-dev-server on http://localhost:8080/
note caution CAUTION If you get a Sass related error, stop the server and run the command npm rebuild node-sass
and repeat the above steps. This error can occur if you have a different version ofnpm
andnode
than specified in the projectaem-cif-guides-venia/pom.xml
. -
Navigate to the http://localhost:8080/ in a new tab with the same browser as a logged in instance of AEM. You should see the Venia home page via the webpack-dev-server:
Leave the webpack-dev-server running. It is used in the next exercise.
Implement Card style for Product Teaser update-css-product-teaser
Next modify the Sass files in the ui.frontend
module to implement a card-like style for the Product Teaser. The webpack-dev-server is used to rapidly see the changes.
Return to the IDE and the generated project.
-
In the ui.frontend module, reopen the file
_productteaser.scss
atui.frontend/src/main/styles/commerce/_productteaser.scss
. -
Make the following changes to the Product Teaser border:
code language-diff .item__image { - border: #ea00ff 8px solid; + border-bottom: 1px solid #c0c0c0; display: block; grid-area: main; height: auto; opacity: 1; transition-duration: 512ms; transition-property: opacity, visibility; transition-timing-function: ease-out; visibility: visible; width: 100%; }
Save the changes and the webpack-dev-server should automatically refresh with the new styles.
-
Add a drop-shadow and include rounded corners to the Product Teaser.
code language-scss .item__root { position: relative; box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2); transition: 0.3s; border-radius: 5px; float: left; margin-left: 12px; margin-right: 12px; } .item__root:hover { box-shadow: 0 8px 16px 0 rgba(0,0,0,0.2); }
-
Update the Product’s name to appear at the bottom of the teaser and modify the text color.
code language-css .item__name { color: #000; display: block; float: left; font-size: 22px; font-weight: 900; line-height: 1em; padding: 0.75em; text-transform: uppercase; width: 75%; }
-
Update the Product’s price to also appear in the bottom of the teaser and modify the text color.
code language-css .price { color: #000; display: block; float: left; font-size: 18px; font-weight: 900; padding: 0.75em; padding-bottom: 2em; width: 25%; ...
-
Update the media query at the bottom, so you can stack the name and price in screens smaller than 992px.
code language-css @media (max-width: 992px) { .productteaser .item__name { font-size: 18px; width: 100%; } .productteaser .item__price { font-size: 14px; width: 100%; } }
You should now see the card-style reflected in the webpack-dev-server:
However, the changes have not been deployed to AEM yet. You can download the solution file here.
-
Deploy the updates to AEM using your Maven skills, from a command-line terminal:
code language-shell $ cd aem-cif-guides-venia/ $ mvn clean install -PautoInstallPackage,cloud
note note NOTE There are additional IDE Setup and Tools that can sync project files directly to a local AEM instance without having to perform a full Maven build.
View Updated Product Teaser view-updated-product-teaser
After the code for the project has been deployed to AEM, you should now be able to see the changes to the Product Teaser.
-
Return to your browser and refresh the Home page: http://localhost:4502/editor.html/content/venia/us/en.html. You should see the updated product teaser styles applied.
-
Experiment by adding additional Product teasers. Use Layout Mode to change the width and offset of the components to display multiple teasers in a row.
Troubleshooting troubleshooting
You can verify in CRXDE-Lite that the updated CSS file has been deployed: http://localhost:4502/crx/de/index.jsp#/apps/venia/clientlibs/clientlib-site/css/site.css
When deploying new CSS files, or JavaScript files, or both, it is also important to ensure that the browser is not serving stale files. You can eliminate this potential issue by clearing the browser cache or starting a fresh browser session.
AEM also attempts to cache client libraries for performance. Occasionally, following a code deployment the older files are served. You can manually invalidate AEM’s client library cache using the Rebuild Client Libraries tool. Invalidate Caches is the preferred method if you suspect AEM has cached an old version of a client library. Rebuild Libraries is inefficient and time consuming.
Congratulations congratulations
You finished styling your first AEM CIF Core Component and you used a webpack dev server!
Bonus Challenge bonus-challenge
Use the AEM Style system to create two styles that can be toggled on or off by a content author. Developing with the Style System includes detailed steps and information on how to accomplish this task.