CQ Portals and Portlets

You are reading the CQ 5.3 version of CQ Portals and Portlets.
This documentation is also available for the following versions: AEM 5.6 CQ 5.5 CQ 5.4

This document describes the following:

CQ Portal architecture
How to configure CQ to act as a portal
How to configure CQ content to appear in a portlet

Note

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.

To configure CQ content to appear in a portal, see How to configure CQ in a portlet.

CQ Portal Container

The CQ5 Portal Container lets you run JSR 286-compliant portlets in CQ. The Portlet component allows you to embed a portlet in the page.

To configure CQ to act as a portal, see Using CQ as a portal.

CQ Portal Director

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.

Note

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.

Portal Security

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.

SSO

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:

<LoginModule class="com.day.crx.security.authentication.CRXLoginModule">
  ...
  <param name="trust_credentials_attribute" value="TrustedInfo"/>
  <param name="anonymous_principal" value="anonymous"/>
</LoginModule>

Enabling PIN authentication

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:

<pre>
<LoginModule class="com.day.crx.security.authentication.CRXLoginModule">
  ...
  <param name="trust_credentials_attribute" value="TrustedInfo"/>
</LoginModule>
</pre>

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 /.

Caching

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.

Name	Description	Default Behavior
Authenticator	Provides the authentication information to CQ	Uses a configurable technical user for both author and publish
ElementRewriter	Rewrites links, images etc.	Rewrites CQ links to portal links, can be extended by a UrlMapper
HttpClientService	Handles all http connections	Standard implementation
LocaleHandler	Handles the locale info	Adds information as request headers and rewrites content link
PortletDecoratorService	Optional service that can be used to add html above and below the portlet, add css, and suppress the toolbar	NA
PrivilegeManager	Checks user rights	Checks access to author instance if user is allowed to edit contents
RequestTracker	Optional service to track portlet invocations	NA
ToolbarLayoutProvider	Optional service to provide layout for the toolbar	NA
ToolbarRenderer	Renders the toolbar	Adds a toolbar with Preview, Edit, Site administration functionality
UrlMapper	Optional service to map portlet urls to portal pages	NA

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

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.

Note

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:

 <servlet>
        <servlet-name>slingportal</servlet-name>
        <servlet-class>org.apache.sling.portal.container.api.ContainerServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>slingportal</servlet-name>
        <url-pattern>/SlingPortletInvoker</url-pattern>
    </servlet-mapping>

Deploying the application

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 at http://<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.

Note

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.

Note

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.

Note

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 administration.
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 http://<wps-host>:<port>/wps/PA_CQ5_Portlet. The OSGi administration console provided by the portlet is available at http://<wps-host>:<port>/wps/ PA_CQ5_Portlet/cqbridge/system/console (default username/password is admin/admin).
Ensure that Start application is selected and click Finish to finish the installation.

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 Configure Portlet. 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

authorBaseUrl	http://localhost:4502	The base URL to the author instance (without a trailing slash / )
publishBaseUrl	http://localhost:4503	The base URL to the publish instance (without a trailing slash /)
startPath	/content/geometrixx/en.html	The start path for the content to display (with leading slash / and extension)
htmlSelector	portlet	The selector to be appended to each content URL (see `appendMaxWindowStateAsSelector`, `appendHelpViewModeAsSelector`, and `addCssToPortalHeader`.)
appendMaxWindowStateAsSelector	TRUE	Indicates whether a selector is appended to a URL if the window is maximized
appendHelpViewModeAsSelector	TRUE	Indicates whether a selector is appended to a URL if the portlet is in Help mode
addCssToPortalHeader	TRUE	Indicates that the included CSS files be added to the portal page header
authorIsUsedAsPublish	FALSE	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.

Content URLs

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.

Using the Portlet

To access the page you added to the portlet in Adding the Portlet to the Portal Page:

In the portlet's personalization menu, configure the portlet as you configured it in the portal.
Click Change. The portlet displays the publish start URL configured in the portlet’s configuration.

Your comments are welcome!

Did you notice a way we could improve the documentation on this page? Is something unclear or insufficiently explained? Please leave your comments below and we will make the appropriate changes. Comments that have been addressed, by improving the documentation accordingly, will then be removed.

COMMENTS

By jclark42796 - 11:21 PM on Aug 04, 2010 Reply
What kind of security (e.g. ACLs) can be applied to portlets. e.g. only users with group X can see this portlet.

ADD A COMMENT

In order to post a comment, you need to sign-in.

Note: Customers with DayCare user accounts need to create a new account for use on day.com.