Tag Libraries tag-libraries

The Granite, CQ, and Sling tag libraries give you access to specific functions for use in the JSP script of your templates and components.

Granite Tag Library granite-tag-library

The Granite tag library contains helpful functions.

When you develop the jsp script of a Granite UI component, it is recommended to include following code at the top of the script:

<%@include file="/libs/granite/ui/global.jsp"%>

The global also declares the Sling library.

<%@taglib prefix="sling" uri="https://sling.apache.org/taglibs/sling" %>

<ui:includeClientLib> ui-includeclientlib

The <ui:includeClientLib> tag Includes a AEM html client library, which can be a js, a css, or a theme library. For multiple inclusions of different types, for example js and css, this tag needs to be used multiple times in the jsp. This tag is a convenience wrapper around the [com.adobe.granite.ui.clientlibs.HtmlLibraryManager](https://helpx.adobe.com/experience-manager/6-4/sites/developing/using/reference-materials/javadoc/com/adobe/granite/ui/clientlibs/HtmlLibraryManager.html) service interface.

It has the following attributes:

categories - A list of comma-separated client lib categories. This will include all Javascript and CSS libraries for the given categories. The theme name is extracted from the request.

Equivalent to: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeIncludes

theme - A list of comma-separated client lib categories. This will include all theme related libraries (both CSS and JS) for the given categories. The theme name is extracted from the request.

Equivalent to: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeThemeInclude

js - A list of comma-separated client lib categories. This will include all Javascript libraries for the given categories.

Equivalent to: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeJsInclude

css - A list of comma-separated client lib categories. This will include all CSS libraries for the given categories.

Equivalent to: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeCssInclude

themed - A flag that indicates of 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).

The <ui:includeClientLib> tag can be used as follows in a jsp:

<%-- all: js + theme (theme-js + css) --%>
<ui:includeClientLib categories="cq.wcm.edit" />

<%-- only js libs --%>
<ui:includeClientLib js="cq.collab.calendar, cq.security" />

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

<%-- css only --%>
<ui:includeClientLib css="cq.collab.calendar, cq.security" />

CQ Tag Library cq-tag-library

The CQ tag library contains helpful functions.

To use the CQ Tag Library in your script, the script must start with the following code:

<%@taglib prefix="cq" uri="https://www.day.com/taglibs/cq/1.0" %>

When you develop the jsp script of a AEM component, it is recommended to include following code at the top of the script:

<%@include file="/libs/foundation/global.jsp"%>

It declares the sling, CQ, and jstl taglibs and exposes the regularly used scripting objects defined by the <cq:defineObjects /> tag. This shortens and simplifies the jsp code of your component.

<cq:text> cq-text

The <cq:text> tag is a convenience tag that outputs component text in a JSP.

It has the following optional attributes:

property - Name of the property to use. The name is relative to the current resource.

value - Value to use for output. If this attribute is present, it overwrites the use of the property attribute.

oldValue - Value to use for diff output. If this attribute is present, it overwrites the use of the property attribute.

escapeXml - Defines whether the characters <, >, &, ’ and " in the resulting string should be converted to their corresponding character entity codes. Default value is false. Note that the escaping is applied after the optional formatting.

format - Optional java.text.Format to use for formatting the text.

noDiff - Suppresses the calculation of a diff output, even if a diff info is present.

tagClass - CSS class name of an element that will surround a non-empty output. If empty, no element is added.

tagName - Name of the element that will surround a non-empty output. It defaults to DIV.

placeholder - Default value to use for null or empty text in edit mode, i.e. the placeholder. Please note that the default check is performed after the optional formatting and escaping, i.e. it is written as-is to the output. It defaults to:

<div><span class="cq-text-placeholder">&para;</span></div>

default - Default value to use for null or empty text. Note that the default check is performed after the optional formatting and escaping i.e. it is written as-is to the output.

Some examples how the <cq:text> tag can be used in a JSP:

<cq:text property="jcr:title" tagName="h2"/>
<cq:text property="jcr:description" tagName="p"/>

<cq:text value="<%= listItem.getTitle() %>" tagName="h4" placeholder="" />
<cq:text value="<%= listItem.getDescription() %>" tagName="p" placeholder=""/>

<cq:text property="jcr:title" value="<%= title %>" tagName="h3"/><%
    } else if (type.equals("link")) {
        %><cq:text property="jcr:title" value="<%= "\u00bb " + title %>" tagName="p" tagClass="link"/><%
    } else if (type.equals("extralarge")) {
        %><cq:text property="jcr:title" value="<%= title %>" tagName="h1"/><%
    } else {
        %><cq:text property="jcr:title" value="<%= title %>" tagName="h2"/><%

<cq:text property="jcr:description" placeholder="" tagName="small"/>

<cq:text property="tableData"
               escapeXml="false"
               placeholder="<img src=\"/libs/cq/ui/resources/0.gif\" class=\"cq-table-placeholder\" alt=\"\">"
    />

<cq:text property="text"/>

<cq:text property="image/jcr:description" placeholder="" tagName="small"/>
<cq:text property="text" tagClass="text"/>

<cq:setContentBundle> cq-setcontentbundle

The <cq:setContentBundle> tag creates an i18n localization context and stores it in the javax.servlet.jsp.jstl.fmt.localizationContext configuration variable.

It has the following attributes:

language - The language of the locale for which to retrieve the resource bundle.

source - The source where the locale should be taken from. It can be set to one of the following values:

If the source attribute is not set:

The “content bundle” can be simply used by standard JSTL <fmt:message> tags. The lookup of messages by keys is two-fold:

The <cq:setContentBundle> tag can be used as follows in a jsp.

For pages that define their language:

... %><cq:setContentBundle source="page"/><%  %>
<div class="error"><fmt:message key="Hello"/>
</div> ...

For user personalized pages:

... %><cq:setContentBundle scope="request"/><% %>
<div class="error"><fmt:message key="Hello"/>
</div> ...

<cq:include> cq-include

The <cq:include> tag includes a resource into the current page.

It has the following attributes:

flush

path

resourceType

script

ignoreComponentHierarchy

Example:

<%@taglib prefix="cq" uri="https://www.day.com/taglibs/cq/1.0" %><%
%><div class="center">
    <cq:include path="trail" resourceType="foundation/components/breadcrumb" />
    <cq:include path="title" resourceType="foundation/components/title" />
    <cq:include script="redirect.jsp"/>
    <cq:include path="par" resourceType="foundation/components/parsys" />
</div>

Should you use <%@ include file="myScript.jsp" %> or <cq:include script="myScript.jsp" %> to include a script?

Should you use <cq:include> or <sling:include>?

<cq:includeClientLib> cq-includeclientlib

The <cq:includeClientLib> tag Includes a AEM html client library, which can be a js, a css or a theme library. For multiple inclusions of different types, for example js and css, this tag needs to be used multiple times in the jsp. This tag is a convenience wrapper around the com.day.cq.widget.HtmlLibraryManager service interface.

It has the following attributes:

categories - A list of comma-separated client lib categories. This will include all Javascript and CSS libraries for the given categories. The theme name is extracted from the request.

Equivalent to: com.day.cq.widget.HtmlLibraryManager#writeIncludes

theme - A list of comma-separated client lib categories. This will include all theme related libraries (both CSS and JS) for the given categories. The theme name is extracted from the request.

Equivalent to: com.day.cq.widget.HtmlLibraryManager#writeThemeInclude

js - A list of comma-separated client lib categories. This will include all Javascript libraries for the given categories.

Equivalent to: com.day.cq.widget.HtmlLibraryManager#writeJsInclude

css - A list of comma-separated client lib categories. This will include all CSS libraries for the given categories.

Equivalent to: com.day.cq.widget.HtmlLibraryManager#writeCssInclude

themed - A flag that indicates of 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).

The <cq:includeClientLib> tag can be used as follows in a jsp:

<%-- all: js + theme (theme-js + css) --%>
<cq:includeClientLib categories="cq.wcm.edit" />

<%-- only js libs --%>
<cq:includeClientLib js="cq.collab.calendar, cq.security" />

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

<%-- css only --%>
<cq:includeClientLib css="cq.collab.calendar, cq.security" />

<cq:defineObjects> cq-defineobjects

The <cq:defineObjects> tag exposes the following, regularly used, scripting objects which can be referenced by the developer. It also exposes the objects defined by the <sling:defineObjects> tag.

componentContext

component

currentDesign

currentPage

currentStyle

designer

editContext

pageManager

pageProperties

properties

resourceDesign

resourcePage

requestName

responseName

resourceName

nodeName

logName

resourceResolverName

slingName

componentContextName

editContextName

propertiesName

pageManagerName

currentPageName

resourcePageName

pagePropertiesName

componentName

designerName

currentDesignName

resourceDesignName

currentStyleName

Example

<%@page session="false" contentType="text/html; charset=utf-8" %><%
%><%@ page import="com.day.cq.wcm.api.WCMMode" %><%
%><%@taglib prefix="cq" uri="https://www.day.com/taglibs/cq/1.0" %><%
%><cq:defineObjects/>

<cq:requestURL> cq-requesturl

The <cq:requestURL> tag writes the current request URL to the JspWriter. The two tags <cq:addParam> and <cq:removeParam> and may be used inside the body of this tag to modify the current request URL before it is written.

It allows you to create links to the current page with varying parameters. For example, it enables you to transform the request:

mypage.html?mode=view&query=something into mypage.html?query=something.

The use of addParam or removeParam only changes the occurrence of the given parameter, all other parameters are unaffected.

<cq:requestURL> does not have any attribute.

Examples:

<a href="<cq:requestURL><cq:removeParam name="language"/></cq:requestURL>">remove filter</a>

<a title="filter results" href="<cq:requestURL><cq:addParam name="language" value="${bucket.value}"/></cq:requestURL>">${label} (${bucket.count})</a>

<cq:addParam> cq-addparam

The <cq:addParam> tag adds a request parameter with the given name and value to the enclosing <cq:requestURL> tag.

It has the following attributes:

name

value

Example:

<a title="filter results" href="<cq:requestURL><cq:addParam name="language" value="${bucket.value}"/></cq:requestURL>">${label} (${bucket.count})</a>

<cq:removeParam> cq-removeparam

The <cq:removeParam> tag removes a request parameter with the given name and value from the enclosing <cq:requestURL> tag. If no value is provided all parameters with the given name are removed.

It has the following attributes:

name

Example:

<a href="<cq:requestURL><cq:removeParam name="language"/></cq:requestURL>">remove filter</a>

Sling Tag Library sling-tag-library

The Sling tag library contains helpful Sling functions.

When you use the Sling Tag Library in your script, the script must start with the following code:

<%@ taglib prefix="sling" uri="https://sling.apache.org/taglibs/sling/1.0" %>

<sling:include> sling-include

The <sling:include> tag includes a resource into the current page.

It has the following attributes:

flush

resource

path

resourceType

replaceSelectors

addSelectors

replaceSuffix

Examples:

<div class="item"><sling:include path="<%= pathtoinclude %>"/></div>

<sling:include resource="<%= par %>"/>

<sling:include addSelectors="spool"/>

<sling:include resource="<%= par %>" resourceType="<%= newType %>"/>

<sling:include resource="<%= par %>" resourceType="<%= newType %>"/>

<sling:include replaceSelectors="content" />

<sling:defineObjects> sling-defineobjects

The <sling:defineObjects> tag exposes the following, regularly used, scripting objects which can be referenced by the developer:

slingRequest

slingResponse

resourceResolver

.sling

resource

currentNode

log

requestName

responseName

nodeName

l ogName resourceResolverName

slingName

Example:

<%@page session="false" %><%
%><%@page import="com.day.cq.wcm.foundation.forms.ValidationHelper"%><%
%><%@taglib prefix="sling" uri="https://sling.apache.org/taglibs/sling/1.0" %><%
%><sling:defineObjects/>

JSTL Tag library jstl-tag-library

The JavaServer Pages Standard Tag Library contains a lot of useful and standard tags. The core, formatting and functions taglibs are defined by the /libs/foundation/global.jsp as shown in the following snippet.

Extract of /libs/foundation/global.jsp extract-of-libs-foundation-global-jsp

<%@taglib prefix="c" uri="https://java.sun.com/jsp/jstl/core" %>
<%@taglib prefix="fmt" uri="https://java.sun.com/jsp/jstl/fmt" %>
<%@taglib prefix="fn" uri="https://java.sun.com/jsp/jstl/functions" %>

After importing the /libs/foundation/global.jsp file as described before, you can use the c, fmt and fn prefixes to access to those taglibs. The official documentation of the JSTL is available at The Java EE 5 Tutorial - JavaServer Pages Standard Tag Library.