Front-End Development for AEM as a Cloud Service

All JavaScript, CSS, and other front-end assets should be maintained in the ui.frontend module of the AEM Project Archetype. The flexibility of the archetype lets you use your modern web tools of choice to create and manage these resources.

The archetype can then compile the resources into single CSS and JS files, embedding them automatically into a cq:clientLibraryFolder in the repository.

Client-Side Library Folder Structure

A client-side library folder is a repository node of type cq:ClientLibraryFolder. Its definition in CND notation is

[cq:ClientLibraryFolder] > sling:Folder
  - dependencies (string) multiple
  - categories (string) multiple
  - embed (string) multiple
  - channels (string) multiple
  • cq:ClientLibraryFolder nodes can be placed anywhere within the /apps subtree of the repository.
  • Use the categories property of the node to identify the library categories to which it belongs.

Each cq:ClientLibraryFolder is populated with a set of JS and/or CSS files, along with a few supporting files (see below). Important properties of the cq:ClientLibraryFolder are configured as follows:

  • allowProxy: Since all clientlibs must be stored under apps, this property allows access to client libraries via proxy servlet. See the section Locating a Client Library Folder and Using the Proxy Client Libraries Servlet below.
  • categories: Identifies the categories into which the set of JS and/or CSS files within this cq:ClientLibraryFolder fall. The categories property, being multi-valued, allows a library folder to be part of more than one category (see below for how this may be useful).

If the client library folder contains one or more source files that, at runtime, they are merged into a single JS and/or CSS file. The name of the generated file is the node name with either the .js or .css file name extension. For example, the library node named cq.jquery results in the generated file named cq.jquery.js or cq.jquery.css.

Client library folders contain the following items:

  • The JS and/or CSS source files
  • Static resources that support CSS styles, such as icons, web fonts, and so on.
  • One js.txt file and/or one css.txt file which identify the source files to merge in the generated JS and/or CSS files

Clientlib architecture

Creating Client-Side Library Folders

Client libraries must be located under /apps. This rule necessary to better isolate code from content and configuration.

In order for the client libraries under /apps to be accessible, a proxy servelt is used. The ACLs are still enforced on the client library folder, but the servlet allows for the content to be read via /etc.clientlibs/ if the allowProxy property is set to true.

  1. Open CRXDE Lite in a web browser (https://<host>:<port>/crx/de).

  2. Select the /apps folder and click Create > Create Node.

  3. Enter a name for the library folder, and in the Type list select cq:ClientLibraryFolder. Click OK and then click Save All.

  4. To specify the category or categories that the library belongs to, select the cq:ClientLibraryFolder node, add the following property, and then click Save All:

    • Name: categories
    • Type: String
    • Value: The category name
    • Multi: Selected
  5. In order for the client libraries to be accessible via proxy under /etc.clientlibs, select the cq:ClientLibraryFolder node, add the following property, and then click Save All:

    • Name: allowProxy
    • Type: Boolean
    • Value: true
  6. If you need to manage static resources, create a subfolder named resources below the client library folder.

    • If you store static resources anywhere other than under the folder resources, theycannot be referenced on a publish instance.
  7. Add source files to the library folder.

    • This is typically done by the front-end build process of the AEM Project Archetype.
    • You can organize source files in subfolders if desired.
  8. Select the client library folder and click Create > Create file.

  9. In the file name box, type one of the following file names and click OK:

    • js.txt: Use this file name to generate a JavaScript file.
    • css.txt: Use this file name to generate a Cascading Style Sheet.
  10. Open the file and type the following text to identify the root of the path of the source files:

    • #base=*[root]*
    • Replace [root] with the path to the folder that contains the source files, relative to the TXT file. For example, use the following text when the source files are in the same folder as the TXT file:
      • #base=.
    • The following code sets the root as the folder named mobile below the cq:ClientLibraryFolder node:
      • #base=mobile
  11. On the lines below #base=[root], type the paths of the source files relative to the root. Place each file name on a separate line.

  12. Click Save All.

Serving Client-Side Libraries

Once your client library folder is configured as required, your clientlibs can be requested via proxy. As an example:

  • You have a clientlib in /apps/myproject/clientlibs/foo
  • You have a static image in /apps/myprojects/clientlibs/foo/resources/icon.png

The allowProxy property lets you request:

  • The clientlib via /etc.clientlibs/myprojects/clientlibs/foo.js
  • The static image via /etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png

Loading Client Libraries via HTL

Once your clientlibs are successfully stored and managed in their client library folder, they can be access via HTL.

Client libraries are loaded through a helper template provided by AEM, which can be accessed through data-sly-use. Helper templates are available in this file, which can be called through data-sly-call.

Each helper template expects a categories option for referencing the desired client libraries. That option can be either an array of string values, or a string containing a comma separated values list.

See the HTL documentation for more details on loading clientlibs via HTL.

Client Libraries on Author versus Publish

Most clientlibs are required on the AEM publish instance. That is, most clientlibs’ purposes are to produce the end-user experience of the content. For clientlibs on publish instances, front-end build tools can be used and deployed via client library folders as described above.

However there are times when client libraries may be necessary to customize the authoring experience. For example, customizing a dialog might require deploying small bits of CSS or JS to the AEM authoring instance.

Managing Client Libraries on Author

If you need to use client libraries on author, you can create your client libraries under /apps using the same methods as for publish, but write it directly under /apps/.../clientlibs/foo instead of creating an entire project to manage it.

You can then “hook” into the authoring JS by adding your client libraries to an out-of-the-box client library category.

Debugging Tools

AEM provides several tools for debugging and testing client library folders.

Discover Client Libraries

The /libs/cq/granite/components/dumplibs/dumplibs component generates a page of information about all client library folders on the system. The /libs/granite/ui/content/dumplibs node has the component as a resource type. To open the page, use the following URL (changing the host and port as required):

https://<host>:<port>/libs/granite/ui/content/dumplibs.test.html

The information includes the library path and type (CSS or JS), and the values of the library attributes, such as categories and dependencies. Subsequent tables on the page show the libraries in each category and channel.

See Generated Output

The dumplibs component includes a test selector that displays the source code that is generated for ui:includeClientLib tags. The page includes code for different combinations of js, css, and themed attributes.

  1. Use one of the following methods to open the Test Output page:

    • From the dumplibs.html page, click the link in the Click here for output testing text.
    • Open the following URL in your web browser (use a different host and port as required):
      • http://<host>:<port>/libs/granite/ui/content/dumplibs.html
    • The default page shows output for tags with no value for the categories attribute.
  2. To see the output for a category, type the value of the client library’s categories property and click Submit Query.

Additional Client Library Folder Features

There are several other features that are supported by client library folders in AEM. However, these are not required on AEM as a Cloud Service and as such their use is discouraged. They are listed here for completeness.

WARNING
These additional features of Client Library Folders are not required on AEM as a Cloud Service and as such their use is discouraged. They are listed here for completeness.

Adobe Granite HTML LIbrary Manager

Additional client library settings can be controlled through the Adobe Granite HTML Library Manager panel of the System Console at https://<host>:<port>/system/console/configMgr).

Additional Folder Properties

Additional folder properties include allow control of dependencies and embeds, but are generally no longer needed and their use is discouraged:

  • dependencies: This is a list of other client library categories on which this library folder depends. For example, given two cq:ClientLibraryFolder nodes F and G, if a file in F requires another file in G to function properly, then at least one of the categories of G should be among the dependencies of F.
  • embed: Used to embed code from other libraries. If node F embeds nodes G and H, the resulting HTML is a concatenation of content from nodes G and H.