Client libraries and front-end workflow client-side-libraries

Check out the tutorial/client-side-libraries-start branch from GitHub

$ cd aem-guides-wknd
$ git checkout tutorial/client-side-libraries-start

Deploy code base to a local AEM instance using your Maven skills:

$ mvn clean install -PautoInstallSinglePackage

$ mvn clean install -PautoInstallSinglePackage -Pclassic

Using VSCode or other IDE open up the ui.apps module.

Expand the path /apps/wknd/clientlibs to view the clientlibs generated by the archetype.

In the below section, these clientlibs are reviewed in greater details.

The following table summarizes the client libraries. More details about including Client Libraries can be found here.

Observe that clientlib-site and clientlib-dependencies are ignored from source control. This is by design, since these are generated at build time by the ui.frontend module.

Open up the ui.frontend module and navigate to src/main/webpack/site.

Open the file main.scss

main.scss is the entry point to the Sass files in the ui.frontend module. It includes the _variables.scss file, which contains a series of brand variables to be used throughout different Sass files in the project. The _base.scss file is also included and defines some basic styles for HTML elements. A regular expression includes the styles for individual components styles under src/main/webpack/components. Another regular expression includes the files under src/main/webpack/site/styles.

Inspect the file main.ts. It includes main.scss and a regular expression to collect any .js or .ts files in the project. This entry point is used by the webpack configuration files as the entry point for the entire ui.frontend module.

Inspect the files beneath src/main/webpack/site/styles:

These files styles for global elements in the template, like the Header, Footer and main content container. The CSS rules in these files target different HTML elements header, main, and footer. These HTML elements were defined by policies in the previous chapter Pages and Templates.

Expand the components folder under src/main/webpack and inspect the files.

Each file maps to a Core Component like the Accordion Component. Each Core Component is built with Block Element Modifier or BEM notation to make it easier to target specific CSS classes with style rules. The files beneath /components have been stubbed out by the AEM Project Archetype with the different BEM rules for each component.

Download the WKND Base Styles wknd-base-styles-src-v3.zip and unzip the file.

To accelerate the tutorial, several Sass files that implement the WKND brand based on Core Components and the structure of the Article Page Template is provided.

Overwrite the contents of ui.frontend/src with files from the previous step. The contents of the zip should overwrite the following folders:

/src/main/webpack
         /components
         /resources
         /site
         /static

Inspect the changed files to see details of the WKND style implementation.

Open a command-line terminal and install the ui.frontend module using the npm install command:

$ cd ~/code/aem-guides-wknd/ui.frontend
$ npm install

Open ui.frontend/package.json and in the scripts start command add --env writeToDisk=true.

{
  "scripts": {
    "start": "webpack-dev-server --open --config ./webpack.dev.js --env writeToDisk=true",
  }
}

Start the webpack dev server in watch mode by running the following command:

$ npm run watch

This compiles the source files from the ui.frontend module and syncs the changes with AEM at http://localhost:4502

+ jcr_root/apps/wknd/clientlibs/clientlib-site/js/site.js
+ jcr_root/apps/wknd/clientlibs/clientlib-site/js
+ jcr_root/apps/wknd/clientlibs/clientlib-site
+ jcr_root/apps/wknd/clientlibs/clientlib-dependencies/css.txt
+ jcr_root/apps/wknd/clientlibs/clientlib-dependencies/js.txt
+ jcr_root/apps/wknd/clientlibs/clientlib-dependencies
http://admin:admin@localhost:4502 > OK
+ jcr_root/apps/wknd/clientlibs/clientlib-site/css
+ jcr_root/apps/wknd/clientlibs/clientlib-site/js/site.js
http://admin:admin@localhost:4502 > OK

The command npm run watch ultimately populates the clientlib-site and clientlib-dependencies in the ui.apps module which is then synced automatically with AEM.

Inspect the file site.css beneath ui.frontend/dist/clientlib-site/site.css. This is the compiled CSS based on the Sass source files.

Inspect the file ui.frontend/clientlib.config.js. This is the configuration file for an npm plugin, aem-clientlib-generator that transforms the contents of /dist into a client library and moves it to the ui.apps module.

Inspect the file site.css in the ui.apps module at ui.apps/src/main/content/jcr_root/apps/wknd/clientlibs/clientlib-site/css/site.css. This should be an identical copy of the site.css file from the ui.frontend module. Now that it is in ui.apps module it can be deployed to AEM.

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

You should now see the updated styles for the article. You may need to do a hard refresh to clear any CSS files cached by the browser.

It’s starting to look a lot closer to the mockups!

From, the ui.frontend module open the file: ui.frontend/src/main/webpack/site/_variables.scss.

Update the $brand-primary color variable:

//== variables.css

//== Brand Colors
$brand-primary:          $pink;

Save the changes.

Return to the browser and refresh the AEM page to see the updates:

Revert the change to the $brand-primary color and stop the webpack build using the command CTRL+C.

Browse to the Article Page template at http://localhost:4502/editor.html/conf/wknd/settings/wcm/templates/article-page/structure.html

Click the Page Information icon and in the menu select Page Policy to open the Page Policy dialog.

Page Information > Page Policy

Notice that the categories for wknd.dependencies and wknd.site are listed here. By default clientlibs configured via the Page Policy are split to include the CSS in the page head and the JavaScript at the body end. You can explicitly list the clientlib JavaScript be loaded in the Page head. This is the case for wknd.dependencies.

Navigate to the LA Skateparks page created using the Article Page Template: http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html.

Click the Page Information icon and in the menu select View As Published to open the article page outside of the AEM Editor.

View the Page source of http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled and you should be able to see the following clientlib references in the <head>:

<head>
...
<script src="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.lc-d41d8cd98f00b204e9800998ecf8427e-lc.min.js"></script>
<link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.lc-d41d8cd98f00b204e9800998ecf8427e-lc.min.css" type="text/css">
<link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-78fb9cea4c3a2cc17edce2c2b32631e2-lc.min.css" type="text/css">
...
</head>

Notice that the clientlibs are using the proxy /etc.clientlibs endpoint. You should also see that the following clientlib includes at the bottom of the page:

...
<script src="/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-7157cf8cb32ed66d50e4e49cdc50780a-lc.min.js"></script>
<script src="/etc.clientlibs/wknd/clientlibs/clientlib-base.lc-53e6f96eb92561a1bdcc1cb196e9d9ca-lc.min.js"></script>
...
</body>

Copy the page source of the LA skatepark article page at http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled.

Reopen your IDE. Paste the copied markup from AEM into the index.html in the ui.frontend module beneath src/main/webpack/static.

Edit the copied markup and remove any references to clientlib-site and clientlib-dependencies:

<!-- remove -->
<script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.js"></script>
<link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.css" type="text/css">
<link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-site.css" type="text/css">
...
<script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-site.js"></script>

Remove these references because the webpack dev server generates these artifacts automatically.

Start the webpack dev server from a new terminal by running the following command from within the ui.frontend module:

$ cd ~/code/aem-guides-wknd/ui.frontend/
$ npm start

> aem-maven-archetype@1.0.0 start code/aem-guides-wknd/ui.frontend
> webpack-dev-server --open --config ./webpack.dev.js

This should open a new browser window at http://localhost:8080/ with static markup.

Edit the file src/main/webpack/site/_variables.scss file. Replace the $text-color rule with the following:

- $text-color:              $black;
+ $text-color:              $pink;

Save the changes.

You should automatically see the changes automatically reflected in the browser on http://localhost:8080.

Review the /aem-guides-wknd.ui.frontend/webpack.dev.js file. This contains the webpack configuration used to start the webpack-dev-server. It proxies the paths /content and /etc.clientlibs from a locally running instance of AEM. This is how the images, and other clientlibs (not managed by the ui.frontend code) are made available.

You can stop the webpack server from the command line by typing CTRL+C.