Client Libraries and the Core Components

The Core Components come with a number of client libraries and offer the ability to include your own.

Provided Client Libraries

The Core Components provide the following client libraries out-of-the-box.

  • The site clientlibs provide the minimalistic functional behavior of the components that is to be applied to the site.
    • They serve as a starting point to accelerate projects, with implementations encouraged to extend and customize them to achieve the desired appearance and functionality.
  • The editor clientlibs are applied to the authoring dialog to ensure its expected functionality and appearance.
  • The editorhook clientlibs are applied to the site when loaded in edit mode.
    • They contain JavaScript code executed on editor-triggered events, facilitating the initialization of dynamic functionality.
  • Some components may have specific additional clientlibs designed for use in particular situations, such as when employed alongside Dynamic Media for example.

Including Client Libraries

There are a number of different ways to include client libraries depending on your use case. The following are examples with sample HTL snippets for each.

If you don’t have time to investigate what’s best in your situation, then include your client libraries by placing the following HTL lines inside your page head element:

<sly data-sly-use.clientlibs="${'com.adobe.cq.wcm.core.components.models.ClientLibraries' @
    categories='wknd.base', defer=true}">
    ${clientlibs.jsAndCssIncludes @ context="unsafe"}
</sly>

This will include both the CSS and the JS in your page head, but adding the defer attribute to your JS script includes, so that the browsers wait for the DOM to be ready before executing your scripts, and therefore optimizing the page load speed.

Basic Usage

The basic syntax to include both JS and CSS of a client library category, which will generate all the corresponding CSS link elements and/or JS script elements, is as follows:

<sly data-sly-use.clientlibs="${'com.adobe.cq.wcm.core.components.models.ClientLibraries' @ categories='wknd.base'}">
    ${clientlibs.jsAndCssIncludes @ context="unsafe"}
</sly>

To do the same for multiple client library categories at once, an array of strings can be passed to the categories parameter:

<sly data-sly-use.clientlibs="${'com.adobe.cq.wcm.core.components.models.ClientLibraries' @
    categories=['wknd.base', 'cq.foundation']}">
    ${clientlibs.jsAndCssIncludes @ context="unsafe"}
</sly>

CSS or JS Only

Frequently, one wants to place the CSS includes in the HTML head element, and the JS includes just before the closing of the body element.

In the head, to include only the CSS, and not the JS, use cssIncludes:

<sly data-sly-use.clientlibs="${'com.adobe.cq.wcm.core.components.models.ClientLibraries' @ categories='wknd.base'}">
    ${clientlibs.cssIncludes @ context="unsafe"}
</sly>

Before the body closing, to include only the JS, and not the CSS, use jsIncludes:

<sly data-sly-use.clientlibs="${'com.adobe.cq.wcm.core.components.models.ClientLibraries' @ categories='wknd.base'}">
    ${clientlibs.jsIncludes @ context="unsafe"}
</sly>

Attributes

To apply attributes to the generated CSS link elements and/or JS script elements, a number of parameters are possible:

<sly data-sly-use.clientlibs="${'com.adobe.cq.wcm.core.components.models.ClientLibraries' @
    categories='wknd.base',
    media='print',
    async=true,
    defer=true,
    onload='console.log(\'loaded: \' + this.src)',
    crossorigin='anonymous'}">
    ${clientlibs.jsAndCssIncludes @ context="unsafe"}
</sly>

CSS link attributes that can be passed to jsAndCssIncludes and cssIncludes:

  • media: string JS script attributes that can be passed to jsAndCssIncludes and jsIncludes:
  • async: boolean
  • defer: boolean
  • onload: string
  • crossorigin: string

Inlining

In some cases, either for optimization, or for email or AMP, it might be required to inline the CSS or JS into the output of the HTML.

To inline the CSS, cssInline can be used, in which case you must write the surrounding style element:

<style type="text/css"
    data-sly-use.clientlibs="${'com.adobe.cq.wcm.core.components.models.ClientLibraries' @ categories='wknd.base'}">
    ${clientlibs.cssInline @ context="unsafe"}
</style>

Similarly, to inline the JS, jsInline can be used, in which case you must write the surrounding script element:

<script type="text/javascript"
    data-sly-use.clientlibs="${'com.adobe.cq.wcm.core.components.models.ClientLibraries' @ categories='wknd.base'}">
    ${clientlibs.jsInline @ context="unsafe"}
</script>

Loading Context-Aware CSS and JavaScript

The Page Component also supports loading developer-defined context-aware CSS, JavaScript, or meta tags.

This is done by creating a context-aware resource for com.adobe.cq.wcm.core.components.config.HtmlPageItemsConfig using the following structure:

com.adobe.cq.wcm.core.components.config.HtmlPageItemsConfig
    - prefixPath="/some/path"
    + item01
        - element=["link"|"script"|"meta"]
        - location=["header"|"footer"]
        + attributes
            - attributeName01="attributeValue01"
            - attributeName02="attributeValue02"
            ...
    + item02
        ...
    ...

See the technical documentation for the Page Component for more information.

d2be9096-a81e-404b-9952-d8925af7219c