Welcome to CQBlueprints - A resource for your Adobe CQ 5.4, 5.5, 5.6 and AEM6 projects. Get your CQ project on the right track.

Writing A JSP Custom Tag Library

Within CQ, Components (including Page Templates) can utilize JSPs for rendering not only HTML, but also other output formats such as JSON.

Unfortunately, many JSPs are written poorly and mix presentation logic with business logic (in the form of scriptlets) making them difficult to test, debug and maintain. One of the best ways to write better JSPs is to never use scriptlets and instead use a combination of EL expressions and Custom Tag Libraries (including the JSTL). This Blueprint details how Custom Tag Libraries should be developed and deployed to a CQ environment.

IMPORTANT: This Blueprint deals specifically with packaging and deploying a JSP Custom Tag Library into a CQ environment. It does not get into the general details of how to actually write a JSP Custom Tag Library. For more information on writing JSP Custom Tag Libraries, see the JavaEE 5 Tutorial - Custom Tags in JSP Pages documentation.

Setup a Maven Project To Create An OSGi Bundle

To deploy a JSP Custom Tag Library into CQ, it must be packaged as an OSGi Bundle. An OSGi Bundle is simply a JAR file with extra meta-data embedded inside of it. Luckily there is excellent support in Apache Maven (via plugins) for creating OSGi Bundles.

For complete instructions on how to create an OSGi Bundle for CQ, see this Blueprint: Building and Deploying OSGi Bundles

Write The Tag Library

Once you have a basic Maven project setup that will create an OSGi Bundle for your Tag Library, you can go ahead and implement your Tag Library classes and Tag Files as you normally would.

package com.cqblueprints.examples.taglib;

import java.io.IOException;
import javax.servlet.jsp.JspException;
import com.squeakysand.commons.taglib.EnhancedSimpleTagSupport;
import com.squeakysand.jsptld.annotations.JspTag;

/**
 * @author <a href="http://craigsdickson.com">Craig S. Dickson</a>
 */
@JspTag
public class HelloWorldTag extends EnhancedSimpleTagSupport {

   @Override
   public void doTag() throws JspException, IOException {
        getJspWriter().write("Hello World!");
   }
}

IMPORTANT: In your Tag Library Descriptor (.tld file), for the value of the <uri> tag, you must specify a full and unique URL to identify your Tag Library within the CQ environment. If you only specify a relative URI, CQ often fails to find your library.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<taglib xmlns="http://java.sun.com/xml/ns/javaee" version="2.1">
	<tlib-version>5.4.0-SNAPSHOT</tlib-version>
	<short-name>example</short-name>
	<uri>http://cqblueprints.com/examples/cqblueprints-examples-taglib</uri>
	<tag>
		<name>helloWorld</name>
		<tag-class>com.cqblueprints.examples.taglib.HelloWorldTag</tag-class>
		<body-content>empty</body-content>
	</tag>
</taglib>

IMPORTANT: The Tag Library Descriptor file must be found inside of the META-INF directory within your OSGi Bundle (remember, a bundle it is just a JAR file with extra meta-data). When using the Maven Bundle Plugin, if your Tag Library Descriptor is in a sub-directory called META-INF of the standard Maven resources source directory (e.g. src/main/resources/META-INF/mytaglib.tld) it will automatically be included in the right spot in the OSGi Bundle. If your Tag Library Descriptor cannot be put in this location (perhaps it is generated at build time), then you can pass the <Include-Resource> instruction to the Maven Bundle Plugin to include additional files into the created OSGi bundle.

<plugin>
	<groupId>org.apache.felix</groupId>
	<artifactId>maven-bundle-plugin</artifactId>
	<configuration>
		<instructions>
			<Bundle-Activator>com.cqblueprints.examples.taglib.osgi.Activator</Bundle-Activator>
			<Private-Package>com.cqblueprints.examples.taglib.osgi</Private-Package>
			<Embed-Dependency>*;scope=compile|runtime</Embed-Dependency>
			<Embed-Directory>OSGI-INF/lib</Embed-Directory>
			<Embed-Transitive>true</Embed-Transitive>
			<Import-Package>!org.slf4j.impl,*</Import-Package>
			<Include-Resource>META-INF/example-${project.version}.tld=target/classes/META-INF/example-${project.version}.tld</Include-Resource>
		</instructions>
	</configuration>
</plugin>

Deploy The Tag Library To CQ

Because the Tag Library is correctly packaged as an OSGi Bundle, there is nothing special that needs to be done to deploy the Tag Library to CQ beyond what you would normally do to deploy any other OSGi bundle.

If you look at the  Maven pom.xml file mentioned in the Building and Deploying OSGi Bundles Blueprint, it has a profile called auto-deploy defined:

<profile>
	<id>auto-deploy</id>
	<build>
		<pluginManagement>
			<plugins>
				<plugin>
					<groupId>org.apache.sling</groupId>
					<artifactId>maven-sling-plugin</artifactId>
					<version>2.0.4-incubator</version>
				</plugin>
			</plugins>
		</pluginManagement>
		<!--
                    Use the sling plugin to deploy the built bundle to CQ.
                -->
		<plugins>
			<plugin>
				<groupId>org.apache.sling</groupId>
				<artifactId>maven-sling-plugin</artifactId>
				<executions>
					<execution>
						<id>deploy-to-cq</id>
						<phase>install</phase>
						<goals>
							<goal>install</goal>
						</goals>
						<configuration>
							<slingUrl>${crx.url}/system/console/install</slingUrl>
							<user>${crx.user}</user>
							<password>${crx.password}</password>
						</configuration>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>
</profile>

With this profile defined in your pom.xml, deploying the Tag Library to your CQ server is as easy as executing a Maven command similar to:

mvn -Pauto-deploy clean install

You can run this command repeatedly (either from the command line or from within your favorite IDE) and CQ will redeploy the Tag Library each time. As soon as the deployment of the Tag Library completes, you can view a page in your web browser that uses the Tag Library and you will see the effects of the latest code - ie. no need to restart the CQ server.

Using Your Custom Tag Library

Once you have deployed your Tag Library for the first time, you can begin to use it in your JSPs by defining the Tag Library in your JSP using the standard mechanism:

<?xml version="1.0" encoding="UTF-8"?>
<jsp:root version="2.1"
         xmlns:jsp="http://java.sun.com/JSP/Page"
         xmlns:example="hhttp://cqblueprints.com/examples/cqblueprints-examples-taglib">

	<jsp:directive.page contentType="text/html" pageEncoding="UTF-8"/>
	<example:helloWorld/>
</jsp:root>

Do you find the information on this site useful? Do you think we should add an article on a specific subject? We'd like to hear from you. Please drop us an email @ info@headwire.com

Search CQ Related Information