How to configure CQ content to appear in a portlet
The CQ portals and portlets described in this document are those supplied with CQ 5.3 (crx-quickstart/opt/portal). If you are using the CQ 5.4 version of the portal director with CQ 5.3, please see the CQ 5.4 portal documentation.
CQ Portal Architecture
CQ portal architecture includes definitions of portals, portlets, the CQ Portal Container, and the CQ Portal Director.
What is a portal?
A portal is a web application that provides personalization, single sign on, content integration from different sources, and hosts the presentation layer of information systems.
The CQ5 Portal Container lets you run JSR 286-compliant portlets in CQ. The portlet component lets you embed a portlet on the page.
What is a portlet?
Portlets are web components deployed inside of a container that generate dynamic content. The portlet interface is packaged and deployed as a .war file inside of a portlet container. If you are running CQ as a portal, you need the portlet's .war file to run the portlet.
The CQ5 Portal Director provides a content portlet that lets you display content from the publish instance, preview content from the author instance, and provides a link within the content to open the corresponding page in a new browser window. The portlet is located at /crx-quickstart/opt/portal after the quickstart is extracted.
The content portlet is based on the JSR 286 (portlet API 2.0) and can run in any compliant portal.
A special mode has been built into the portlet for WebLogic Portal 10.3 that provides the 2.0 API but implements only the 1.0 functionality.
CQ Content Portlet Architecture
This section describes CQ Content Portlet architecture including portal security, caching, and customizing OSGi services.
The portal is the driving authentication mechanism. You can log in to CQ either with a technical user, the portal user, a group and so on. The portlet has no access to the password for the user in the portal, so if the portlet does not know all the credentials to successfully log in a user, an SSO solution must be used. In this case, the CQ portlet forwards all required information to CQ, which in turn forwards this information to the underlying CRX. This behavior is pluggable and can be customized.
The portlet supports SSO with CQ5 out of the box. The authenticator service can be configured to use SSO and transmit the current portal user with format Basic as a cookie named cqpsso to CQ. CQ should be configured to use the SSO authentication handler for path /. The cookie name needs to be configured here as well.
The crx-quickstart/repository/repository.xml for CRX needs to be configured accordingly:
To open the website administration page or to edit a page from the portlet, the CQ content portlet uses the new pin authentication. By default, the pin authentication is disabled, therefore, the following configuration changes have to be made in CQ:
1. Enable trusted authentication in CRX by adding the trusted info in the repository.xml file:
2. In the OSGi configuration console, by default located at http://localhost:4502/system/console/configMgr, select CQ PIN Authentication Handler from the drop-down menu.
3. Edit the URL Root Path parameter to just contain the single value /.
The portlet can be configured with its own cache so that the content in the portlet displays without requiring access to CQ. The portlet cache can be invalidated with a dispatcher flush from CQ. To configure the portlet to use its own cache:
Configure a replication agent in author that targets the portal server.
Assuming the portal server runs on host localhost, port 8080 and the CQ portlet web application is mounted in the context cqportlet, the url to flush the cache is http://localhost:8080/cqportlet/cqbridge/cqpcache?Path=$(path). Use GET as the method.
Instead of using a request parameter, you can send an http header named Path.
Customizing the CQ portlet application
The provided CQ portlet application starts an OSGi container inside the web application just as CQ5 does. This architecture lets you make use of all the benefits of OSGi:
Easy to update and extend.
Provides hot updates of the portlet without any interaction of the portal server.
Easy to customize the portlet.
Customizable OSGi Services
The following services are services (with a corresponding Java interface). To customize, a bundle containing the new service implementation needs to be deployed into the portlet application.
Provides the authentication information to CQ
Uses a configurable technical user for both author and publish
Rewrites links, images etc.
Rewrites CQ links to portal links, can be extended by a UrlMapper
Handles all http connections
Handles the locale info
Adds information as request headers and rewrites content link
Optional service that can be used to add html above and below the portlet, add css, and suppress the toolbar
Checks user rights
Checks access to author instance if user is allowed to edit contents
Optional service to track portlet invocations
Optional service to provide layout for the toolbar
Renders the toolbar
Adds a toolbar with Preview, Edit, Site administration functionality
Optional service to map portlet urls to portal pages
OSGi Web Console
Assuming the portal server runs on host localhost, port 8080 and the CQ portlet web application is mounted in the context cqportlet, the url to for the web console is http://localhost:8080/cqportlet/cqbridge/system/console.
Using CQ as a Portal
To configure to use CQ as a portal, you need to do the following:
Configure the portlet component in CQ WCM.
Deploy the portlet.
Configure the portlet.
Configuring the Portlet component
You need to add the portlet component to the paragraph system by adding it in the Designer.
To add the portlet component to the existing paragraph system:
In the sidekick, select the ruler icon (Designer).
In Design of par above the first paragraph, click Edit.
In the General component category, select the check box next to the Portlet component to make it part of the paragraph system.
In Edit mode, drag the portlet component on the page or double-click the component and choose Portlet from General in the sidekick.
Deploying portlets includes rewriting the portlet application's web.xml file and deploying the application.
Adding the servlet configuration to the web.xml file
To work properly in the CQ portal container, the portlet application's web.xml needs to be rewritten before you deploy it.
If CQSE is used as the servlet container, CQSE does the rewriting and you do not have to rewrite the web.xml file.
To add the servlet configuration when CQSE is not used as the servlet container:
Open the .war file (jar xf nameofapp.war extracts the files) to access the application's web.xml file.
Add the following servlet configuration to the web.xml file:
After configuring the portlet application's web.xml file, deploy the portlet through the admin console.
To deploy the application:
Navigate to the admin console athttp://<host>:<port>/admin/webapps.
Navigate to the portlet by clicking Choose File and browsing to the .war file.
In the Context field, add a context, for example, /portlet.
Adding portlets to your CQ page
After the portlet is deployed, you can add it to your page.
To add a portlet component to your web page:
1. On the web page, drag the Portlet component from the sidekick (General) to the page.
After you drag the component to the page, reload the page to ensure that it works properly.
2. In the Portlet Entity drop-down menu, select the portlet from the list.
3. Select or clear the Hide Title Bar check box depending on whether you want to see the portlet's title bar.
4. In the Portlet Window field, enter a unique Portlet Window ID, if desired.
If you plan to use the same portlet more than once on the same page, give each portlet a different window ID.
5. Click OK. The portlet displays on your CQ page.
How to install, configure, and use CQ in a portlet
To access content provided by CQ5 WCM, the portal server needs to be
fitted with the CQ5 Portal Director Portlet. You do this by installing,
configuring, and adding the portlet to the portal page by using the steps
provided in this section.
By default, the portlet connects to the publish instance at
localhost:4503 and to the author instance at
localhost:4502. These values can be changed during
deployment of the portlet by changing the according preferences. The portal
director can be found in the opt directory after CQ
quickstart has been started for the first time.
These procedures use the Websphere portal as an example; therefore, the procedures and included screenshots vary for other web portals. Although the steps are essentially identical for all web portals, you need to repurpose the steps for your web portal (for example, navigating to the Administration section of your web portal may differ from the Websphere portal).
Installing the portlet
To install the portlet:
Log in to the portal with administrator privileges.
Navigate to the Portlet Management part of your web portal. For
example, in Websphere, click Administration and then select Web Modules from the Portlet Management tree to access portlet
Click Install and browse to the supplied
CQ5 portlet application (cqportlet.war) located
in the opt director of the crx quickstart folder
and click Next to enter other important
information about the portlet.
For other essential portlet information, you can either accept
the defaults or change the values. If you accept the default values,
the portlet is available at
The OSGi administration console provided by the portlet is available
username/password is admin/admin).
Ensure that Start application is selected
and click Finish to finish the
You see a message that your installation was successful.
Configuring the Portlet
After you install the portlet, you need to configure it so that it
knows the URLs of the underlying CQ5 instances (author and publish). In
addition, you can configure additional options.
To configure the portlet:
Be sure you are in the Administration screen and click Portal Management and then Portlets. All portlets are listed. Skip to the last page to see the portlet you just added.
Click ConfigurePortlet. You see the current portlet configurations.
Modify portlet configurations, as necessary. For example, you may need to change the URL for the author and publish instances and the URL for the start path. The following are the default configurations:
Default Portlet Configurations
The base URL to the author instance (without a trailing slash / )
The base URL to the publish instance (without a trailing slash /)
The start path for the content to display (with leading slash / and extension)
The selector to be appended to each content URL (see appendMaxWindowStateAsSelector, appendHelpViewModeAsSelector, and addCssToPortalHeader.)
Indicates whether a selector is appended to a URL if the window is maximized
Indicates whether a selector is appended to a URL if the portlet is in Help mode
Indicates that the included CSS files be added to the portal page header
If the author is also used as a publish instance (for demo or development purposes), turn this flag on. If it is turned on, it appends the wcmmode=disabled flag to each request.
Click OK to save the configuration changes. After you have configured the portlet, you can add it to portal pages and use the portal.
When content is requested from CQ, the portlet uses the current display mode (publish or author) and the current path to assemble a complete URL. With the default values, the first url is http://localhost:4503/content/geometrixx/en.portlet.html. The value of the htmlSelector is automatically added to the URL before the extension.
If the portlet switches to the help mode and the appendHelpViewModeAsSelector is selected, then the help selector is appended as well, for example, http://localhost:4503/content/geometrixx/en.portlet.html.help. If the portlet window is maximized and the appendMaxWindowStateAsSelector is selected, then the selector is appended as well, for example, http://localhost:4503/content/geometrixx/en.portlet.max.help.
The selectors can be evaluated in CQ and a different template can be used for different selectors.
Using a Content Url Map in CQ
Usually the start path points directly to the content in CQ. However if you want to maintain start paths in CQ rather than in the portlet preferences, you can point the start path to a content map in CQ, like /var/portlets. In this case, a script running in CQ can use the submitted information from the portlet to decide which url is the start url. It should issue a redirect to the correct url.
Adding the Portlet to the Portal Page
To add the portlet to the portal page:
Be sure you are in the Administration screen and click Manage Pages.
Click the name of the portlet.
Select an existing page or create a new page.
Edit the page layout.
Click Add Portlets and select the portlet to add it to a container.
Click Done on the Edit Layout page to save your changes.