How are themes applied in Adobe AEM?

Question

The Client Library (ClientLib) feature in Adobe AEM (formerly Adobe CQ) makes it easy to include client libraries by category and each library can pull in other libraries through dependencies. However the documentation around "Themes" is a little thin.

This link is about all I can find on the subject. Here is an excerpt of the sample code:

<%-- theme only (theme-js + css) --%>
<cq:includeClientLib theme="cq.collab.calendar, cq.security" />

If this tag were to be used how would CQ determine what Client Libs to pull in? Does it look for a theme property of type String[]?

Or does it look for a certain directory structure in the /etc/designs section?

Or does it take the passed in categories and add theme-js to the end like so?

cq.collab.calendar.theme-js

Or is the theme invoked through the URL? In other words, the word "theme", in this case, is a token that is replaced with a selector from a URL applied theme?

Tiepolo

Answer 1

Client Libraries reside in a cq:ClientLibraryFolder folder. This folder has a property called category. In the following example, cq.collab.calendar and cq.security are categories:

<cq:includeClientLib theme="cq.collab.calendar, cq.security" />

When this include is called, it is looking for any cq:ClientLibraryFolder with the category cq.collab.calendar or cq.security assigned to it. Using the theme property adds both the css and javascript of clientLibs residing in the themes folder of the parent ClientLibraryFolder. If you were to view your page source, these would be added to their own css and js files. For example, I created the following structure under the geometrixx clientLibary:

geometrixx
    clientlibs
        themes
            myTheme (clientLibray)
               css.txt
               myCSS.css
               js.txt
               myJS.js

If, you use the theme property with this clientlib you would get a myTheme.css and myTheme.js file showing in your source/network tab.

The themed flag is a way to shut theme inclusion on and off. The following cq:include will include all the css in the clientLibrary, including stuff in the themes directory.

<cq:includeClientLib css="apps.geometrixx-main" />

However, if I add the themed flag and set it to false, anything under the theme directory is excluded:

<cq:includeClientLib css="apps.geometrixx-main" themed="false" />

So in that case, myTheme.css would not show up. One thing to note, is that the themed flag, only works on "pure css and js includes" Categories and theme properties would not work with this.

The answer to this question goes over this a bit: What exactly does currentDesign.writeCssincludes include?

Strung

How does the "themed" property come into play then: "themed: A flag that indicates if only themed or non themed libraries should be included. If omitted, both sets are included. Only applies to pure JS or CSS includes (not for categories or theme includes)." If the theme is just simply included JS+CSS categories then what does "themed or non-themed" refer to? It seems like there is some sort of theme support but maybe I am reading too much into it. – Tiepolo

Okay, did a bit more research and testing and revised my answer. – Strung

So even though myTheme has the category "apps.geometrixx-main" it won't be included when themed=false because its parent folder is called "themes"? – Tiepolo

BTW thanks for the extra info. I had read that other post before and I agree with @evil-otto who said, "[there's] nothing about how to define a theme, or how to select a theme for a page or site" – Tiepolo

Yes, even though it has the category "apps.geometrixx-main" it would not be included if themed was set to false. – Strung

It does not appear that you can select a single theme in the themes folder. Day/Adobe's intent on theme folders does not seem clear to me. – Strung

Answer 2

It has been mentioned that theme is fetched from the request did a little digging an finally found out it tries to fetch it from request parameter named "forceTheme"

private String getDefaultThemeName(SlingHttpServletRequest request)
  {
    String theme = request.getParameter("forceTheme");
    if (theme == null) {
      theme = this.defaultUserThemeName;
    }
    return theme;
  }

But needed request.getAttribute because using query parameters will send all requests to pub.

So guess this theme option is of no use at all.

Meritorious

Answer 3

Depends on what you mean by "theme". If you are used to wordpress, drupal, etc, what is called a theme in those systems is called a "design" in CQ5/AEM.

To set a design, you choose a "designpath" in the page properties. This will affect where information about components for each template is stored (all changes made in design mode about what components are allowed where are stored under this path) and is the convention for where CSS, JS, and non-DAM image resources are stored. It takes planning, but you can re-use code and markup in AEM/CQ5 but totally change the look by changing the design.

Lesalesak