Visualizzazione del contenuto dell'aiuto per la versione :

This document describes the following:

  • CQ Portal architecture
  • Administering and configuring CQ as a portal
  • Using CQ as a portal
  • Installing, configuring, and displaying CQ content in a portlet (for example, a web server)

CQ Portal Architecture

CQ portal architecture includes definitions of portals, portlets, 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.

You can run JSR 286-compliant portlets in CQ. The portlet component lets you embed a portlet on the page. See Administering the CQ Content Portlet.

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 Installing, Configuring, and Using CQ in a portlet.

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.

The CQ portlet has the following features:

  • Displaying content in a portlet. The portlet displays content, which can be either an entire page or part of a page, from CQ WCM. The template that is used in combination with the provided selectors, defines how you see the content. In particular, the portlet can show content from just one page or provide a whole substructure of a site and show the corresponding navigation. The portlet supports different display modes such as the normal view and the maximized view.

  • Configuring the portlet. You configure the portlet to point directly to the publish CQ5 instance by using a URL that either points directly to the content or to the portlet content map within CQ WCM. If it points to the portlet content map, then the configured URL contains a key for the content and the configuration maps the key to the actual content to be displayed, which allows CQ5 to adjust references, for example if someone moves pages within CQ WCM. .The portlet itself does not know if it points directly to the content or if a configuration map is used. For editing, the base URL to the CQ WCM author instance is configured as well.

  • Layout. The portlet respects portal design/themes. The design (CSS files) are added by the portlet to the portal page, which you can configure. As this is an optional portlet API 2.0 feature, for portlet containers not supporting this feature, you manually add the CSS files to the portal server.

  • Security. User and group information are shared with the portal. CQ WCM respects user information for personalization and access control. The user information from the portal (current user) is forwarded to CQ WCM. The user is already logged into the portal, so the portal is the driving authentication mechanism. CQ WCM (and therefore CRX) receives enough information to handle this properly. SSO scenarios are supported through existing and/or custom authenticators. As the portlet can connect to different CQ WCM instances (especially publish and author for display and editing), potentially different user information needs to be properly handled. Because this handling can be very specific to a given environment, a mechanism is provided that allows for plugging diverse authenticators. In addition to this proper user handling, it is also possible to configure the portlet to just use one technical user.

  • Multi-Language. Content from CQ WCM respects the portal language. The portlet standard specification requires that available languages for a portlet are configured per portlet. The portal forwards the preferred language of the user to the CQ portlet which, in turn, forwards this to the CQ WCM server. The mechanism to provide the correct language uses structural information about the site, that is, the request is mapped to language specific URLs inside the portlet. This mechanism is pluggable to allow for customization.

  • Links. All links in the portlet must be rewritten properly.

  • Caching. The portlet can be configured to point to the dispatcher instead of directly pointing to the CQ server. In this scenario, the dispatcher cache is used. The portlet also has its own cache. The implementation of the cache can be replaced by a custom implementation if needed.

  • Editing Content. The CQ portlet provides links to configure the portlet and edit its content. The CQ WCM part of the configuration determines how to handle the content that is shown in the portlet. You edit in the CQ WCM authoring environment. If necessary, you can also access the Websites tab through an additional link in the tree instead of directly editing a page. It might still be necessary to go to the Websites tab instead of directly editing a page. The editing functionality is only available if the current user has the credentials to edit a page. By default, the CQ5 author instance is queried to detect if the user is an author.

  • Non Functional. Wherever possible, portlet integration is based on standards (in particular JSR 286), so it is generic for all portal environments that support this standard. Setups with one portal and multiple CQ WCM instances as well as multiple portal instances and one CQ WCM instance are supported.

Administering the CQ Content Portlet

The CQ content portlet enables you to display CQ content in a portal. The portlet is available at /crx-quickstart/opt/portal, and can be customized in various ways. For example, you can customize the SSO/Authentication handling by deploying your own authentication service generating the required authentication information for CQ to overwrite the default behavior. The plugins use a defined API that lets you add your own functionality by building the plugin against the API. The plugin can be deployed into the running portlet. To function properly, it needs a configuration of the CQ author and publish instance together with the content path to display on startup.

Some of the configurations can be changed through portlet preferences and others through OSGi service configurations. You change these configurations using config files or the OSGi web console.

Portlet Preferences

Porlet preferences can be configured at deployment time in the portal server or by editing the WEB-INF/portlet.xml file before deploying the portlet web application. The portlet.xml file appears as follows by default:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd /opt/SUNWps/dtd/portlet.xsd"
             version="1.0">
   <portlet>
      <portlet-name>RSSWeatherPortlet</portlet-name>
      <portlet-class>org.jboss.portlet.weather.WeatherPortlet</portlet-class>
      <init-param>
         <name>default_zipcode</name>
         <value>05673</value>
      </init-param>
      <init-param>
         <name>RSS_XSL</name>
         <value>/WEB-INF/Rss.xsl</value>
      </init-param>
      <init-param>
         <name>base_url</name>
         <value>http://xml.weather.yahoo.com/forecastrss?p=</value>
      </init-param>
      <expiration-cache>180</expiration-cache>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>VIEW</portlet-mode>
         <portlet-mode>EDIT</portlet-mode>
      </supports>
      <portlet-info>
         <title>Weather Portlet</title>
      </portlet-info>
      <portlet-preferences>
         <preference>
            <name>expires</name>
            <value>180</value>
         </preference>
         <preference>
            <name>RssXml</name>
            <value>http://xml.weather.yahoo.com/forecastrss?p=33145</value>
            <read-only>false</read-only>
         </preference>
      </portlet-preferences>
   </portlet>
</portlet-app>

The portlet can be configured with the following preferences:

startPath

This is the start path of the portlet: it defines the content that is initially displayed.

Important: If the portlet is configured to connect to CQ author and publish instances that are running on a context path different than /, you need to enable the force CQUrlInfo in the Html Library Manager configuration of these CQ instances (e.g. via Felix Webconsole) or editing will not work and the preferences dialog will not appear.

htmlSelector The selector that is appended to each url. By default this is portlet,  so all requests to html pages use urls ending in .portlet.html. This allows the use of custom scripts within CQ for portlet rendering.
addCssToPortalHeader

By default css files included in the HTML page from CQ are included in the portlet. Disabling this option excludes the default css files.

If this option is enabled, the CSS files are either added to the head of the html page or embedded in the html page depending on the behavior of the portal.

includeToolbar By default, a toolbar is rendered inside the content portlet for management functionality. By disabling this option, no toolbar is rendered.
urlParameterNames

List of alternative URL parameter names that might contain the new content URL to display for the portlet. The list is processed top to bottom, the first parameter containing a value is used. If no URL is found, the default URL parameter is used. The provided URL is used, as is, without any further modification.

This setting is per deployed portlet - it is also to globally configure some url parameters in the OSGi configuration for the "Day Portal Director Portlet Bridge".

preferenceDialog Path to the preferences dialog in CQ - if left empty, the built-in preferences dialog will be used. This defaults to /libs/portal/content/prefs.html.
initialRedirect By default, the portlet performs a javascript redirect of the whole portal page on the first invocation. This is to support the drag and drop scenario of modern portal servers. In production this redirect is rarely needed and can therefore be turned off with this preference being set to false.

OSGi Web Console

Assuming the portal server runs on host localhost, port 8080 and the CQ portlet web application is mounted in the web application context cqportlet, the url to for the web console is http://localhost:8080/cqportlet/cqbridge/system/console. The default user and password is admin.

Open the Configurations tab and select Day Portal Directory CQ Server Configuration. Here you specify the base URL to the author and the publish instance. This procedure is described in Configuring the Portlet.

Nota:

The OSGi web console is only meant for changing configurations during development (or testing). Make sure to block requests to the console for production systems.

Providing Configurations

To support automated deployments and configuration provisioning, the CQ content portlet has built-in configuration support that tries to read configurations from the classpath provided to the portlet application.

On startup, the system property com.day.cq.portet.config is read to detect the current environment. Usually, the value of this property is something like dev, prod, test and so on. If no environment is set, no configurations are read.

If an environment is set, a config file is searched in the classpath at com/day/cq/portlet/{env}.config where env is replaced with the actual value for the environment. This file should list all configuration files for this environment. These files are searched relative to the location of the config file. For example, if the file contains a line my.service.xml, this file is read from the classpath at com/day/cq/portlet/my.service.config. The name of the file consists of the persistence ID of the service, followed by .config. In the previous example, the persistence ID is my.service. The format of the configuration file, is the format used by the Apache Sling OSGi installer.

This means, for each environment, a corresponding config file needs to be added. A configuration that should be applied to all environments needs to be entered in all these files - if it is just for a single environment, it is just entered in that file. This mechanism ensures full control over which configuration is read in which environment.

It is possible to use a different system property to detect the environment. Specify the system property com.day.cq.portet.configproperty containing the name of the system property to use instead of com.day.cq.portet.config.

Caching and Caching Invalidation

The portlet, in its default configuration, caches the responses it receives from CQ WCM in a user-specific cache. The caches need to be invalidated when changes occur in the content of the publish instance. For this purpose, in CQ WCM a replication agent must be configured on the author instance. The cache can also be flushed manually. This section describes both of those procedures.

The portlet can be configured with its own cache, so that the content in the portlet displays without requiring access to CQ. The portal is available as content in /libs/portal/director. To access the content, start a CQ instance and download, using CRXDE Lite or Webdav, the file from that location.

You can either deploy this bundle at runtime or add it to the portlet web application at WEB-INF/lib/resources/bundles before the deployment.

After the cache is deployed, the portlet caches contents from the publish instance. The portlet cache can be invalidated with a dispatcher flush from CQ. To configure the portlet to use its own cache:

  1. Configure a replication agent in author that targets the portal server. 
  2. Assuming that 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.
    Note: Instead of using a request parameter, you can send an http header named Path.

Flushing the Cache via Replication Agent

Just like the normal dispatcher invalidation, a replication agent can be configured to target the portal's CQ5 portlet cache. After you configure the replication agent, every regular page activation flushes the portal cache.

If you operate several portal nodes running the CQ portlet, you need to create an agent for each node as described in this procedure.

To configure a replication agent for the portal:

  1. Log in to the author instance.

  2. In the Websites tab, click the Tools tab.

  3. Click New Page... in the replication agents New... menu.

    Screen shot 2012-02-15 at 4.06.47 PM
  4. In Template, select Replication Agent, and enter a name for the agent. Click Create.

  5. Double-click the replication agent you just created. It displays as invalid as it has not yet been configured.

    Screen shot 2012-02-15 at 4.10.01 PM
  6. Click Edit.

  7. In the Settings tab, select the Enabled check box, select Dispatcher Flush as the serialization type, and enter a retry timeout (for example, 60000).

  8. Click the Transport tab.

  9. In the URI field, enter the flush URI (URL) of the portlet. The URI is in the following form:

    http://<wps-host>:<port>/<wps-context>/<cq5-portlet-context>/cqbridge/cqpcache
  10. Click the Extended tab.

  11. In the HTTP Method field, type GET.

  12. In the HTTP Headers field, click + to add a new entry and type Path: {path}.

  13. If necessary, click the Proxy tab and enter proxy information to the agent.

  14. Click OK to save changes.

  15. To test the connection, click the Test Connection link. A log message appears that indicates whether the replication test succeeded. For example:

Manually Flushing the Portlet Cache

You can manually flush the portlet cache by accessing the same URL configured for the replication agent. See Flushing the Cache for the form of the URL. In addition, the URL needs to be extended with a URL parameter Path=<path> to indicate what to flush.

For example:

http://10.0.20.99:10040/wps/PA_CQ5_Portlet/cqbridge/cqpcache?Path=* flushes the complete cache. http://10.0.20.99:10040/wps/PA_CQ5_Portlet/cqbridge/cqpcache?Path=/content/mypage/xyz flushes /content/mypage/xyz from the cache.

Portal Security

The portal is the driving authentication mechanism. You can log into 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.

Authentication on Publish

This section describes the available authentication modes the portlet can use in communicating with the underlying CQ WCM instances.

By default no user information is sent to the publish instance of CQ; the content is always displayed as the anonymous user. If user specific information should be delivered from CQ or if user authentication for publish is required, this has to be turned on.

Accessing the Portlet's Authentication Configuration

Authentication configuration options that the portlet uses in CQ WCM instances are available in the Web console (OSGi configuration).

Nota:

When working with AEM there are several methods of managing the configuration settings for OSGi services (console or repository nodes).

See Configuring OSGi for full details.

To access the portlet's authentication configuration:

  1. Access the Web console at the following URL:

    http://:///cqbridge/system/console

    For example, in its default configuration:

    http://wps-host:10040/wps/PA_CQ5_Portlet/cqbridge/system/console

  2. Log in to the Web console. The default credentials are admin/admin.  

  3. In the console, select Configuration.

  4. In the Configuration menu, select a particular service to configure. Services are provided by the portlet in the OSGi framework.

    Service Name Description 
    Day Portal Director Authenticator Configure which authentication mode is used for CQ WCM instances. Depending on the selected mode, a technical user or the name of the SSO cookie can be specified. Also, authentication for CQ WCM publish instances can be enabled.
    Day Portal Director File Cache Configure the parameters of how the portlet caches responses it receives from CQ WCM instances.
    Day Portal Director HTTP Client Service Configure how the portlet connects via HTTP to underlying CQ WCM instances. You can, for example, specify a proxy server.
    Day Portal Director Locale Handler Configure which locales the portlet supports. Requests to CQ WCM instances are based on the user locale; for example, user language German would request /content/geometrixx/de/....
    Day Portal Director Privilege Manager Configure whether the portlet should test the Websites tab based on the currently logged in user.
    Day Portal Director Toolbar Renderer Customize the rendering of the portlet's toolbar.
  5. In addition, you can configure the Web console and the logging service. For example, you can change the admin credentials for the Web console by clicking the Apache Felix OSGi Management Console link.

Technical User Mode

In default mode, all requests issued by the portlet for the CQ WCM author instance are authenticated using the same technical user, regardless of the current portal user. Technical User mode is enabled by default. You enable/disable this mode in the respective configuration screen in the OSGi management console:

The technical user specified must exist on the CQ WCM author instance and on the publish instance if Authenticate on Publish is enabled. Be sure to give the user access privileges sufficient for authoring work.

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>

SSO Authentication Mode

The portlet can authenticate for CQ WCM using the Single Sign On (SSO) scheme. In this mode, the user currently logged in to the portal is forwarded to CQ WCM in the form of an SSO cookie. If SSO mode is used, all portal users with access to the CQ portlet must be known to the underlying CQ WCM instances, most commonly in the form of CQ WCM being connected to LDAP, or by having manually created the users beforehand. Also, before enabling SSO in the portlet, the underlying CQ WCM author instance (and the publish instance, if Authenticate on Publish is enabled) needs to be configured to accept SSO-based requests.

To configure the portlet to use SSO authentication mode, complete the following steps (described in detail in the following sections):

  • Enable CQ WCM's CRX to accept trusted credentials.
  • Enable SSO authentication in the CQ WCM.
  • Enable SSO Authentication in the CQ portlet.

Enabling CQ WCM's CRX to accept trusted credentials

Before SSO can be enabled for CQ WCM, the underlying CRX instance needs to be configured to accept the trusted credentials provided by CQ WCM. To do this, you configure CRX's repository.xml.

  1. In the file system where CQ WCM is installed, open the following file:

    //crx-quickstart/repository/repository.xml

  2. In the XML file, find the entry for the LoginModule and add the trust_credentials_attribute to its configuration:

    <LoginModule class="com.day.crx.security.authentication.CRXLoginModule">
      ...
      <param name="trust_credentials_attribute" value="TrustedInfo"/>
      <param name="anonymous_principal" value="anonymous"/>
    </LoginModule>
  3. Restart CQ WCM for the changes to take effect.

Enabling SSO authentication in the CQ WCM

To enable SSO in CQ WCM, access the relevant configuration entry in the CQ WCM's Apache Felix Web Management Console (OSGi):

  1. Access the console through its URI at http://<cq5-host>:<port>/system/console.

  2. In the Configuration menu, select SSO Authentication Handler. In this example, the SSO handler accepts SSO requests for all paths based on the cookie provided by the CQ portlet. Your configuration may vary.

    Path / Enables SSO handler for all requests
    Cookie Names cqpsso Name of the cookie provided by the portlet as configured in the portlet's OSGi console.
  3. Click Save to enable SSO. SSO is now the primary authentication scheme.

For every request CQ WCM receives, first the SSO-based authentication is attempted. Upon failure, a fallback to the usual basic authentication scheme is performed. As such, normal connections to CQ WCM without SSO remain possible.

Enabling SSO Authentication in a CQ Portlet

In order for the underlying CQ WCM instance to accept SSO requests, the portlet’s authentication mode has to be switched from Technical to SSO.

To enable SSO authentication in a CQ portlet:

  1. Access the console through its URI at http://<cq5-host>:<port>/system/console.

  2. In the Configuration menu, select Day Portal Director Authenticator from the list of available configurations.

  3. In Mode, select SSO. Leave the other parameters with their default values.

    chlImage_1
  4. Click Save to enable SSO for the portlet.

    For testing purposes, access the portlet with your portal's administrative user, after you create the same user in CQ WCM with administrator privileges.

After performing this procedure, requests are authenticated using SSO. A typical snippet from the HTTP communication reveals the presence of the following SSO and Portlet specific headers:

C-12-#001898 -> [GET /mynet/en/_jcr_content/par/textimage/image.img.png HTTP/1.1 ]
C-12-#001963 -> [cq5:locale: en ]
C-12-#001979 -> [cq5:used-locale: en ]
C-12-#002000 -> [cq5:locales: en,en_US ]
C-12-#002023 -> [cqp:user: wpadmin ]
C-12-#002042 -> [cqp:portal: IBM WebSphere Portal/6.1 ]
C-12-#002080 -> [cqp:windowid: 7_CGAH47L000CE302V2KFNOG0084 ]
C-12-#002124 -> [cqp:windowstate: normal ]
C-12-#002149 -> [cqp:portletmode: view ]
C-12-#002172 -> [User-Agent: Jakarta Commons-HttpClient/3.1 ]
C-12-#002216 -> [Host: 10.0.0.68:4502 ]
C-12-#002238 -> [Cookie: $Version=0; cqpsso=Basic+d3BhZG1pbg%3D%3D ]
C-12-#002289 -> [ ]

Enabling PIN authentication

If you are not using the default inline editing features of the CQ content portlet, but want the authoring and administration part of the portlet outside the portal directly in the CQ author instance, you should enable PIN authentication. You also need to change the configuration of the management buttons.

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:

    <LoginModule class="com.day.crx.security.authentication.CRXLoginModule">
      ...
      <param name="trust_credentials_attribute" value="TrustedInfo"/>
    </LoginModule>
  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 /.

Privileges

Some functions of the portlet are protected by privileges. The current user needs to have this privilege in order to be able to access this function. There are the following privileges pre-defined:

  • "toolbar" : This is the general privilege to see/use the toolbar in the portlet.
  • "prefs" : If the user has this privilege, the user is allowed to see/change the preferences of the portlet.
  • "cq-author:edit" : With this privilege, the user is allowed to invoke the edit view of the content.
  • "cq-author:preview" : With this privilege, the user is allowed to see the preview.
  • "cq-author:siteadmin" : With this privlege, the user is allowed to open the siteadmin within CQ.

The best approach to manage the privileges is to use portal roles and assign roles to these privileges. This can be done through an OSGi configuration. The "Day Portal Director Privilege Manager" can be configured with a set of roles for each privilege. If the user has one of the roles, the user has the corresponding privilege.

In addition it is possible to define this role based access on a per portlet instance base. The preferences dialog of the portlet contains an input field for each of the above privileges. For each privilege a comma-separated list of portlet roles can be configured. If a value is configured, this overrides the global configuration from the "Day Portal Director Privilege Manager" service and it might be required to add the same roles from this global setting as the roles are not merged! If no value is specified, the global configuration is used.

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 of 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

Toolbar Buttons

The toolbar and its buttons are configurable and can be customized. You can add your own buttons to the toolbar or define which buttons are displayed in which mode. Each button is an OSGi service configurable through an OSGi configuration.

The OSGi web console lists all button configurations on the Configuration tab. For each button, you can define in which mode this button is displayed. This lets you disable a button by removing all modes for example.

By default, the CQ content portlet uses the inline editing functionality. However, if you prefer to switch into the CQ author instance for editing, enable the SiteAdmin Button and the ContentFinder Button, but disable the Edit Button. In this case, make sure to correctly configure the PIN authentication in CQ.

The portlet's toolbar layout can be customized by installing a bundle through the portlet's Felix Web Console, which contains custom CSS/HTML at a predefined location.

Bundle Structure

The following is an example bundle structure:

$ jar tvf target/toolbarlayout-0.0.1-SNAPSHOT.jar | awk '{print $8}'
META-INF/
META-INF/MANIFEST.MF
/com/day/cq/portlet/toolbar/layout/
/com/day/cq/portlet/toolbar/layout/author.gif
/com/day/cq/portlet/toolbar/layout/back.gif
/com/day/cq/portlet/toolbar/layout/button.html
/com/day/cq/portlet/toolbar/layout/edit.gif
/com/day/cq/portlet/toolbar/layout/manage.html
/com/day/cq/portlet/toolbar/layout/publish.html
/com/day/cq/portlet/toolbar/layout/refresh.gif
/com/day/cq/portlet/toolbar/layout/siteadmin.gif
/com/day/cq/portlet/toolbar/layout/toolbar.css

The META-INF folder contains the MANIFEST.MF file required by OSGi to identify it as a bundle. It appears as follows:

Manifest-Version: 1.0
Built-By: djaeggi
Created-By: Apache Maven Bundle Plugin
Import-Package: com.day.cq.portlet.toolbar.layout
Bnd-LastModified: 1234178347159
Export-Package: com.day.cq.portlet.toolbar.layout
Bundle-Version: 0.0.1.SNAPSHOT
Bundle-Name: Company CQ5 Portal Director Portlet Toolbar Layout
Bundle-Description: This bundle provides a custom layout for the CQ5 P
 ortal Director Portlet Toolbar.
Build-Jdk: 1.5.0_16
Bundle-ManifestVersion: 2
Bundle-SymbolicName: com.day.cq.portlet.company.toolbarlayout
Tool: Bnd-0.0.255

The fact that the HTML/CSS/images are within the /com/day/cq/portlet/toolbar/layout folder is mandated by the portlet and cannot be changed. Along the same lines, the Import-Package and Export-Package headers in MANIFEST.MF must be called /com/day/cq/portlet/toolbar/layout as well. The Bundle-SymbolicName must be a unique, fully qualified package name.

You can build it using a tool such as maven or manually create such a jar file with the relevant header set as shown in this section.

Portlet Toolbar Views

The portlet's toolbar basically has two view states. Each view and associated buttons can be customized with a respective HTML file.

Publish View

The publish view only has one button that switches the toolbar to the Manage view. The publish view is represented by the publish.html file in previous bundle. In the HTML, you can use the following placeholders, which are replaced by the portlet with the respective contents when rendered:

Publish View Placeholders

Placeholder  String Description 
{buttonManage} Placeholder is replaced by the Manage button, which switches the portlet state into the management state.

Manage View

The manage view has four buttons: Edit, Websites tab, Refresh and Back. The manage view is represented by the manage.html file in the previous bundle. In the HTML, you can use the following placeholders, which are replaced by the portlet with the respective contents when rendered:

Manage View Placeholders

Placeholder String  Description 
{buttonEdit} Placeholder is replaced by the Edit button, which opens a new window with the current page in CQ's edit mode.
{buttonWebsites tab} Placeholder, replaced by a button which opens the Websites tab of CQ WCM.
{buttonRefresh} Refreshes the current view.
{buttonBack} Switches the portlet back into the publish view.

Buttons

Buttons, on whichever view they appear, use the same common HTML, defined in button.html.

In the HTML, you can use the following placeholders, which are replaced by the portlet with the respective contents when rendered:

Manage and Publish View Buttons

Placeholder String  Description 
{name} Name of the button, for example, author, back, refresh, and so on.
{id} CSS id of the button.
{url} URL for the button's target.
{text} Label of the button.
{onclick} Javascript onclick function (contains {url}).

Example of a button.html file:

<div class="cqp_button">

 <a href="#" onclick="{onclick}">

 <img src="/wps/PA_CQ5_Portlet/cqbridge/static/{id}.gif" alt="{text}" 
title="{text}"/>

 </a>
</div>

Installing a Custom Layout

To install a custom layout, access the portlet’s OSGI Web console Bundles section and upload the bundle.

Packages

If you need to upload, or create, packages for your installation, then see Package Manager in the CRX documentation for detailed instructions.

Link Handling

All links are rewritten to work within the portal context. By default links with render parameters are used. The Day Portal Director HTML Rewriter can be configured to use action links instead.

You can also define additional request parameters to be queried for the content path to be displayed. This is useful, for example, if there is a link from the outside to specific content.

In addition, the Day Portal Director HTML Rewriter can be configured with a list of regular expressions defined excludes for link rewriting. For example, if you have relative links to external systems, you should add them to this exclude list.

Localization

The CQ content portlet has a built-in localization feature, which ensures that the content from CQ is in the correct language.

This is done in two steps:

  1. The Day Portal Directory Locale Detector detects the locale of the portal user by getting the locale setting from the portal. This service must be configured with the list of available languages in CQ.
  2. The Day Portal Director Locale Handler handles the localization of the current request. It takes the path of the requested content, for example /content/geometrixx/en/company.html and according to the configuration, it rewrites the en with the actual locale of the user.

The Day Portal Director Locale Handler can be configured with the paths to check for locale information - usually this includes everything under /content and with the position of the locale information in the path. By default, the locale handler follows the recommondation of structuring multi-language sites within CQ.

If your site has no strict rule for handling the locale information within the path, it is possible to replace the locale handler with your own implementation.

Optional OSGi Services

Optional OSGi services can be implemented to customize various parts of the portlet. Each service corresponds to a Java interface. This interface can be implemented and deployed through a bundle into the portlet.

RequestTracker The request tracker gets notified whenever content is displayed by the portlet. This allows you to keep track of the invocations of the portlet.
InvocationContextListener Listener that is invoked at the beginning and end of each request to the portlet. The listener can be used to change or add information for the current request.
ErrorHandler Custom error handler for errors during the render phase.
HttpProcessor This service can be used to add information to each http invocation to CQ.
PortletAction Add an own action to the portlet - this action can be invoked through a portlet action link.
PortletDecoratorService This service can be used to decorate the contents of the portlet.
ResourceProvider Add your own resource provider to deliver some resource through a portlet resource link to the client.
TextMapper Allows you to post process HTML, CSS and Javascript files.
ToolbarButton Add your own button to the toolbar.
UrlMapper Add a service to apply a custom url mapping or rewriting.
UserInfoProvider Add your own information about the user. This service can be used to get information from the portal to the portlet.

Replacing Default Services

The following services have a default implementation in the content portlet (with a corresponding Java interface). To customize, a bundle containing the new service implementation needs to be deployed into the portlet application.

When implementing such a service, make sure to set the service.ranking property of the service to a positive value. The default implementation uses the ranking 0 and the portlet uses the service with the highest ranking.

Name Description Default Behavior
Authenticator Provides the authentication information to CQ Uses a configurable technical user for both author and publish. Or SSO can be used.
HTMLRewriter Rewrites links, images etc. Rewrites CQ links to portal links, can be extended by a UrlMapper and a TextMapper
HttpClientService Handles all http connections Standard implementation
LocaleHandler Handles the locale info Rewrites a link to the content with respect to the locale.
LocaleDetector Detects the locale of the user. Uses the locale provided by the portal.
PrivilegeManager Checks user rights Checks access to author instance if user is allowed to edit contents
ToolbarRenderer Renders the toolbar Adds a toolbar functionality

Portlet Events

The portlet API (JSR-286) specifies portlet events. The CQ content portlet has an integrated bridge, distributing portlet events for the CQ portlet as OSGi events - this makes handling of portlet events pluggable.

If you want to handle specific events, declare these as receiving events in the deployment descriptor (or configure it through your portal server) and implement an OSGi service declaring the EventHandler interface (see OSGi EventAdmin specification).

Whenever a portlet event occurs, a specific OSGi event is sent invoking your handler. The handler gets all context information and can update the status of the portlet accordingly or sent new events. Basically, inside the handle method all functionality of the portlet event phase can be used.

Using CQ as a Portal

Use the Portlet component to add portlet windows to CQ pages. Shared libraries that you install to the application server enable the Portlet component to detect deployed portlet applications.

To use CQ as a portal, perform the following tasks:

  1. Install the Portlet component and shared libraries.
  2. Add the Portlet component to Sidekick.
  3. Configure and deploy the web application that contains the portlets that you want to appear in the Portal component.
  4. Add the Portlet component to a page and select the portlet to display.

Nota:

You can use the portlet component only when CQ is deployed as a web application. (See Installing CQ5 With an Application Server.)

Installing the portlet component

The CQ5.5 Quickstart JAR file contains the portlet component files. To obtain the files (cq-portlet-components.zip), you can either execute the Quickstart, or extract the contents. 

  1. Execute or extract the contents of the Quickstart JAR file, and locate the cq-portlet-components.zip file accordingly:
    • Execute Quickstart: crx-quickstart/opt/portal
    • Extract Quickstart contents: static/opt/portal
  2. Open Package Manager of the CQ5 author instance that is deployed to the application server. (http://appserverhost:port/cq5author/crx/packmgr)
  3. Use Package Manager to Upload and install the cq-portlets-components.zip package.

    The package installs the cq-portlet-director-sharedlibs-x.x.x.jar in the /libs/portal/director folder in the repository.

  4. Copy cq-portlet-director-sharedlibs-x.x.x.jar to your hard drive. Use any means to obtain the file, for example FileVault or a WebDAV client.
  5. Move the cq-portlet-director-sharedlibs.x.x.x.jar file to the shared library folder of your application server so that the classes are available to deployed portlet applications.

Adding the Portlet component to Sidekick

Add the portlet component to the paragraph system so that it is available to authors. 

  1. In Sidekick, click the ruler icon to enter Design mode.
  2. Beside the Design of par heading above the first paragraph, click Edit.
  3. In the General component category, select the check box next to the Portlet component and click OK.
chlImage_1

Configuring and deploying your portlet applications

Deploy the portlets to the application server web container so that they are available to the Portal component. Before you deploy the portlet application, you need to configure the application so that it loads the CQ portal container servlet. This configuration enables the Portlet component to access the portlets.

  1. Extract the contents of the portlet application WAR file.

    Tip: The jar xf nameofapp.war command extracts the files.

  2. Open the web.xml file in a text editor.

  3. Add the following servlet configuration inside the web-app element:

    <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>
  4. Save the web.xml file and repackage the WAR file.

    Tip: The jar cvf nameofapp.war * command adds contents of the current directory to the nameofapp.war file. 

  5. Deploy the portlet application to the application server. For information, refer to the documentation for your application server.

Adding portlets to your CQ page

Use the Portal component to add a portlet window to your web page. Use the component properties to specify the portlet to display.

  1. On the web page, drag the Portlet component from the General group in Sidekick to the page.

    Nota:

    After you drag the component to the page, reload the page to ensure that it works properly.

  2. Double-click the component to open the Portlet properties.

  3. In the Portlet Entity drop-down menu, select the portlet from the list.

  4. Select or clear the Hide Title Bar check box depending on whether you want to see the portlet's title bar.

  5. In the Portlet Window field, enter a unique Portlet Window ID, if desired.

    Nota:

    If you plan to use the same portlet more than once on the same page, give each portlet a different window ID.

  6. Click OK. The portlet displays on your CQ page.

    chlImage_1

Installing, Configuring, and Using 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. The portal director is available as content in the repository under /libs/portal/directory. You will need to download the application war file before using it.

Downloading the war file

  1. Using either Webdav or CRXDE Lite, navigate to /libs/portal/director.

  2. Download cq-portlet-webapp.war.

Nota:

These procedures use the Websphere portal as an example although they are as generic as possible; please be aware that procedures vary for other web portals. Although the steps are essentially identical for all web portals, you need to repurpose the steps for your particular web portal.

Installing the portlet

To install the portlet:

  1. Log in to the portal with administrator privileges.

  2. Navigate to the Portlet Management part of your web portal.

  3. Click Install and browse to the CQ5 portlet application (cq-portlet-webapp.war) you downloaded and 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).

  4. Ensure that the portlet application automatically starts by selecting that option or check box and save your changes. 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). You also can configure other options.

To configure the portlet:

  1. In the Portal administration window of the app server, navigate to portlet management, where all portlets are listed and select the CQ Portal Director portlet.

  2. Configure the portlet, as necessary. For example, you may need to change the URL for the author and publish instances and the URL for the start path. Default configurations are described in Portlet Preferences.

    Nota:

    If the portlet is configured to connect to CQ author and publish instances that are running on a context path different than /, you need to enable the force CQUrlInfo in the Html Library Manager configuration of these CQ instances (e.g. via Felix Webconsole) or editing will not work and the preferences dialog will not appear.

  3. Save the configuration changes in the app server.

  4. Navigate to the OSGI admin console for the portlet. The default location is http://<wps-host>:<port>/wps/PA_CQ5_Portlet/cqbridge/system/console/configMgr. The default username/password is admin/admin.

  5. Select the Day Portal Director CQ Server Configuration configuration and edit the following values:

    • Author Base URL: The base URL for the CQ author instance.
    • Publish Base URL: The base URL for the CQ publish instance.
    • Author Is Used As Publish: Is the author instance used as a publish
      instance (for development)?
    chlImage_1
  6. Click Save. You can now add the portlet 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:

  1. Be sure you are in the administration window of your app server and navigate to the location where you manage pages. (for example, in WebSphere 6.1, click Manage Pages).

  2. Select the name of the portlet and then select an existing page or create a new page.

  3. Edit the page layout.

  4. Select the portlet and add it to a container. 

  5. Save your changes.

Using the Portlet

To access the page you added to the portlet:

  1. In the portlet's personalization menu, configure the portlet as you configured it in the portal.

  2. Open the configuration (The portlet displays the publish start URL configured in the portlet’s configuration) and make edits as necessary, then save them.

Questo prodotto è concesso in licenza in base alla licenza di Attribuzione-Non commerciale-Condividi allo stesso modo 3.0 Unported di Creative Commons.  I post su Twitter™ e Facebook non sono coperti dai termini di Creative Commons.

Note legali   |   Informativa sulla privacy online