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
This document describes the following:
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 includes definitions of portals, portlets, the CQ Portal Container, and the CQ Portal Director.
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.
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.
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.
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.
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:
<LoginModule class="com.day.crx.security.authentication.CRXLoginModule"> ... <param name="trust_credentials_attribute" value="TrustedInfo"/> <param name="anonymous_principal" value="anonymous"/> </LoginModule>
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 /.
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:
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:
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.
|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|
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.
To configure to use CQ as a portal, you need to do the following:
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:
Deploying portlets includes rewriting the portlet application's web.xml file and deploying the application.
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:
<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>
After configuring the portlet application's web.xml file, deploy the portlet through the admin console.
To deploy the application:
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.
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).
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.
Clickand browse to the supplied CQ5 portlet application (cqportlet.war) located in the opt director of the crx quickstart folder and click 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 thatis selected and click to finish the installation.
You see a message that your installation was successful.
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 thescreen and click and then . All portlets are listed. Skip to the last page to see the portlet you just added.
Click. 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|
||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.
Clickto 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.
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.
To add the portlet to the portal page:
Be sure you are in thescreen and click .
Click the name of the portlet.
Select an existing page or create a new page.
Edit the page layout.
Clickand select the portlet to add it to a container.
Clickon the Edit Layout page to save your changes.
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. The portlet displays the publish start URL configured in the portlet’s configuration.