1. No category

CQ5 WCM How To - A Collection
CQ5 WCM How To - A Collection
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Contents
1. Introduction ........................................................................................................................ 1
1.1. Introduction ............................................................................................................. 1
1.2. Purpose of this Document ........................................................................................ 1
1.3. Target Audience ...................................................................................................... 1
2. How to Quickly Create a Website ....................................................................................... 2
2.1. Introduction ............................................................................................................. 2
2.2. Creating the application, the Content Page Template, the Content Page Component
and a Web Page ........................................................................................................... 2
2.3. Setting up the Designer ........................................................................................... 3
2.4. Importing the original Web Page (CSS, HTML and images) into your project ................ 3
2.5. Replacing static content by dynamic content using CQ Foundation Components .......... 4
2.6. Creating a Media Library ......................................................................................... 5
3. How to Develop Components ............................................................................................. 6
3.1. Developing Components .......................................................................................... 6
3.1.1. Developing a new component by adapting an existing component .................... 6
3.1.2. Adding a new component to the paragraph system (design mode) ................... 7
3.1.3. Extending the Text and Image Component - An Example ................................ 7
4. How to Set Up a Cluster .................................................................................................. 14
4.1. How to Set Up a Cluster in Communiqué ................................................................ 14
5. How to Monitor Performance ............................................................................................ 16
5.1. Introduction ........................................................................................................... 16
5.1.1. Purpose of this How To .............................................................................. 16
5.1.2. Target Audience ......................................................................................... 16
5.2. Performance - some theory .................................................................................... 16
5.3. Performance - basic rules ...................................................................................... 18
5.4. Recognizing some common performance problems ................................................. 18
5.5. Monitoring, and optimizing, the performance ........................................................... 19
5.5.1. Tools and mechanisms ............................................................................... 19
5.5.2. Interpreting the request.log .......................................................................... 20
5.5.3. Caching ...................................................................................................... 22
5.5.4. Analyzing Search ........................................................................................ 24
6. How to Create and Use a Workflow .................................................................................. 25
6.1. Creating a Workflow .............................................................................................. 25
6.1.1. Creating a new Workflow Model .................................................................. 25
6.1.2. Editing the Workflow ................................................................................... 25
6.2. Using the Workflow ............................................................................................... 28
6.2.1. Starting the Workflow for an individual page ................................................. 28
6.2.2. Automatically Assigning a Workflow ............................................................. 30
6.2.3. Taking actions on a Participant Step ............................................................ 32
6.2.4. Suspending, Resuming and Terminating a Workflow instance ........................ 34
6.2.5. Monitoring the Status of Workflow Instances ................................................. 35
7. Upgrading to CQ5 ............................................................................................................ 37
7.1. How to Upgrade Your Communiqué Instance (3 or 4) to CQ5 ................................... 37
8. Installing CQ5 .................................................................................................................. 39
8.1. How to Install CQ WCM Author and Publish Instances using Quickstart ..................... 39
8.1.1. Installing a CQ WCM instance - Generic procedure ....................................... 39
8.1.2. Installing an Author instance ........................................................................ 40
8.1.3. Installing a Publish instance ........................................................................ 40
8.2. How to install CQ5 with an Application Server ......................................................... 41
8.2.1. WebSphere v6.1 ......................................................................................... 41
8.2.2. WebLogic v10.3 .......................................................................................... 43
8.2.3. Tomcat v6 .................................................................................................. 45
8.2.4. JBoss v4 .................................................................................................... 47
8.2.5. Generic Procedures .................................................................................... 50
9. How to Use, Create, and Edit a Page ............................................................................... 52
Page iii of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
CQ5 WCM How To - A Collection
10.
11.
12.
13.
14.
15.
16.
17.
18.
9.1. Managing Pages within CQ WCM ..........................................................................
9.1.1. Creating a New Page ..................................................................................
9.1.2. Editing a Page ............................................................................................
9.1.3. Moving or Renaming Page ..........................................................................
9.1.4. Deleting a Page ..........................................................................................
9.1.5. Setting the Page Properties .........................................................................
How to Publish a Page ...................................................................................................
10.1. How To Publish Pages ........................................................................................
10.1.1. Activating Content .....................................................................................
10.1.2. Deactivating Content .................................................................................
10.1.3. Determining Page Publication Status ..........................................................
10.1.4. Locking Pages ..........................................................................................
10.1.5. Unlocking Pages .......................................................................................
10.1.6. Using Preview Mode .................................................................................
How to Restore a Page ..................................................................................................
11.1. How To Restore Pages ........................................................................................
How to Create Templates ...............................................................................................
12.1. Developing Page Templates .................................................................................
12.1.1. Creating a new Template (based on an existing template) ............................
How to Use Tags ...........................................................................................................
13.1. How to Manage Tags in CQ WCM .......................................................................
13.1.1. Using Sidekick to access and assign Tags .................................................
13.1.2. The Tag Administration Console ................................................................
13.1.3. Searching for Tags ....................................................................................
Integrating with CQ DAM ................................................................................................
14.1. How to Integrate CQ DAM into your CQ5 WCM Installation ....................................
How to Find Logs and Audit Entries ................................................................................
15.1. Finding the Audit Records and Log Files ...............................................................
15.1.1. Audit Records ...........................................................................................
15.1.2. Log files ...................................................................................................
Security Checklists .........................................................................................................
16.1. Security Checklist for System Administrators .........................................................
16.1.1. Disable WebDAV ......................................................................................
16.1.2. Restrict Access via the Dispatcher .............................................................
16.1.3. Check for Cross-Site Scripting (XSS) .........................................................
16.2. Security Checklist for Power Users .......................................................................
16.2.1. Change Default Passwords ........................................................................
16.3. Security Checklist for Developers .........................................................................
16.3.1. Use the user session, not the administrative session ...................................
Defining Performance Tests on Your Publish Environment ................................................
17.1. Introduction .........................................................................................................
17.1.1. Purpose of this How To .............................................................................
17.1.2. Target Audience .......................................................................................
17.2. Phases to be used ..............................................................................................
17.3. Verification of Knowledge .....................................................................................
17.3.1. Test Architecture .......................................................................................
17.3.2. Application Map ........................................................................................
17.4. Scope Definition ..................................................................................................
17.5. Test Methodologies ..............................................................................................
17.6. Defining the Performance Goals ...........................................................................
17.6.1. Single Component Tests ...........................................................................
17.6.2. Combined Component Tests ......................................................................
17.6.3. Going Live Tests .......................................................................................
17.6.4. Error Tests ...............................................................................................
17.6.5. Endurance Tests .......................................................................................
17.7. Optimization ........................................................................................................
17.8. Reporting ............................................................................................................
How to Create a Fully Featured Internet Website .............................................................
Page iv of 117
52
52
54
58
59
59
64
64
64
65
65
66
66
66
68
68
69
69
69
70
70
70
71
73
75
75
77
77
77
78
80
80
80
80
81
81
81
83
83
84
84
84
84
84
85
85
85
86
86
87
87
88
88
89
89
89
90
91
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
CQ5 WCM How To - A Collection
19. How to Set Up the Development Environment with Eclipse ............................................... 92
19.1. How to Set Up the Development Environment with Eclipse ..................................... 92
19.1.1. Creating the Project Structure in CQ5 ........................................................ 92
19.1.2. Installing FileVault (VLT) ............................................................................ 92
19.1.3. Installing Eclipse ....................................................................................... 93
19.1.4. Creating the Project Structure in Eclipse ..................................................... 94
19.1.5. Scripting with Eclipse and CQ5 .................................................................. 98
19.1.6. Java Developing with Eclipse and CQ5 .................................................... 100
19.1.7. Building collaborative and automated projects ........................................... 102
20. How to Model Data ....................................................................................................... 103
20.1. Data Modeling - David Nuescheler's Model .......................................................... 103
20.1.1. Source .................................................................................................... 103
20.1.2. Introduction from David ............................................................................ 103
20.1.3. Seven Simple Rules ................................................................................ 103
21. JSP Tag Libraries ......................................................................................................... 109
21.1. JSP Tag Libraries .............................................................................................. 109
21.1.1. CQ Tag Library ....................................................................................... 109
21.1.2. Sling Tag Library ..................................................................................... 113
A. Copyright, Licenses and Formatting Conventions ............................................................. 117
A.1. Formatting Conventions ....................................................................................... 117
Page v of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
1 Introduction
1.1 Introduction
To help you perform certain tasks within CQ5 this collection of How To articles has been compiled.
1.2 Purpose of this Document
To collect all the How To articles into one document.
1.3 Target Audience
• see individual How To sections
Page 1 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
2 How to Quickly Create a Website
2.1 Introduction
This tutorial enables you to quickly create a website with CQ5, based on an existing website. It is
mainly targeted at Day Pre-Sales staff and Day Partners preparing Proof Of Concept for a project.
You only need CQ5 WCM, CQDE and a Web browser.
2.2 Creating the application, the Content Page Template, the
Content Page Component and a Web Page
1.
In CRX Explorer, copy the node apps/geometrixx, name the target node
<customername> and paste it under apps.
2.
Set the title (jcr:title property) of the Template apps/<customername>/templates/
contentpage to <Customername> Content Page Template.
3.
Replace the thumbnail /apps/<customername>/templates/contentpage/
thumbnail.png with one representing your Template.
• Create a PNG image, 128 x 98 px big.
• In your file system, copy the image and paste it into /apps/<customername>/
templates/contentpage/ .
4.
Delete the property allowedPaths of the Template /apps/<customername>/
templates/contentpage.
5.
Set the property sling:resourceType of the node /apps/<customername>/
templates/contentpage/jcr:content to <customername>/components/
contentpage.
6.
In CQDE, under the Component /apps/<customername>/components/contentpage,
create the file contentpage.jsp.
7.
Copy/paste following code into the script contentpage.jsp:
<%@page session="false" contentType="text/html; charset=utf-8" %><%
%><%@taglib prefix="cq" uri="http://www.day.com/taglibs/cq/1.0" %><%
%><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/
strict.dtd">
<html>
<%@include file="/libs/wcm/global.jsp" %><%
%><head>
<cq:include script="/libs/wcm/init/init.jsp"/>
<% currentDesign.writeCssIncludes(out); %>
MyCustomerHead
</head>
<body>
MyCustomerBody
</body>
</html>
8.
In your browser, open the CQ site administration.
9.
Under Websites, create a new page with the Title www.<customername>.com, the label
<customername> and the <Customername> Content Page Template.
10. Under the Page www.<customername>.com, create a new page with the Title English,
the label en and the <Customername> Content Page Template. If needed, create one Page
with the Title French, the label fr and one Page the Title German, the label de.
Page 2 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Quickly Create a Website
11. Under the Page English, create as many pages as needed in order to reproduce the site
map of your customer site.
12. Open the English Page. It should look as follows:
2.3 Setting up the Designer
1.
In CRX Explorer, copy the node /etc/designs/geometrixx, name the target node
<customername> and paste it under /etc/designs.
2.
In contentpage.jsp, insert <% currentDesign.writeCssIncludes(out); %> at the
appropriate location.
3.
In CQDE, open the file /etc/designs/<customername>/static.css and adapt the
styles to your needs.
4.
Link your pages to the <customername> designer: in CRX Explorer, select the node /
content/<customername>/jcr:content. Double-click Property cq:designPath and
set /etc/designs/<customername> as Value.
2.4 Importing the original Web Page (CSS, HTML and images) into
your project
1.
In Firefox, browse to the page that you want to import, select Save Page As …, enter
<customername> as Filename and save it on your desktop.
2.
Test the downloaded website on your desktop: open the downloaded
<customername>.htm file in your browser and compare the result with the original website.
If it is different, open the file in a text editor and fix the problems. Problems are often caused
by paths for css files and images that need to be correctly reset.
3.
In your filesystem, zip all the resources of your webpage (html, css, images, ...).
4.
In CRX Explorer, under the node /apps/<customername>/components/contentpage,
create a New Node: set the Name to resources and the Type to sling:Folder.
Page 3 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Quickly Create a Website
5.
In CRX Content Loader, import the zip file and expand it into the node /apps/
<customername>/components/contentpage/resources:
• Browse to http://localhost:4502/crx/loader/index.jsp.
• Click Browse beside Root path for import:, browse to the node /apps/
<customername>/components/contentpage/resources and click Open.
• Click Browse beside File to upload:, browse to your zip file and click Open.
• Check Auto-Expand and Expand file content directly below selected
root checkboxes.
• Click Import.
Note
In a normal project setup, the resources wouldn't be placed under the Component. It
is only done here to maximize your efficiency.
6.
In CQDE, open the file <customername>.html and copy the content between the <head>
and </head> tags. In the script contentpage.jsp, select
MyCustomerHead
and paste the previously copied content.
7.
In the file <customername>.html, copy the content between the <body> and </body> tags.
In the script contentpage.jsp, select
MyCustomerBody
and paste the previously copied content.
8.
In the script contentpage.jsp, reset the paths of the css files and the images by replacing:
<customername>_files
with:
/apps/<customername>/components/contentpage/resources
Note
Make sure that the names of your resources don't start with _ (underscore).
.
9.
In the script contentpage.jsp, replace all external links with internal links. This way the
external links don't appear broken when your machine is not online.
10. In your browser, in the CQ Site Administration, open the page www.<customername>.com. It
should display your <customername> web page.
2.5 Replacing static content by dynamic content using CQ
Foundation Components
1.
In CQDE, in the file contentpage.jsp, select the content of the middle part of the page and
replace it with:
<cq:include path="par" resourceType="foundation/components/parsys" />
Page 4 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Quickly Create a Website
. The content has been replaced by the parsys Foundation Component.
2.
In your browser, refresh your page. The features of the Paragraph System are now available
to you: you can include other Components, for example, Flash, Text or Text Image.
3.
By following the previous steps, you can add other CQ Foundation Components as for
example topnav or toolnav.
4.
In your browser, in the CQ Site Administration, open a page of your choice from your
application. Copy content from the original web page and paste it into your page.
5.
Adapt the design to look like the design of the original website.
2.6 Creating a Media Library
1.
In your browser, download about 20 resources (pictures, banners, pdf, …) from the original
website: open a Google page, type site:<customer-url>, click search and click the
Images tab. Save the desired resources on your computer.
2.
In your filesystem, zip all the resources.
3.
In CRX Content Loader, import the zip file and expand it into the node content/dam/
<customername>. The resources are now available in the contentfinder, when browsing
through the Pages.
Page 5 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
3 How to Develop Components
3.1 Developing Components
This section describes how to create your own components and add them to the paragraph
system.
A quick way to get started is to copy an existing component and then make the changes you want.
You can also use this method to edit existing components (although Day recommends that you
back up the original component).
An example of how to develop a component is described in detail in Extending the Text and Image
Component - An Example.
3.1.1 Developing a new component by adapting an existing component
To develop new components for CQ WCM based on existing component, you copy the component
and create a javascript file for the new component and store it in a location accessible to CQ5:
1.
Create a new component folder in /apps/<website-name>/
components/<MyComponent> by copying an existing component, such as the Text
component, and renaming it.
2.
In the CRX Explorer, modify the jcr:description and jcr:title to reflect its new name.
3.
Open the new component folder and make the changes you require; also, delete any
extraneous information in the folder.
You can make changes such as:
• adding a new field in the dialog box
• replacing the .jsp file (name it after your new component)
• or completely reworking the entire component if you want
For example, if you take a copy of the standard Text component, you can add an additional
field to the dialog box, then update the .jsp to process the input made there.
Page 6 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Develop Components
4.
In the Content Explorer, navigate to the component and change the allowedParents
property to */parsys, which makes it available to the paragraph system.
Note
Either cq:editConfig node, dialog, or design_dialog node should be present and
properly initialized for the new component to appear.
5.
Activate the new component in your paragraph system either by adding /apps/<websitename>/components/<MyComponent> to the /etc/designs/default/<websitename>/jcr:content/contentpage/parsys/components property in CRX or by
following the instructions in Adding new components to paragraph systems.
6.
In CQ WCM, open a page in your web site and insert a new paragraph of the type you just
created to make sure the component is working properly.
Note
To see timing statistics for page loading, you can use Ctrl-Shift-U - with ?
debugClientLibs=true set in the URL.
3.1.2 Adding a new component to the paragraph system (design mode)
After the component has been developed, you add it to the paragraph system, which enables
authors to select and use the component when editing a page.
1.
Access a page within your authoring environment that uses the paragraph system; for
example <contentPath>/Test.html.
2.
Switch to Design mode by either:
• adding ?cmsmode=design to the end of the URL and accessing again; for example
<contextPath>/ Test.html?cmsmode=design.
• clicking Design in Sidekick
You are now in designmode and can edit the paragraph system:
3.
Click Edit.
A list of components belonging to the paragraph system are shown (all those defined with the
property allowedParents=*/parsys). Your new component is also listed.
The components can be activated (or deactivated) to determine which are offered to the
author when editing a page.
4.
Activate your component, then return to normal edit mode to confirm that it is available for
use.
3.1.3 Extending the Text and Image Component - An Example
This section provides an example on how to extend the widely used text and image standard
component with a configurable image placement feature.
The extension to the text and image component allows editors to use all the existing functionality of
the component plus have an extra option to specify the placement of the image either:
• on the left-hand side of the text (current behavior and the new default)
• as well as on the right-hand side
Page 7 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Develop Components
After extending this component, you can configure the image placement through the component's
dialog box.
The following techniques are described in this exercise:
• Copying existing component node and modifying its metadata
• Modifying the component's dialog, including inheritance of widgets from parent dialog boxes
• Modifying the component's script to implement the new functionality
3.1.3.1 Extending the existing textimage component
To create the new component, we use the standard textimage component as a basis and modify
it. We store the new component in the Geometrixx CQ WCM example application. To extend the
textimage component, go to the CRX Explorer (server name:port number/crx) and log in as
admin and then navigate to the Content Explorer.
1.
Copy the standard textimage component from /libs/foundation/components/
textimage into the Geometrixx component folder, /apps/geometrixx/components,
using textimage as the target node name. (Copy the component by navigating to the
component, right-clicking and selecting Copy and browsing to the target directory.)
2.
To keep this example simple, navigate to the component you copied and delete all the
subnodes of the new textimage node except for the following ones:
• dialog definition: textimage/dialog
• component script: textimage/textimage.jsp
Page 8 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Develop Components
3.
Edit the component metadata:
• Component name
• Set jcr:description to Text Image Component (Extended)
• Set jcr:title to Text Image (Extended)
• Component listing in the paragraph (parsys component) system (leave as is)
• Leave allowedParents defined as */parsys
• Group, where the component is listed in the sidekick (leave as is)
• Leave componentGroup set to General
• Parent component for the new component (the standard textimage component)
• Set sling:resourceSuperType to foundation/components/textimage
After these steps the component node looks like the following:
4.
Modify the component's dialog box to include the new option. The new component inherits
the parts of the dialog box that are the same as in the original. The only addition we make is
to extend the Advanced tab, adding an Image Position dropdown list, with options Left
and Right:
• Leave the textimage/dialog properties unchanged.
• Note how textimage/dialog/items has three subnodes, tab1 to tab3, representing
the three tabs of the textimage dialog box.
• For the first two tabs (tab1 and tab2):
• Change xtype to cqinclude (to inherit from the standard component).
• Add a pathParameter property with values /libs/foundation/components/
textimage/dialog/items/tab1.infinity.json and /libs/foundation/
components/textimage/dialog/items/tab2.infinity.json, respectively.
• Remove all other properties or subnodes.
• For tab3:
• Leave the properties and subnodes without changes
• Add a new field definition to tab3/items, node position of type cq:Widget
• Set the following properties (of type String) for the new tab3/items/position node
Page 9 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Develop Components
• name: ./imagePosition
• xtype: selection
• fieldLabel: Image Position
• type: select
• Add subnode position/options of type cq:WidgetCollection to represent the
two choices for image placement, and under it create two nodes, o1 and o2 of type
nt:unstructured
• For node position/options/o1 set the properties: text to Left and value to left
• For node position/options/o2 set the properties: text to Right and value to
right
Image position is persisted in content as the imagePosition property of the node
representing textimage paragraph.
After these steps, the component dialog box looks like this:
5.
Extend the component script, textimage.jsp, with extra handling of the new parameter.
• Open the /apps/geometrixx/components/textimage/textimage.jsp script for
editing.
• We are going to manipulate the style of the <div class="image"> tag, generated by the
component, to float the image to the right. It is located in the following area of the code:
Image img = new Image(resource, "image");
if (img.hasContent() || WCMMode.fromRequest(request) == WCMMode.EDIT) {
%><div class="image"><%
img.loadStyleData(currentStyle);
We are going to replace the emphasized code fragment %><div class="image"><%
with new code generating a custom style for this tag.
Page 10 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Develop Components
• Copy the following code fragment, and replace the %><div class="image"><% line with
it:
// todo: add new CSS class for the 'right image' instead of using
//
the style attribute
String style="";
if (properties.get("imagePosition", "left").equals("right")) {
style = "style=\"float:right\"";
}
%><div <%= style %> class="image"><%
Note that for simplicity we are hard-coding the style to the HTML tag. The proper way to do
it would be to add a new CSS class to the application styles and just add the class to the
tag in the code in the case of a right-aligned image.
• The code fragment, after the change, should look like this (new code emphasized):
Image img = new Image(resource, "image");
if (img.hasContent() || WCMMode.fromRequest(request) == WCMMode.EDIT) {
// todo: add new CSS class for the 'right image' instead of using
//
the style attribute
String style="";
if (properties.get("imagePosition", "left").equals("right")) {
style = "style=\"float:right\"";
}
%><div <%= style %> class="image"><%
img.loadStyleData(currentStyle);
• Save the script to the repository.
6.
The component is ready to test.
3.1.3.2 Checking the new component
After the component has been developed, you can add it to the paragraph system, which enables
authors to select and use the component when editing a page. These steps allow you to test the
component.
1.
Open a page in Geometrixx; for example, English/Company
2.
Switch to design mode by clicking Design in Sidekick
3.
Edit the paragraph system design by clicking Edit on the paragraph system in the middle of
the page. A list of components, which can be placed in the paragraph system are shown, and
it should include your newly developed component, Text Image (Extended). Activate it
for the paragraph system by selecting it and clicking OK.
4.
Switch back to the editing mode.
5.
Add the Text Image (Extended) paragraph to the paragraph system, initialize text and image
with sample content. Save and you should see the default rendering of Text and Image
component:
Page 11 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Develop Components
6.
Open the dialog of the text and image paragraph, and change the Image Position on the
Advanced tab to Right, and click OK to save the changes.
7.
You see the paragraph rendered with the image on the right:
Page 12 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Develop Components
8.
The component is now ready to use.
The component stores its content in a paragraph on the Company page. The following screenshot
shows how our new configuration parameter is persisted in the repository, with the node
representing the paragraph we have just created.
The textimage/imagePosition parameter represents the position of the image for this
paragraph on /content/geometrixx/en/company page.
Page 13 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
4 How to Set Up a Cluster
4.1 How to Set Up a Cluster in Communiqué
Clustering uses two or more live servers, so if one server breaks down, the other can take over.
Therefore, even if a node fails, the other nodes are active and accessible for your applications and
there is no system interruption. This allows you to recover and re-start failed nodes easily. Also,
new nodes can be added to an existing cluster, allowing for simple extensibility.
Clustering is beneficial in the following scenarios.
• A server breaks down – The cluster agent relays requests to the servers that are still running.
Service continues without interruption.
• A repository breaks down – If the repository breaks down, the server becomes unavailable, and
the cluster agent relays the requests to the other servers. Service continues without interruption.
• Increased performance – clustering enables your system to perform better even when nodes fail.
Note
As long as both servers are active, you can use their combined computational power.
This means that this solution improves performance during normal use. On the other
hand, if one server breaks down, you lose its performance, so your overall application
performance may suffer.
Following section describes how to set up a cluster in Communiqué with two cluster nodes on two
separate networked machines.
The master node is called node 1, the slave node is called node 2.
On the node 1 (master):
1. In the file system, create a folder /node1.
2. Install Communiqué under /node1. For a complete description of the installation, please refer to
the section called “Installing an Author instance”.
3. In the file system, share the folder node1/crx-quickstart/repository/shared so that it
can be accessed from the node 2.
On the node 2 (slave):
1. In the file system, create a folder /node2.
2. Install Communiqué under /node2. For a complete description of the installation, please refer to
the section called “Installing an Author instance”.
3. In the file system, map the folder on node 1 node1/crx-quickstart/repository/shared
to a drive, Z: in our case.
4. In your browser, open the CRX Main Console
5. Browse to http://localhost:4502/crx to open the CRX Main Console.
6. Log in as administrator.
7. Click Repository Configuration.
8. Under Tools, click Cluster.
Page 14 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up a Cluster
9. Under Join Cluster, as Shared path, enter Z:\ and click Join.
Note
In order to add more nodes to the cluster, repeat the steps on the slave node as many
times as needed.
Page 15 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
5 How to Monitor Performance
5.1 Introduction
CQ5 encompasses several applications, and interacts with several more.
Performance (or the lack of it) is one of the first things that your users notice, so as with any
application with a user interface, performance is of key importance. To optimize the performance of
your CQ5 WCM installation various attributes of the behavior should be monitored.
5.1.1 Purpose of this How To
To give a short introduction on what to monitor, and how, when optimizing the performance of your
CQ5 implementation.
Note
This document deals primarily with the mechanics of monitoring performance. Issues
such as setting the target metrics of the performance you want to achieve are covered
elsewhere. See the CQ5 WCM Project Manager Guide for more information.
5.1.2 Target Audience
• Power Users
• System Administrators
• Project Managers
5.2 Performance - some theory
The problems that cause performance issues are often difficult to track down, even when their
effects are easy to see.
A basic starting point is a good knowledge of your system when it is operating as normal. If you
don't know how your environment "looks" and "behaves" when it is performing properly, it can
be difficult to locate the problem when performance deteriorates. This means that you should
spend some time investigating your system when it is running smoothly and ensure that collecting
performance information is an ongoing task. This will provide you with a basis for comparison
should the performance suffer.
The following diagram illustrates the path that a request for CQ5 content can take - and therefore
the number of different elements which can impact the performance.
Page 16 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Monitor Performance
Figure 5.1. CQ5 request - the web-chain
Performance is also a balance between Volume and Capacity:
Volume
the amount of output that is processed and delivered by the system.
Capacity
the system’s ability to deliver the volume.
This can be illustrated in various locations throughout the web-chain.
Page 17 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Monitor Performance
Figure 5.2. Capacity vs. Volume
There are several functional areas which are often responsible for impacting the performance:
• Caching
• Application (your project) code
• Search functionality
5.3 Performance - basic rules
Certain rules should be kept in mind when optimizing performance:
1. Performance tuning must be part of every project.
2. Do not optimize early in the development cycle.
3. Performance is only as good as the weakest link.
4. Always think about capacity vs. volume.
5. Optimize important things first.
6. Never optimize without realistic goals.
Note
Bear in mind that the mechanism you use to measure performance will often affect
exactly what you are trying to measure. You should always try to account for these
discrepancies, and eliminate as much of their effect as possible; in particular browser
plug-ins should be de-activated wherever possible.
5.4 Recognizing some common performance problems
The following lists common performance issues which occur, together with proposals on how to
spot and counteract them.
Page 18 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Monitor Performance
Table 5.1. Recognizing common performance problems
Area
Symptom(s)
To increase capacity...
To reduce volume...
Client
High client CPU usage.
Install a client CPU with
higher performance.
Simplify (HTML) layout.
Low server CPU usage.
Upgrade to a faster browser. Improve client-side cache.
Some clients fast, some
slow.
Server
Network
CPU usage low on both
servers and clients.
Remove any network
bottlenecks.
Improve/optimize the
configuration of the client
cache.
Browsing locally on the
server is (comparatively)
fast.
Increase network
bandwidth.
Reduce the "weight" of
your web pages (e.g. less
images, optimized HTML).
Cluster your web-servers.
Reduce the hits per page
(visit).
Web-server CPU usage on the webserver is high.
Use a hardware loadbalancer.
Application Server CPU usage is high.
Cluster your CQ5 instances. Search for, and eliminate,
CPU and memory hogs (use
code review, timing output,
etc).
High memory consumption.
Improve caching on all
levels.
Low response times.
Optimize templates and
components (e.g. structure,
logic).
Repository
Cache
5.5 Monitoring, and optimizing, the performance
Performance issues may stem from a number of causes that have nothing to do with your website,
including temporary slowdowns in connection speed, CPU load, and many more.
It may also impact either all your visitors, or only a subset of them.
All this information needs to be obtained, sorted and analyzed before you can optimize the
performance.
If you experience a performance issue:
• try to replicate it: with one (or preferably more) standard web-browsers, on a different client that
you know has good general performance and/or on the server itself (if possible)
• check whether anything (related to the system) has changed within an appropriate time-space,
and if any of these changes could have impacted the performance
• collect as much information as possible to compare with your knowledge of the system under
normal circumstances
5.5.1 Tools and mechanisms
The following gives a short overview of some of the tools available for monitoring performance.
Page 19 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Monitor Performance
Note
Some of these will be dependent on your operating system.
Table 5.2. Tools and mechanisms for monitoring performance
Tool
Used to analyze...
Usage / More information...
request.log
Response times and
concurrency.
Interpreting the request.log.
truss/strace
Page Loads
Unix command. Include the misc.truss log level to
INFO.
CQ5 status
monitor
Monitor CQ5 requests;
including request-type,
long-running requests,
pending requests.
Thread dumps
Observe JVM threads. Dependent on the operating system, e.g. kill -QUIT
Identify contentions,
<pid> on Unix/Linux whereas Ctrl-Break on Windows.
locks and long-runners.
System calls
Identify timing issues.
Apache Bench Identify memory leaks,
selectively analyze
response time.
Calls to System.currentTimeMillis() or
com.day.util.Timing are used to generate
timestamps from your code, or via HTML-comments.
Note: These should be implemented so that they can
be activated / deactivated as required; when a system is
running smoothly the overhead of collecting statistics will
not be needed.
For full details: http://httpd.apache.org/docs/2.0/programs/
ab.html; basic usage is: ab -k -n <requests> -c
<concurrency> <url>
Search
Analysis
Execute search queries Analyzing Search.
offline, identify response
time of query, test and
confirm result set.
JMeter
Load and functional
tests.
http://jakarta.apache.org/jmeter/
JProfiler
In-depth CPU and
memory profiling.
http://www.ej-technologies.com/
truss/strace,
lsof
In depth kernel call and Unix/Linux commands.
process analysis (Unix).
5.5.2 Interpreting the request.log
This file registers basic information about every request made to CQ5. From this valuable
conclusions can be extracted.
5.5.2.1 Monitoring traffic on your website
The request log registers each request made, together with the response made:
09:43:41 [66] -> GET /author/y.html HTTP/1.1
09:43:41 [66] <- 200 text/html 797ms
By totaling all the GET entries within a specific periods (e.g. over various 24 hour periods) you can
make statements about the average traffic on your website.
5.5.2.2 Monitoring response times with the CQ5 request.log
Page 20 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Monitor Performance
A good starting point for performance analysis is the request log.
You can find the request log at data\author\logs and data\publish\logs for the author
and publish instance respectively.
The log looks as follows (the lines are shortened for simplicity):
09:43:41
09:43:41
09:43:47
09:43:48
09:43:49
09:43:49
[66]
[66]
[67]
[67]
[68]
[68]
->
<->
<->
<-
GET
200
GET
200
GET
404
/author/y.html HTTP/1.1
text/html 797ms
/author/z.gif HTTP/1.1
image/gif 141ms
/author/x.html HTTP/1.1
text/html 0ms
This log has one line per request or response:
• The date at which each request or response was made.
• The number of the request, in square brackets. This number matches for the request and the
response.
• An arrow indicating whether this is a request (arrow pointing to the right) or a response (arrow to
the left).
• For requests, the line contains:
• the method (typically, GET, HEAD or POST)
• the requested page
• the protocol
• For responses, the line contains:
• the status code (200 means “success”, 404 means “page not found”)
• the MIME type
• the response time
Using small scripts, you can extract the required information from the log file and assemble the
statistics you want. From these, you can see which pages or types of pages are slow, and if the
overall performance is satisfactory.
5.5.2.3 Monitoring search response times with the CQ5 request.log
Search requests are also registered in the log file:
22.05.2008 12:27:40 [338] -> GET /author/playground/en/tools/search.html?
query=dilbert&size=5&dispenc=utf-8 HTTP/1.1
22.05.2008 12:27:42 [338] <- 200 text/html 1562ms
So, as above, you can use scripts to extract the relevant information and build up statistics.
5.5.2.4 Monitoring the numbers and impacts of concurrent users
Again the request.log can be used to monitor concurrency and the system's reaction to it.
Page 21 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Monitor Performance
Tests must be made to determine how many concurrent users the system can handle before a
negative impact is seen. Again scripts can be used to extract results from the log file:
• monitor how many requests are made within a specific time span e.g. one minute
• test the effects of a specific number of users all making the same requests at (as close as
possible) the same time; e.g. 30 users clicking Save at the same time
22.05.2008 12:27:22 [333] -> GET /author/libs/Personalize/content/statics.close.gif
HTTP/1.1
22.05.2008 12:27:22 [334] -> GET /author/libs/Personalize/content/statics.detach.gif
HTTP/1.1
22.05.2008 12:27:22 [335] -> GET /author/libs/CFC/content/imgs/
logo.rZMNURccynWcTpCxyuBNiTCoiBMmw000.default.gif HTTP/1.1
22.05.2008 12:27:22 [335] <- 304 text/html 0ms
22.05.2008 12:27:22 [334] <- 200 image/gif 31ms
22.05.2008 12:27:22 [333] <- 200 image/gif 31ms
22.05.2008 12:27:22 [336] -> GET /author/libs/CFC/content/imgs/
logo.rZMNURccynWcTZRXunQbbQtvuuCMbRRBuWXz0000.default.gif HTTP/1.1
22.05.2008 12:27:22 [337] -> GET /author/titlebar_bg.gif HTTP/1.1
22.05.2008 12:27:22 [336] <- 304 text/html 0ms
22.05.2008 12:27:22 [337] <- 304 text/html 0ms
5.5.2.5 Timing Statistics for Page Loading
To see timing statistics for page loading you can use Ctrl-Shift-U - with ?
debugClientLibs=true set in the URL.
5.5.3 Caching
The following diagram shows the different cache locations that can be used for the various content
types.
Figure 5.3. What can be cached where?
The following can act as a rough guide for target values:
Page 22 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Monitor Performance
Figure 5.4. Cache vs. Uncached - maximum hits / second
Although there are many algorithms to ensure that data is retrieved from the source system when
appropriate, circumstances can arise where the data residing in a cache is out of date. Retrieving
every page individually is the only guaranteed method of ensuring your content is up-to-date, but it
is very costly in terms of response, and can indeed cause knock-on effects.
This is particularly relevant when using personalized pages, where at least some content of a
page is dependent on the user, and the account they used to login.
Figure 5.5. Cache speed vs. Data Integrity
Page 23 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Monitor Performance
5.5.3.1 Optimizing your content for cache performance
Make sure you use realistic cache settings for the browser cache. If you have disabled the browser
cache for development, this may increase traffic and decrease responsiveness.
5.5.4 Analyzing Search
First steps to analyzing the search function can be made with Monitoring search response times
with the CQ5 request.log.
However, once you have determined the response time, you may need to analyze why the request
is taking the time it does, and what can be done to improve the response.
Page 24 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
6 How to Create and Use a Workflow
6.1 Creating a Workflow
First you must create your workflow. You can then apply an instance of this (version dependent)
when managing your website.
Important
Actions on workflows can only be undertaken if:
• you are working with the admin account
• the account has been assigned to the default group workflow-users, which holds all
the privileges necessary for your users to perform workflow actions.
Note
For simplicity, the following examples have all been made using the admin account.
6.1.1 Creating a new Workflow Model
The actual creation is a small step - a skeleton workflow (with 3 default steps) will be created.
1.
Open the Workflow console.
2.
From the Models tab, select New from the top navigation bar. The New Workflow dialog will
open.
3.
Specify the Title for your workflow.
4.
Click OK to save and close the dialog. You will be returned to the Models tab, where you see
your new workflow in the list.
6.1.2 Editing the Workflow
As mentioned above, a skeleton workflow is created with a minimum of steps. For the workflow to
become meaningful, you must edit it immediately.
1.
Open the Workflow console.
2.
From the Models tab, select your workflow.
3.
Either click Edit or double-click the name of the workflow. A new tab (named after the
workflow) will open for editing and configuring a workflow. This shows 3 panes:
• Toolbox
Page 25 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
Lists the Step and Split types. Click to display the appropriate list, then use drag the
element you want into the appropriate position to build your workflow.
Note
A complete explanation of all types of workflow steps and splits, together with
their related properties, can be found in the next section - the section called “The
types of Workflow Steps available”.
• Workflow Model
Contains the graphical representation of your workflow. Here you can position the steps
and splits, edit the workflow name or description and save changes.
The Save button is also located here, as is the Model Version. The Model Version is
incremented every time the workflow model is updated. This is reflected in the monitoring
displays. As multiple versions of a workflow can be in use at any one time, this helps you
track the version being used in each instance.
• Properties
Allows you to edit properties of the individual steps and splits.
Note
A complete explanation of all types of workflow steps and splits, together with
their related properties, can be found in the next section - the section called “The
types of Workflow Steps available”.
Three steps have already been created:
Start
A mandatory step to start the workflow. This cannot be edited, nor deleted.
Step 1
A Participant step which is an example. This must be edited, or replaced if required.
Further steps can be added.
End
A mandatory step for every workflow. The End step is used to cleanly terminate the
workflow, or to pass control back to the parent workflow if used as a child workflow.
Page 26 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
You can either define a full workflow, or a sub-section of a workflow. Sub-workflows can then
be referenced by other workflows to form part of a complete workflow. This simplifies the
construction of complex workflows, and also allows you to reuse sub-workflows which occur
repeatedly.
4.
Enter a Model Description for the workflow (you can also edit the Model Title) from
the center pane. Click on the field to enter edit mode.
5.
You can now design your workflow by dragging steps onto the Workflow Model, then
configuring the properties.
6.
When finished, Save your model, then close the tab.
6.1.2.1 Example
To illustrate some of the possibilities for creating a workflow, the following example emulates a
variation of the Publish Example workflow.
1.
Edit Step 1 using
on the step itself.
a.
Enter Validate Content for the Title and Description.
b.
Set the User/Group to admin.
c.
Set the Timeout to Off and Timeout Handler empty.
2.
Click on Splits to display the list of split types.
3.
Drag an Or Split onto the workflow and position it between Validate Content and End.
An Or Split will be added to your workflow.
4.
Edit the left-hand branch:
a.
Click the
icon on the actual branch.
b.
Set Default Route to true.
c.
Click the
icon on New Step in the left-hand branch. This will be a Participant step.
5.
d.
Enter Cancel Publish for the Title and Description.
e.
Set the User/Group to admin.
Edit the right-hand branch:
a.
Click the
icon on the actual branch.
Page 27 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
b.
Set Default Route to false.
c.
Leave the Rule empty. This is for demonstration purposes.
d.
Click the
icon on New Step in the right-hand branch. Change this from a Participant to a
Process step; the properties available will be updated.
e.
Enter Publish Page for the Title and Description.
f.
Set the Handler Advance to false.
g.
Select com.day.cq.workflow.example.publish.PublishProcess as the
Implementation script. This implementation will publish the selected page to the publisher
instances.
6.
Now you have specified all steps in your workflow, click Save.
7.
Finally close the tab and return to the main console.
6.2 Using the Workflow
After you have defined your workflow you will want it to be used when managing your website. The
following sections detail the different tasks when using workflows.
6.2.1 Starting the Workflow for an individual page
There are two methods of starting a workflow; from the Workflow Console or the siteadmin:
In either case you need to link a workflow to its payload. The payload (including pages, nodes,
resources) will then be subject to this instance of the workflow.
Page 28 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
Important
The current version of the workflow model is assigned; if the main copy of the workflow is
updated later then the changes will have no impact on the instance assigned.
Procedure 6.1. Starting a workflow from the workflow console
1.
Open the Workflow console.
2.
From the Models tab select the required workflow.
3.
Click Start from the top navigation.
4.
The Start Workflow dialog opens allowing you to enter the payload and a comment.
Specify the payload (includes pages, nodes, resources, etc) to which the workflow is to be
applied. You can use the drop down selector to browse the repository when selecting:
5.
Click OK to save your selection and start the workflow. Now the workflow is running.
Procedure 6.2. Starting a workflow from the sidekick
1.
Open the siteadmin.
2.
Open the required page.
3.
Select the Workflow tab from the sidekick.
4.
Select Start Workflow... to open a new dialog allowing you to select the workflow and a
enter a comment.
Page 29 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
5.
Click Start to save your selection and start the workflow. Now the workflow is running.
Once a page has been linked to a workflow it will be indicated in the siteadmin:
6.2.2 Automatically Assigning a Workflow
To simplify the action of starting a workflow it is possible to Auto Assign workflows. With this, you
can automatically assign one or more workflows to a content tree, dependent on the page template
being used. As soon as a page is created within this tree and with the specified template, the
workflow is applied to that page.
1.
Open the siteadmin.
2.
Select the page at the root of the content tree. Any pages created underneath this page will
be subject the specified workflow.
3.
From the Workflow menu select Auto Assign. The Auto Assign Workflow dialog will
open.
4.
Click Add to open the Auto Assign Rule dialog:
Page 30 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
This allows you to specify the:
Template
Any page created using this template will be subject to the rule.
Workflow
The workflow to be applied to any page created - with the specified template and in the
given path.
Path
Path to which the rule is applied.
5.
Click OK to save the rule.
6.
The rule will now be listed in the Auto Assign Workflow window.
Note
You can create several rules, so you must take care that the rules do not conflict.
Page 31 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
7.
Click Close to complete the definition. From now on, as soon as a page is created within the
specified trees with the specified templates the appropriate workflows are applied. This will be
indicated in the In Workflow column,
6.2.3 Taking actions on a Participant Step
Any participant steps that you have created will be assigned to the specific user or group, who will
need to take action:
• When the task is completed they then acknowledge this fact by completing the workflow step
(see Completing a Participant step).
• If the specific user(s) are unable to take action they can delegate responsibility to another user or
group (see Delegating a Participant step).
• If necessary they can step back to repeat a section of the workflow (see Performing Step Back
on a Participant step).
6.2.3.1 Selecting a Participant Step to take action
Before you can take any action on a Participant step, you need to select it:
1.
Open the Workflow console.
2.
Select the Inbox tab to see when an action is assigned to you. This occurs when a workflow
reaches a Participant step with your account, or group, specified:
Page 32 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
3.
Select the entry.
6.2.3.2 Completing a Participant step
After you have taken the action indicated you can complete the workflow step, thus allowing the
workflow to continue.
1.
Click the Complete button in the top navigation bar.
2.
In the resulting dialog, select the Next Step; that is, the step to execute next. A drop down
list will show all appropriate destinations. A Comment can also be entered.
Note
The number of steps listed depends on the design of the workflow.
3.
Click OK to confirm the action.
6.2.3.3 Delegating a Participant Step
If a step has been assigned to you, but for any reason you are unable to take action, you can
delegate the step to another user or group.
1.
Click the Delegate button in the top navigation bar.
2.
In the resulting dialog, select the User you want to pass the action to.
A drop down list will show all appropriate users.
If the step has been defined with one user, then only this user will be available - the step
cannot be delegated to anyone else.
If a group has been defined, then the list will show the group itself and all individual users
within the group. You can delegate to either the entire group, or an individual user within that
group.
A Comment can also be entered.
Page 33 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
3.
Click OK to confirm the action.
6.2.3.4 Performing Step Back on a Participant step
If you discover that a step, or series of steps, needs to be repeated you can step back. This allows
you to select a step which occurred earlier in the workflow for reprocessing. The workflow will
return to the step you specify, then proceed from there.
1.
Click the Step Back button in the top navigation bar.
2.
In the resulting dialog, select the Previous Step; that is, the step to execute next - even
though it is a step that occurs earlier in the workflow. A drop down list will show all appropriate
destinations.
Note
The number of previous steps available in the list depends on the design of the
workflow.
3.
Click OK to confirm the action.
6.2.4 Suspending, Resuming and Terminating a Workflow instance
Aside from workflow instances that require your immediate action and show up in your Workflow
Inbox, you can perform certain other actions on running workflow instances.
Page 34 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
1.
Open the Workflow console.
2.
Select the Instances tab. You will see a list of active (neither finished, nor terminated)
workflow instances.
3.
Select an entry.
4.
To suspend the workflow, click the Suspend button in the navigation bar. The State will
changed to Suspended. This can be helpful in exceptional cases when you do not want the
workflow to proceed; for instance for maintenance.
5.
While a workflow is suspended, you can then click Resume. This will restart the workflow from
where it was suspended, with the same configuration. Again the State will be updated.
6.
To finally terminate the workflow, click Terminate. This will immediately end the workflow
execution - the state will change to ABORTED. A terminated workflow instance cannot be
restarted.
The Instances tab is not only useful for taking action on running workflows, you can also use it to
monitor workflow instances, without necessarily modifying them.
6.2.5 Monitoring the Status of Workflow Instances
To monitor the status of workflow instances, you can use the Instances or Archive tabs.
Instances tab
Shows all running instances.
Archive tab
Shows terminated workflow instances.
6.2.5.1 Monitoring Workflows in progress
From the Instances tab you can see the status of a Workflow in progress. A list of the active
Models is shown; in this case RUNNING:
With the Instances tab you can take various actions (see Suspending, Resuming and
Terminating a Workflow instance) and also Open History to show the actions executed to date
on the workflow instance:
Page 35 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Create and Use a Workflow
6.2.5.2 Archived Workflows
After a Workflow instance has finished, for whatever reason (terminated, as below, or after
successful completion), it can (only) be seen in the Archive tab:
As the workflow has already completed, no further action can be taken on these instances.
However, if you need further details of a completed workflow you can still use Open History.
Page 36 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
7 Upgrading to CQ5
7.1 How to Upgrade Your Communiqué Instance (3 or 4) to CQ5
The upgrade tool allows you to launch a standardized upgrade process. It is delivered with a
configuration to be used “out of the box,” though several settings can be updated when necessary.
You:
• provide the URL of the Communiqué instance to be upgraded, together with the superuser
access credentials
• can configure a list of page handles to be included in the upgrade
• can set debug parameters if required.
Note
The following procedure uses a standard Communiqué 4 installation, complete with
Playground and DesignGround, to illustrate the upgrade process.
1.
Navigate to the Upgrade window, by one of the following methods:
a.
Select the Miscellaneous tab in CQ WCM, then double-click on the Migrate
Page to open.
b.
Navigate directly to http://<cq-context-path>/etc/migration for example,
http://localhost:4502/etc/migration (if not already logged in you will be
required to).
In either case the following form will be shown:
2.
Update any of the default settings if required.
Page 37 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Upgrading to CQ5
3.
Click Migrate to start the process. A status message will shown while this is running:
4.
When complete, the upgraded items will be listed (the following screenshot is an extract):
5.
You can now access the upgraded items in your CQ5 instance:
Note
You must test the operation of the upgraded website; highly customized items may
need to be upgraded separately.
Page 38 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
8 Installing CQ5
8.1 How to Install CQ WCM Author and Publish Instances using
Quickstart
This section describes how to install CQ WCM. Generally, when you set up CQ WCM, you need to
set up an Author and a Publish instance, which are described in Installing an Author instance and
Installing a Publish instance. If, for testing or other purposes, you need to install CQ WCM out of
the box, you can use the generic procedure.
8.1.1 Installing a CQ WCM instance - Generic procedure
This procedure is a generic, quickstart procedure for installing CQ WCM. You do not need to
perform this procedure before installing an author or publish instance. To install an author or
publish instance, see Installing an Author instance and Installing the Publish instance.
To install a CQ WCM instance:
1.
Copy the CQ WCM cq-wcm-quickstart-<version>.jar file (for example, cq-wcmquickstart-5.1.0.20081114.jar) to the desired directory on the host file system.
2.
Copy a valid license.properties file into the same directory as the cq-wcmquickstart-<version>.jar file.
Note
If when starting the application, you do not provide the license.properties file,
CQ WCM redirects you to the Welcome screen where you enter a valid license key.
You can also request a valid license key from Day at this time.
3.
Start CQ WCM Quickstart by doing one of the following:
• If using a GUI file-system explorer, double-click the cq-wcm-quickstart<version>.jar file. This installs and automatically starts the server.
Note
The repository data is stored in the subdirectory crx-quickstart/
repository.
• If using the command line, type the following:
java -jar cq-wcm-quickstart-<version>.jar
• Use a custom script located in the crx quickstart folder, such as server.bat to
start CQ. The Start and Stop scripts are for UNIX, Linux, and Macintosh. The server.bat
script is for Windows.
Note
You cannot use a custom script when you install the quickstart.jar file
unless you expand the file first. Use the -unpack option on the command line
to unpack the contents before running the script as in java -jar cq-wcmquickstart-<version>.jar -unpack.
4.
When the installation is complete, you are automatically redirected to http://
localhost:4502/bin/login.html.
Page 39 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
Note
CQ WCM quickstart selects the first available port from the following list:
4502,8080,8081,8082,8083,8084,8085,8888,9362,<random>. You can
also set the port number. See installing an author instance for an example on how to
set a port number.
8.1.2 Installing an Author instance
This procedure describes how to set up a default Author instance on port 4502 of the desired host.
To install an author instance:
1.
On the host file system, create a directory and name it author.
2.
Copy the CQ5 cq-wcm-quickstart-<version>.jar file into author/ and rename the
file cq5-author-4502.jar. A different port can be set in the filename.
3.
Copy a valid license.properties file into the same directory as the cq-wcmquickstart-<version>.jar file.
Note
If when starting the application, you do not provide the license.properties file,
CQ WCM redirects you to the Welcome screen where you enter a valid license key.
You can also request a valid license key from Day at this time.
4.
Start CQ WCM Quickstart:
• If using a GUI file-system explorer, double-click the cq5-author-4502.jar file.
• If using the command line, type:
java -jar cq5-author-4502.jar
• Use a custom script located in the crx quickstartfolder, such as server.bat to start
CQ. The Start and Stop scripts are for UNIX, Linux, and Macintosh. The server.bat
script is for Windows.
Important
You cannot use a custom script when you install the quickstart.jar file
unless you expand the file first. Use the -unpack option on the command line
to unpack the contents before running the script as in java -jar cq-wcmquickstart-<version>.jar -unpack.
5.
When the installation is completed, you are automatically redirected to http://
localhost:4502/bin/login.html.
Note
With the default settings, the syndication agent points toward the publish instance at
http://localhost:4503/.
8.1.3 Installing a Publish instance
To set up a publish instance on port 4503 of the desired host, you perform the same steps as
in installing an author instance except that you create a directory named publish (instead of
author) and you rename the quickstart.jar file as cq5-publish-4503.jar. You can select any
port number.
Page 40 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
To install a publish instance:
1.
On the host file system, create a directory and name it publish.
2.
Copy the CQ WCM cq-wcm-quickstart-<version>.jar file into publish/ and
rename it cq5-publish-4503.jar. A different port can be set in the filename.
3.
Copy a valid license.properties file into the same directory as the cq-wcmquickstart-<version>.jar file.
Note
If when starting the application, you do not provide the license.properties file,
CQ WCM redirects you to the Welcome screen where you enter a valid license key.
You can also request a valid license key from Day at this time.
4.
Start CQ WCM Quickstart:
• If using a GUI file-system explorer, double-click the cq5-publish-4503.jar file.
• If using the command line, type:
java -jar cq5-publish-4503.jar
• Use a custom script located in the crx quickstartfolder, such as server.bat to start
CQ. The Start and Stop scripts are for UNIX, Linux, and Macintosh. The server.bat
script is for Windows.
Important
You cannot use a custom script when you install the quickstart.jar file unless
you expand the file first. Use the -unpack option on the command line to unpack
the contents before running the script as in java -jar cq-wcm-quickstart<version>.jar -unpack.
5.
When the installation is completed, you can browse your site (for example, http://
localhost:4503/content/geometrixx/en/company.html)
8.2 How to install CQ5 with an Application Server
The following sections detail how to install CQ5 in conjunction with various application servers:
• WebSphere v6.1
• WebLogic v10.1
• Tomcat v6
• JBoss v4
A generic overview is also given for general usage and information:
• Generic Procedures
8.2.1 WebSphere v6.1
After installing WebSphere v6.1 you:
8.2.1.1 Install CQ5
1.
Unpack the installation files of the CQ5 Quickstart into a directory (without starting the server);
the installation directory will be referred to as <cq-installation-dir>:
Page 41 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
•
Start the CQ5 Quickstart jar with the option -unpack; for example:
java -jar cq-wcm-quickstart-5.1.0.jar -unpack
This will create a folder <cq-installation-dir>crx-quickstart containing the
files and folders used for installation, without actually starting the installation.
Important
This must be done from the command line. If you open the jar file directly you will
activate the Quickstart installation and start the server.
2.
Copy the following jar files to the application server folder holding shared libraries:
a.
CRX\server\lib\container\jcr-1.0.jar
b.
CRX\server\lib\container\crx-shared.jar
3.
Restart WebSphere.
4.
Deploy the following web applications; they can be found in <cq-installationdir>\crx-quickstart\server\webapps:
a.
CRX webapp; crx-explorer_crx.war.
For example, deploy with the context path /crx.
b.
Launchpad webapp; crx-launchpad.war.
For example, deploy with the context path /launchpad.
5.
Start the two applications.
6.
Register your CRX license:
a.
Access your CRX installation:
http://<server>:<port>/<context-path>/index.jsp
for example: http://<server>:<port>/crx/index.jsp
b.
Click the red warning message - “Click here...” (the message is a link).
c.
Enter your license key.
8.2.1.2 Configure the default JDK
WebSphere v6.1 uses JDK 1.5. By default the SAMLv2 JSP JDK source level uses JDK 1.3. As the
SAMLv2 sample configuration uses the JDK 1.5 syntax, running it with the default source level will
not work. The following steps should be used to configure the source level as 1.5:
1.
Within the deployed crx-explorer_crx.war, edit ibm-web-ext.xmi and add the
following configuration parameter to specify the JSP engine:
<jspAttributes xmi:id="JSPAttribute_1225281520121"
name="jdkSourceLevel" value="15"/>
Note
The integer (n) referenced in JSPAttribute_<n> must be unique within the file.
2.
Repeat for crx-launchpad.war.
Page 42 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
Note
The default configuration directory for the web module is:
<WAS_ROOT>\profiles\profilename\config\cells\cellname
\applications\enterpriseappname\ deployments\deployedname
\webmodulename\WEB-INF\
If you have already checked the option Use Binary Configuration the files are
extracted to the following directory, where they can be edited:
<WAS_ROOT>\profiles\profilename\installedApps\nodename
\enterpriseappname\webmodulename\
Where <WAS_ROOT> is the root directory of the web application server installation.
3.
Restart Websphere.
8.2.1.3 Install your Content Packages
1.
Access the CRX main console.
2.
Log in to the crx.system workspace as admin.
3.
Navigate to the Package Manager in CRX.
4.
Upload and install the following CQ5 package from <cq-installation-dir>\crxquickstart\repository\install\system:
•
WCM Security Content Package; cq-security-content-<cq-version>.jar.
5.
Switch to the crx.default workspace, again as admin
6.
Upload and install the following CQ5 packages from <cq-installation-dir>\crxquickstart\repository\install in the following order:
a.
Sling Content Package; 0001-cq-wcm-sling-content-<cq-version>.jar.
b.
WCM Content Package; 0002-cq-wcm-content-<cq-version>.jar.
8.2.1.4 Enable Replication for Author instances of CQ5
For an author instance of CQ5 you must configure it to start in “author run mode” so that you can
perform replications.
1.
Open the file: <cq-installation-dir>\crx-quickstart\launchpad
\sling.properties for edit.
2.
Add the following two properties to the file:
sling.jcrinstall.folder.name.regexp = .*/(install|config)(.author)?$
sling.run.modes = author
3.
Restart the crx-launchpad web application.
8.2.2 WebLogic v10.3
After installing WebLogic v10.3 and creating your domain you:
8.2.2.1 Configure the Server Locale
When you deploy CQ5 with WebLogic 10.3 you must have the server locale set to en_US to avoid
errors such as:
Page 43 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
java.lang.IllegalArgumentException: Bad date header: 'Wed, 12 Nov 2008
16:34:28 GMT'
These can occur when, for example, requesting a resource such as /libs/widgets/0.gif.
To configure the server locale on Microsoft Windows:
1.
Open the Control Panel.
2.
Open Regional and Languages Options.
3.
In the Regional Options tab, for Standards and formats select English(United
States).
To configure the server locale on Linux or Unix:
•
set the environment variable LANG to en_US.
8.2.2.2 Enable Basic Authentication Headers
To enable out-of-the-box authentication of users in CQ5, authentication by the application server
must be switched off:
1.
Open <WebLogic-installation-dir>/user_projects/domains/<your-domain>/
config/config.xml.
2.
Locate the element <security-configuration>.
3.
Add the following child element to it:
<enforce-valid-basic-auth-credentials>
false
</enforce-valid-basic-auth-credentials>
4.
If you had already started WebLogic then you will need to restart it.
8.2.2.3 Install CQ5
1.
Unpack the installation files of the CQ5 Quickstart into a directory (without starting the server);
the installation directory will be referred to as <cq-installation-dir>:
•
Start the CQ5 Quickstart jar with the option -unpack; for example:
java -jar cq-wcm-quickstart-5.1.0.jar -unpack
This will create a folder <cq-installation-dir>crx-quickstart containing the
files and folders used for installation, without actually starting the installation.
Important
This must be done from the command line. If you open the jar file directly you will
activate the Quickstart installation and start the server.
2.
Copy the following jar files to the application server folder holding shared libraries:
a.
CRX\server\lib\container\jcr-1.0.jar
b.
CRX\server\lib\container\crx-shared.jar
3.
Restart WebLogic.
4.
Deploy the following web applications; they can be found in <cq-installationdir>\crx-quickstart\server\webapps:
Page 44 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
a.
CRX webapp; crx-explorer_crx.war.
For example, deploy with the context path /crx.
b.
Launchpad webapp; crx-launchpad.war.
For example, deploy with the context path /launchpad.
5.
Start the two applications.
6.
Register your CRX license:
a.
Access your CRX installation:
http://<server>:<port>/<context-path>/index.jsp
for example: http://<server>:<port>/crx/index.jsp
b.
Click the red warning message - “Click here...” (the message is a link).
c.
Enter your license key.
8.2.2.4 Install your Content Packages
1.
Access the CRX main console.
2.
Log in to the crx.system workspace as admin.
3.
Navigate to the Package Manager in CRX.
4.
Upload and install the following CQ5 package from <cq-installation-dir>\crxquickstart\repository\install\system:
•
WCM Security Content Package; cq-security-content-<cq-version>.jar.
5.
Switch to the crx.default workspace, again as admin
6.
Upload and install the following CQ5 packages from <cq-installation-dir>\crxquickstart\repository\install in the following order:
a.
Sling Content Package; 0001-cq-wcm-sling-content-<cq-version>.jar.
b.
WCM Content Package; 0002-cq-wcm-content-<cq-version>.jar.
8.2.2.5 Enable Replication for Author instances of CQ5
For an author instance of CQ5 you must configure it to start in “author run mode” so that you can
perform replications.
1.
Open the file: <cq-installation-dir>\crx-quickstart\launchpad
\sling.properties for edit.
2.
Add the following two properties to the file:
sling.jcrinstall.folder.name.regexp = .*/(install|config)(.author)?$
sling.run.modes = author
3.
Restart the crx-launchpad web application.
8.2.3 Tomcat v6
After installing Tomcat v6 you:
Page 45 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
8.2.3.1 Configure Tomcat access accounts
Tomcat enables neither admin nor manager access at installation.
Therefore you have to manually edit tomcat-users.xml to allow access for these accounts:
1.
Navigate to the Tomcat configuration folder.
2.
Edit tomcat-users.xml to include access for admin and manager. The configuration
should look similar to the following example:
<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
<role rolename="manager"/>
<role rolename="tomcat"/>
<role rolename="admin"/>
<role rolename="role1"/>
<user username="both" password="tomcat" roles="tomcat,role1"/>
<user username="tomcat" password="tomcat" roles="tomcat"/>
<user username="admin" password="admin" roles="admin,manager"/>
<user username="role1" password="tomcat" roles="role1"/>
</tomcat-users>
8.2.3.2 Install CQ5
1.
Unpack the installation files of the CQ5 Quickstart into a directory (without starting the server);
the installation directory will be referred to as <cq-installation-dir>:
•
Start the CQ5 Quickstart jar with the option -unpack; for example:
java -jar cq-wcm-quickstart-5.1.0.jar -unpack
This will create a folder <cq-installation-dir>crx-quickstart containing the
files and folders used for installation, without actually starting the installation.
Important
This must be done from the command line. If you open the jar file directly you will
activate the Quickstart installation and start the server.
2.
Copy the following jar files to the application server folder holding shared libraries:
a.
CRX\server\lib\container\jcr-1.0.jar
b.
CRX\server\lib\container\crx-shared.jar
3.
Restart Tomcat.
4.
Deploy the following web applications; they can be found in <cq-installationdir>\crx-quickstart\server\webapps:
a.
CRX webapp; crx-explorer_crx.war.
For example, deploy with the context path /crx.
b.
Launchpad webapp; crx-launchpad.war.
For example, deploy with the context path /launchpad.
5.
Start the two applications.
6.
Register your CRX license:
Page 46 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
a.
Access your CRX installation:
http://<server>:<port>/<context-path>/index.jsp
for example: http://<server>:<port>/crx/index.jsp
b.
Click the red warning message - “Click here...” (the message is a link).
c.
Enter your license key.
8.2.3.3 Install your Content Packages
1.
Access the CRX main console.
2.
Log in to the crx.system workspace as admin.
3.
Navigate to the Package Manager in CRX.
4.
Upload and install the following CQ5 package from <cq-installation-dir>\crxquickstart\repository\install\system:
•
WCM Security Content Package; cq-security-content-<cq-version>.jar.
5.
Switch to the crx.default workspace, again as admin
6.
Upload and install the following CQ5 packages from <cq-installation-dir>\crxquickstart\repository\install in the following order:
a.
Sling Content Package; 0001-cq-wcm-sling-content-<cq-version>.jar.
b.
WCM Content Package; 0002-cq-wcm-content-<cq-version>.jar.
8.2.3.4 Enable Replication for Author instances of CQ5
For an author instance of CQ5 you must configure it to start in “author run mode” so that you can
perform replications.
1.
Open the file: <cq-installation-dir>\crx-quickstart\launchpad
\sling.properties for edit.
2.
Add the following two properties to the file:
sling.jcrinstall.folder.name.regexp = .*/(install|config)(.author)?$
sling.run.modes = author
3.
Restart the crx-launchpad web application.
8.2.4 JBoss v4
After installing JBoss v4 you:
8.2.4.1 Install CQ5
1.
Unpack the installation files of the CQ5 Quickstart into a directory (without starting the server);
the installation directory is referred to as <cq-installation-dir>:
•
Start the CQ5 Quickstart jar with the option -unpack; for example:
java -jar cq-wcm-quickstart-5.1.0.jar -unpack
This creates a folder <cq-installation-dir>crx-quickstart containing the files
and folders used for installation, without actually starting the installation.
Page 47 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
Important
This must be done from the command line. If you open the jar file directly you will
activate the Quickstart installation and start the server.
2.
Copy the following jar files to the application server folder holding shared libraries
(<JBOSS_HOME]\server\default\lib>):
a.
CRX\server\lib\container\jcr-1.0.jar
b.
CRX\server\lib\container\crx-shared.jar
3.
Restart JBoss.
4.
Unpack the crx-explorer_crx.war file located in the <cq-installation-dir>\crxquickstart\server\webapps folder.
Note
In Windows, change the .war extension to .zip and unpack like any zip file. In
Linux, type jar xvf crx-explorer_crx.war to unpack.
5.
In the WEB-INF folder, open log4j.xml.
6.
Remove or comment the line <appender-ref ref="console"/> which is in the Loggers
section of the file and save your changes and exit the file. This disables console logging in the
CRX web application.
7.
In the WEB-INF folder, navigate to the lib folder and delete the following files:
• jcr-1.0.jar
• jackrabbit-api-1.4.jar
• day-commons-naming-1.1.1.jar
• crx-api-1.4.1.jar
8.
Pack the crx-explorer_crx.war file.
Note
In Windows, run the zip utility to compress it and rename the crxexplorer_crx.zip file to crx-explorer_crx.war. In Linux, type jar cvf
crx-explorer_crx.war.
9.
Deploy the following web applications; they can be found in <cq-installationdir>\crx-quickstart\server\webapps:
a.
CRX webapp; crx-explorer_crx.war.
For example, deploy with the context path /crx.
b.
Launchpad webapp; crx-launchpad.war.
For example, deploy with the context path /launchpad.
JBoss supports Hot Deployment, so you can simply drag the two files to <JBOSS_HOME>
\server\default\deploy.
10. Start the two applications.
Page 48 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
11. Register your CRX license:
a.
Access your CRX installation:
http://<server>:<port>/<context-path>/index.jsp
for example: http://<server>:<port>/crx/index.jsp
b.
Click the red warning message - “Click here...” (the message is a link).
c.
Enter your license key.
8.2.4.2 Configure the JBoss Server Login Module
By default JBoss' default login configuration attempts to authenticate users against a list of users
in the users.properties file. You must configure JBoss as follows to let login attempts by
unknown users to pass to the web application (CRX Explorer). The web application will then
process authentication by itself.
1.
Open the file for editing:
<JBOSS_HOME>\server\default\conf\login-config.xml
2.
In the section application-policy name="other" (at the bottom of the file) add the
attribute:
unauthenticatedIdentity="nobody"
to the login-module entry.
8.2.4.3 Install your Content Packages
Once you have installed CQ5 you will want to install content packages.
1.
Access the CRX main console:
http://<server>:<port>/crx-explorer_crx/index.jsp
2.
Log in to the crx.system workspace as admin.
3.
Navigate to the Package Manager in CRX.
4.
Upload and install the following CQ5 package from <cq-installation-dir>\crxquickstart\repository\install\system:
•
WCM Security Content Package; cq-security-content-<cq-version>.jar.
5.
Switch to the crx.default workspace, again as admin
6.
Upload and install the following CQ5 packages from <cq-installation-dir>\crxquickstart\repository\install in the following order:
7.
a.
Sling Content Package; 0001-cq-wcm-sling-content-<cq-version>.jar.
b.
WCM Content Package; 0002-cq-wcm-content-<cq-version>.jar.
Restart JBoss.
8.2.4.4 Enable Replication for Author instances of CQ5
For an author instance of CQ5 you must configure it to start in “author run mode” so that you can
perform replications.
Page 49 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
1.
Open the file: <cq-installation-dir>\crx-quickstart\launchpad
\sling.properties for edit.
2.
Add the following two properties to the file:
sling.jcrinstall.folder.name.regexp = .*/(install|config)(.author)?$
sling.run.modes = author
3.
Restart the crx-launchpad web application.
8.2.5 Generic Procedures
After installing the appropriate web application server you:
8.2.5.1 Generic Installation Procedure
This section provides generic information about installing CQ5 with an application server.
1.
Unpack the installation files of the CQ5 Quickstart into a directory (without starting the server);
the installation directory will be referred to as <cq-installation-dir>:
•
Start the CQ5 Quickstart jar with the option -unpack; for example:
java -jar cq-wcm-quickstart-5.1.0.jar -unpack
This will create a folder <cq-installation-dir>crx-quickstart containing the
files and folders used for installation, without actually starting the installation.
Important
This must be done from the command line. If you open the jar file directly you will
activate the Quickstart installation and start the server.
2.
Copy the following jar files to the application server folder holding shared libraries:
a.
CRX\server\lib\container\jcr-1.0.jar
b.
CRX\server\lib\container\crx-shared.jar
3.
Restart your web application server.
4.
Deploy the following web applications; they can be found in <cq-installationdir>\crx-quickstart\server\webapps:
a.
CRX webapp; crx-explorer_crx.war.
For example, deploy with the context path /crx.
b.
Launchpad webapp; crx-launchpad.war.
For example, deploy with the context path /launchpad.
5.
Start the two applications.
6.
Register your CRX license:
a.
Access your CRX installation:
http://<server>:<port>/<context-path>/index.jsp
for example: http://<server>:<port>/crx/index.jsp
b.
Click the red warning message - “Click here...” (the message is a link).
Page 50 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Installing CQ5
c.
Enter your license key.
8.2.5.2 Install Content Packages
Once you have installed CQ5 you will want to install content packages.
1.
Access the CRX main console.
2.
Log in to the crx.system workspace as admin.
3.
Navigate to the Package Manager in CRX.
4.
Upload and install the following CQ5 package from <cq-installation-dir>\crxquickstart\repository\install\system:
•
WCM Security Content Package; cq-security-content-<cq-version>.jar.
5.
Switch to the crx.default workspace, again as admin
6.
Upload and install the following CQ5 packages from <cq-installation-dir>\crxquickstart\repository\install in the following order:
a.
Sling Content Package; 0001-cq-wcm-sling-content-<cq-version>.jar.
b.
WCM Content Package; 0002-cq-wcm-content-<cq-version>.jar.
8.2.5.3 Enable Replication for Author instances of CQ5
For an author instance of CQ5 you must configure it to start in “author run mode” so that you can
perform replications.
1.
Open the file: <cq-installation-dir>\crx-quickstart\launchpad
\sling.properties for edit.
2.
Add the following two properties to the file:
sling.jcrinstall.folder.name.regexp = .*/(install|config)(.author)?$
sling.run.modes = author
3.
Restart the crx-launchpad web application.
Page 51 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
9 How to Use, Create, and Edit a Page
9.1 Managing Pages within CQ WCM
This section describes how to create a page within CQ WCM and then create content on that page.
Important
Your account needs the appropriate access rights to create or edit pages.
9.1.1 Creating a New Page
Unless all pages have been created for you in advance, before you can start creating content, you
must create a page:
1.
From the wcm/siteadmin window, select the level at which you want to create a new page.
In the following example, you are creating a page under the level English - shown in the left
pane; the right pane shows the existing pages at this level.
2.
In the Page menu, select Create. The Create Page window opens.
3.
In the Title field, select a title that is displayed to the user.
4.
In the Label field, select a label that is used to create the URI.
5.
Click the template used to create the new page, which determines the basic layout of the
page.
Page 52 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
6.
Click Create to create the page. You return to the wcm/siteadmin window where you can
see an entry for the new page.
This provides information about the page (for example when it was lasted edited and by
whom) which is updated as necessary.
Page 53 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
9.1.2 Editing a Page
After the page has been created, you can edit its content. When you first create a page, the page
includes only the text and elements from the template. You add content by double-clicking or
dragging and dropping components onto the page.
9.1.2.1 Opening a page
You can open the page to be edited by one of several methods:
• From wcm/siteadmin, you can double-click on the page title to open it for editing. Your page
opens in a new window.
• After you have opened a page, you can navigate to other pages within the site to edit them by
clicking hyperlinks.
9.1.2.2 Inserting a new paragraph
After you open the page, you can start to add content. You do this by adding paragraphs (also
called components).
To insert a new paragraph:
1.
Double-click the area labeled Drag components or assets here... or drag a
component from the floating toolbar to insert a new paragraph. This area appears wherever
new content can be added, such as at the end of the list if other paragraphs exist or at the
end of a column.
Note
If a paragraph already exists, you can right-click the paragraph and select
Insert. This inserts the new paragraph before the existing one.
2.
After you select to insert a paragraph, you see a list of the available paragraph types.
Note
Depending on your production environment, these choices may differ. For complete
details on components, see Default Components.
Page 54 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
3.
Select the component that you want and click OK. A window opens that allows you to
configure your paragraph and add content.
9.1.2.3 Editing a paragraph
To edit an existing paragraph, do one of the following:
• Double-click the paragraph to open it. You see the same window as when you created the
paragraph with the existing content. Make your changes and click OK.
• Right-click the paragraph and click Edit.
9.1.2.4 Moving a paragraph
To move a paragraph:
1.
Click the paragraph you want to move. CQ WCM highlights the paragraph.
Page 55 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
2.
Drag the paragraph to the new location and drop it. Your paragraph is moved. CQ WCM
indicates where paragraphs can be moved to with a green checkmark.
Page 56 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
9.1.2.5 Deleting a paragraph
To delete a paragraph:
1.
Select the paragraph and right-click.
Page 57 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
2.
Select Delete from the menu. CQ WCM confirms that you want to delete the paragraph as
this action cannot be undone.
3.
Click OK.
9.1.3 Moving or Renaming Page
The procedure to move or rename a page is the same. You do not need to do both: you can
rename a page without moving it or vice versa.
To move or rename a page:
1.
From the wcm/siteadmin window, click to select the page, then select the Page menu and
select Move. (You can also right-click after you click the page and select Move.) The Move
window opens where you can either specify a new location, a new name for the page, or both.
Page 58 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
2.
Fill in the following fields, as appropriate:
Move
Specify the page to be moved - this is usually filled in by default, depending on how and
where you started the move action.
to
Use the sitemap (available via the drop-down menu
) to select the location where the page should be moved to. If you are only renaming the
page, ignore this field.
Rename to
The current page label displays by default. Specify the new page label, if required.
3.
Click Move. CQ WCM confirms that you want to move or rename the current page. Click OK to
confirm.
9.1.4 Deleting a Page
1.
You can delete a page from various locations:
• Within the wcm/siteadmin window, click to select the page, then open the Page menu and
select Delete.
• Within sidekick use the page actions tab to select Delete - this deletes the page currently
open
• Within sidekick use the site map tab - navigate to page to be deleted, then right-click
and select Delete
2.
After the page has been selected you must confirm the deletion of the page - as the action
cannot be undone.
Note
If the page has been published you can restore the latest (or a specific) version,
but this may not have exactly the same content. See the section called “How To
Restore Pages” for further details.
9.1.5 Setting the Page Properties
Page Properties define the various properties of the page, such as titles, when they appear on the
website and others.
1.
Open the page you want to edit.
2.
In the sidekick, click the Page icon. Select Page Properties... from the list.
Page 59 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
3.
In the window that opens, you can modify the global, advanced, tags, impressions, and page
analytics of a page:
a.
Global
Title Text
The page title - as appears in the siteadmin list.
Page Title
A title to be used on the page.
Navigation Title
A title for the page for use within the navigation map. Often shorter than the full title.
Page 60 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
Subtitle
A subtitle for use on the page.
Page Language
The
Hide Page in Navigation
A toggle switch to indicate whether the page will be shown, or hidden in the page
navigation.
b.
Advanced
On Time
The date and time at which the published page will be activated. When published this
page will be kept dormant until the specified time. Leave these fields empty for pages
you want to publish immediately (the normal scenario).
Off Time
The time at which the published page will be deactivated. Again leave these fields
empty for pages you want to publish immediately.
Vanity URL
Allows you to enter a vanity URL for this page.
Redirect Vanity URL
Indicates whether you want the page to use the vanity URL.
c.
Tags/Keywords
Here you can add, or remove tags from the page by updating the list in the selection box:
• A completely new tag can be entered by typing the name on an empty space in the
selection box.
• With the drop-down functionality you can select from existing tags.
• An x will appear when you mouse-over a tag entry in the selection box; this can be
used to remove that tag for this page.
Page 61 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
d.
Impressions
This shows the activity on the page as in the impressions generated.
e.
Page Analytics
Page 62 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use, Create, and Edit a Page
Provider
The provider who will be generating the analytical statistics.
ID / Snippet
The ID or code snippet to be included on the page.
4.
Click OK to save the new properties.
Page 63 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
10 How to Publish a Page
10.1 How To Publish Pages
This section describes how to publish pages in CQ WCM. To publish a page, you activate its
contents. Conversely, to remove a page from publication, you deactivate its contents.
When you are working on pages that you are modifying, you can lock the pages so other users
cannot make changes or accidentally activate the content. In addition, you preview a page before
publishing by selecting Preview Mode in the sidekick.
If you are a system administrator and need to test the publish environment, see How to install CQ5
author and publish instances.
10.1.1 Activating Content
You activate pages in the wcm/siteadmin window. After you have opened a page and modified
its contents, you return to the wcm/siteadmin window to activate the content of that page or of an
entire tree of pages.
To activate page content:
1.
In the siteadmin/wcm window, select the page that you want to activate.
2.
In the Page menu, select Activation and then either Activate or Activate Tree.
To activate the content of only that page, select Activate. To activate the content of the
page and all its sub-pages, click Activate Tree. If you want to cancel the activation, click
Cancel.
3.
CQ WCM activates the selected content. To see that the page and its sub-pages (if selected)
have been published, refresh the page. The published page or pages appears in the
siteadmin/wcm window with information about who activated the content as well as date and
time of activation.
Page 64 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Publish a Page
10.1.2 Deactivating Content
To remove a page from the publish environment, you deactivate the content.
To deactivate a page:
1.
In the siteadmin/wcm window, select the page that you want to deactivate.
2.
In the Page menu, select Activation and then Deactivate.
3.
Refresh the siteadmin/wcm window and the content is no longer published.
10.1.3 Determining Page Publication Status
The colors next to pages in the siteadmin/wcm window indicate publication status.
Table 10.1.
Color
Description
Green
Publication was successful. Content is published.
Yellow
Publication is pending. Confirmation of publication has not yet
been received by the system.
Page 65 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Publish a Page
Color
Red
Description
Publication failed. There is no connection with the publish
instance. This can also mean that the content was deactivated.
10.1.4 Locking Pages
To lock a page that you are working on so no one can modify the contents or activate it:
1.
In the siteadmin/wcm window, select the page that you want to lock.
2.
In the Page menu, select Locking and then Lock. That page is locked to other users.
3.
CQ WCM displays the page as locked and indicates which user has locked the page.
10.1.5 Unlocking Pages
You can only unlock locked pages if you locked the page or if you have administrator privileges.
To unlock a page:
1.
In the siteadmin/wcm window, select the page you want to unlock.
2.
In the Page menu, select Locking and then Unlock. CQ WCM indicates that the page is
no longer locked.
10.1.6 Using Preview Mode
This mode allows you to preview the page as if it were appearing on your website in its final form.
Page 66 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Publish a Page
To access Preview mode:
1.
In the siteadmin/wcm window, open the page you want to view in Preview mode.
2.
In the sidekick, click the magnifying glass (preview mode). CQ WCM displays the page as it
appears on your web site in its final form.
Page 67 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
11 How to Restore a Page
11.1 How To Restore Pages
This section describes how to restore pages that have been previously deleted.
Note
Only pages that have been previously activated can be restored. Each time you activate a
page or tree, CQ WCM creates a new version of that page or tree.
To restore a page to a previous version:
1. In the wcm/siteadmin window, navigate to the page you want to restore and select it.
2. In the Page menu, select Restore and then Version or Tree. Selecting Version lists
previous versions of the document. Selecting Tree lists previous version of the content tree.
3. Click Restore. CQ WCM restores the version or tree to the one you selected.
Page 68 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
12 How to Create Templates
12.1 Developing Page Templates
CQ5 page templates are simply models used to create new pages. They can contain as little, or as
much, initial content as needed, their role being to create the correct initial node structures, with the
required properties (primarily sling:resourceType) set to allow editing and rendering.
12.1.1 Creating a new Template (based on an existing template)
Needless to say a new template can be created completely from scratch, but often an existing
template will be copied and updated to save you time and effort. For example, the templates within
Geometrixx can be used to get you started.
1.
Copy an existing template (preferably with a definition as close as possible to what you want
to achieve) to a new node.
Note
Templates are usually stored in /apps/<website-name>/templates/
<template-name>.
2.
Change the jcr:title of the new template node to reflect its new role. You can also update the
jcr:description if appropriate.
3.
Copy the component on which the template is based (this is indicated by the
sling:resourceType property of the jcr:content node within the template) to create a new
instance.
Note
Components are usually stored in /apps/<website-name>/components/
<component-name>.
4.
Update the jcr:title and jcr:description of the new component.
5.
Replace the thumbnail.png if you want a new thumbnail picture to be shown in the
template selection list.
6.
Update the sling:resourceType of the template's jcr:content node to reference the new
component.
7.
Make any further changes to the functionality or design of the template and/or its underlying
component.
Changes made to the /apps/<website>/templates/<template-name> node will affect
the template instance (as in the selection list).
Changes made to the /apps/<website>/components/<component-name> node will
affect the content page created when the template is used.
You can now create a page within your website using the new template.
Page 69 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
13 How to Use Tags
13.1 How to Manage Tags in CQ WCM
13.1.1 Using Sidekick to access and assign Tags
Many users will assign tags directly to the page they are editing. This can be done using the
sidekick:
1.
Within sidekick select the Page tab.
2.
Open Page Properties.
3.
Select the Tags/Keywords tab.
Here you can either enter a tag by either typing a new name, or selecting an existing tag from
the list of matching tags:
Or selecting a tag according to namespace, by using the drop-down option:
Page 70 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use Tags
13.1.2 The Tag Administration Console
The Tag Administration console can be used to manage your tags and taxonomies.
It shows information about the tags already created for your website, and a count of how often they
are referenced in the website:
From here you can perform various actions on tags and/or namespaces.
13.1.2.1 Creating or Editing Tags and Namespaces
1.
Depending on the level you are starting from you can create either a tag or a namespace:
a.
If you select Tags you can create a namespace:
Page 71 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use Tags
b.
2.
If you select a namespace (for example Demo) you can create a tag within that
namespace:
In both cases enter a name, title and description then click Create.
13.1.2.2 Deleting Tags
1.
In the right-hand pane select the namespace or tag that you want to delete.
2.
Click Delete.
3.
You will be asked to confirm the delete action. Click Yes to delete the item.
13.1.2.3 Activating and Deactivating Tags
1.
In the right-hand pane select the namespace or tag that you want to activate or deactivate.
2.
Click Activate, Activate Tree or Deactivate as required.
13.1.2.4 List - showing where tags are referenced
List will open a new window showing the paths of all pages using the highlighted tag:
Page 72 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use Tags
13.1.3 Searching for Tags
You can search for tags in both the author and publish environments.
13.1.3.1 Searching for tags with the Search component
The search component covers tags and can be used in both the author and publish environments.
Page 73 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Use Tags
13.1.3.2 Searching for tags with the Content Finder
In the author environment you can use the content finder to search for tags:
1.
Select the Pages tab in the content finder.
2.
Enter the tag you want to search for.
Using the prefix “tags:” will limit the search to tags only.
Page 74 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
14 Integrating with CQ DAM
14.1 How to Integrate CQ DAM into your CQ5 WCM Installation
The following details how to integrate an existing installation of CQ DAM into CQ5 WCM.
In this scenario CQ WCM and CQ DAM will be installed separately. The integration will result in a
new tab in the CQ WCM content finder that allows you to find and use media from DAM.
Note
CQ DAM has to be mounted as a virtual repository for ALL author and publish
installations (independently if in a cluster). See the CRX documentation for further
information.
1.
Install and start CQ5 WCM. See the section called “How to Install CQ WCM Author and
Publish Instances using Quickstart” for further information.
2.
Create a mount point in the repository.
3.
4.
a.
Open the CRX explorer.
b.
Create /etc/mnt/dam (see the code sample in step 7.b). The new nodes /mnt and /
dam should be of type sling:Folder.
c.
With Mixins... add mix:referenceable to /etc/mnt/dam.
Integrate CQ DAM functionality.
a.
Copy the file crx-quickstart/opt/examples/extensions/contentfinder/
dam.js to /libs/wcm/extensions/contentfinder by using WebDAV.
b.
Stop CQ5.
Enable RMI in the CRX used by CQ DAM.
a.
Open <CQDAM_HOME>/server/runtime/0/_crx/WEB-INF/web.xml.
b.
Configure the RMI configuration for the Repository Servlet; set the port to 8303.
<!-RMI configuration
-->
<init-param>
<param-name>rmi-port</param-name>
<param-value>8303</param-value>
<description>The RMI port for registering the repository in the RMI Registry.
If equals 0, the default port is used. Omit this parameter to
disable RMI server entirely.
</description>
</init-param>
5.
Configure CQ DAM as the virtual repository for CQ5 WCM.
Note
CQ DAM has an issue if it is installed in a path containing space characters.
In such a case you have to add the JVM Property Djava.rmi.server.useCodebaseOnly=true as the first parameter to CQ5, when DAM
is mounted as a virtual repository in CQ5.
Page 75 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Integrating with CQ DAM
a.
Open <CQ5_HOME>/server/runtime/0/_crx/WEB-INF/web.xml.
b.
In the Repository Servlet definition replace the following (either comment out, or remove):
<servlet-class>com.day.crx.j2ee.CRXRepositoryStartupServlet</servlet-class>
with the following configuration:
<servlet-class>com.day.crx.mount.virtual.VirtualRepositoryStartupServlet</servletclass>
<init-param>
<param-name>primaryWorkspace</param-name>
<param-value>crx.default</param-value>
</init-param>
<!-- virtual DAM repository -->
<init-param>
<param-name>mount.crx.default@rmi://127.0.0.1:8303/crx</param-name>
<param-value>/etc/mnt/dam</param-value>
</init-param>
Note
Make sure that:
• the port in rmi://127.0.0.1:8303 matches the port used in step 5.b
(Enable RMI in the CRX used by CQ DAM).
• the mount point /etc/mnt/dam matches that specified in step 2.b (Create a
mount point in the repository).
6.
Start CQ5.
7.
A new tab in the content finder allows you to find and use your media from CQ DAM:
Page 76 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
15 How to Find Logs and Audit
Entries
15.1 Finding the Audit Records and Log Files
Auditing records and log files relating to CQ5 can be found at various locations. The following is
provided to give you a overview of what you can find where.
Note
As CQ WCM is based on CRX, some of the log files listed below are actually generated
by CRX. Please see the CRX documentation for full details of these.
15.1.1 Audit Records
Audit records are held to provide a record of who did what when. Different audit records are
generated for both CQ WCM and OSGi events.
15.1.1.1 CQ WCM Audit records from within the siteadmin
1.
Open a page.
2.
From the sidekick you can select the
tab, then double-click on Audit Log...
3.
A new window will open showing the list of audit records for the current page.
4.
Click OK when you want to close the window.
15.1.1.2 CQ WCM Auditing records within the repository
Within the /var/audit folder, audit records are held according to the resource. You can drill
down until you can see the individual records and the information they contain.
Note
These entries hold the same information as displayed above in the siteadmin.
Page 77 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Find Logs and Audit Entries
15.1.1.3 OSGi Audit records from within the Felix console
OSGi events also generate audit records which can be seen from the Audit Log tab in the Felix
Web Management Console:
15.1.2 Log files
Various log files are held on the file server where you installed CQ5:
• <installation-path>\launchpad\logs
• error.log
Error messages, of varying levels of severity, related to the CRX Quick launchpad are
registered here.
• <installation-path>\logs
• access.log
All access requests to CQ WCM and the repository are registered here.
• error.log
Error messages (of varying levels of severity) are registered here.
• request.log
Each access request is registered here together with the response.
• server.log
All actions made by the server are registered here.
• stderr.log
Holds error messages, again of varying levels of severity, generated during startup.
• stdout.log
Holds logging messages indicating events during startup.
Page 78 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Find Logs and Audit Entries
• <installation-path>\logs\crx
• error.log
Error messages (of varying levels of severity) related to the repository are registered here.
• translation.log
Translation journaling.
• <installation-path>\repository\
• revision.log
Revision journaling information.
• <installation-path>\repository\repository\index
• redo.log
Redo event journaling.
• <installation-path>\repository\shared\journal
• journal.log<.x>
Event journaling on the repository; multiple versions.
• <installation-path>\repository\workspaces\<workspace>\index
• indexing_queue.log
Index journaling.
• redo.log
Redo event journaling.
• <installation-path>\server\logs
• access.log
All access requests to CQ WCM and the repository are registered here.
Page 79 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
16 Security Checklists
This section deals with various steps you should take to ensure that your CQ5 installation is
secure.
16.1 Security Checklist for System Administrators
16.1.1 Disable WebDAV
WebDAV should be disabled on the publish environment.
See the CRX documentation for further details.
16.1.2 Restrict Access via the Dispatcher
By configuring the Dispatcher you should restrict access so that only the following are available to
external visitors:
• /content - Site content
• /etc - Miscellaneous content such as designs
The following should be entered in the configuration file dispatcher.any:
# only handle the requests in the following acl. default is 'none'
# the glob pattern is matched against the first request line
/filter
{
/0001
{
/glob "*"
/type "deny"
}
/0002
{
/glob "* /content[./]"
/type "allow"
}
/0003
{
/glob "* /etc[./]"
/type "allow"
}
Note
This configuration includes the following restrictions:
1. Restricts access to the Servlet Engine Administration /admin
2. Restricts access to the Sling Console /system
3. Restricts access to CRX /crx
4. Restricts access to the following application specific folders:
• /apps – Application data
• /libs – CQ5 Library
• /var – var folder
Page 80 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Security Checklists
• /etc – Miscellaneous folder
• /home – User’s home folder
5. Restricts access to /tmp
6. Denies POST requests in case forms are not used.
16.1.3 Check for Cross-Site Scripting (XSS)
Cross-site scripting (XSS) allows attackers to inject code into web pages viewed by other users.
This security vulnerability can be exploited by malicious web users to bypass access controls.
Warning
CQ5 example code is not protected against such attacks.
16.2 Security Checklist for Power Users
16.2.1 Change Default Passwords
Day strongly recommends that you change the passwords for the following two accounts:
1.
Change the password for the CQ5 admin account.
Important
To change the password for the CQ5 admin account, you need to change the
admin password in both CRX and the OSGi Console. See the section called
“Changing the admin account in the CRX console” and the section called “Changing
the admin account in the OSGi Apache Felix console”.
2.
Change the password for the CQSE (Communiqué Servlet Engine) admin account.
Important
Further actions are described in the table the section called “Default Users and
Groups”, which gives an overview of the default users and groups included in the
standard installation.
16.2.1.1 Changing the admin account in the CRX console
To change the admin account in the CRX console:
1.
Log in to http://<server>:<port_number>/crx to open the CRX console.
2.
Log in as the administrator and switch to the crx.system workspace.
3.
Open the Content Explorer and navigate to the admin user and select it.
Page 81 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Security Checklists
4.
In the Security menu, select Set User Password. A Set User Password window
opens.
5.
Enter the new password and re-enter to confirm and click OK.
6.
Save your changes.
16.2.1.2 Changing the admin account in the OSGi Apache Felix console
To change the admin account in the OSGi Apache Felix console:
1.
Log in to http://<server>:<port_number>/system/console/configMgr to open
configurations in the Apache Felix console.
2.
In the Configurations menu, select CRX Sling Client Repository.
Page 82 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Security Checklists
3.
In the Admin password field, change the password to match the one you entered in the CRX
console.
4.
Click Save to save your changes.
16.3 Security Checklist for Developers
16.3.1 Use the user session, not the administrative session
This means you should use:
slingRequest.getResourceResolver().adaptTo(Session.class);
Page 83 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
17 Defining Performance Tests on
Your Publish Environment
17.1 Introduction
Performance is of prime importance to your publish environment. Therefore, you need to
carefully plan and analyze the performance tests you will make for the publish environment while
implementing your project.
17.1.1 Purpose of this How To
To give a standardized overview of the issues involved with defining a Test Concept specifically for
Performance Tests on your Publish environment.
17.1.2 Target Audience
• QA Engineers
• Project Managers
• System Administrators
17.2 Phases to be used
This document covers a standardized approach to performance tests for a CQ5 application on the
Publish environment. This involves the following 5 phases (which will be covered in more detail in
the next 5 sections):
1. Verification of Knowledge
2. Definition of Scope
3. Definition of Performance Goals
4. Test Methodologies
5. Optimization
Controlling is an additional, all-encompassing process - necessary but not limited to testing.
Page 84 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Defining Performance Tests on Your Publish Environment
Figure 17.1. The 5 Phases of Performance Testing on your Publish
Environment
17.3 Verification of Knowledge
A first step is to document the basis information which you need to know before you can start
testing:
• the architecture of your test environment
• an application map detailing the internal elements which will need testing (both in isolation and
combination)
17.3.1 Test Architecture
You should clearly document the architecture of the test environment being used for your
performance testing.
You will need a reproduction of your planned production Publish environment, together with
Dispatcher and Load Balancer.
17.3.2 Application Map
To get a clear overview you can create a map of the entire application (you may well have this from
tests on the Author environment).
A diagram representation of the internal elements of the application, can give an overview of the
testing requirements; with color-coding it can also act as a basis for reporting.
The example below illustrates the level of detail appropriate:
Page 85 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Defining Performance Tests on Your Publish Environment
Figure 17.2. Verification Map
17.4 Scope Definition
An application will usually have a selection of use cases. Some will be very important, others less
so.
To focus the scope of the performance testing on publish, we recommend that you define the:
• most important business use cases
• most critical technical use cases
The number of use cases is up to you, but it should be limited to an easily manageable number
(e.g. between 5 to 10).
Once the key use cases have been selected, then the key performance indicators (KPI) and the
tools used to measure them can be defined for each case. Examples of common KPIs include:
• End to end response time
• Servlet response time
• Response time for a single component
• Response time for the services
• Number of idle threads in the thread pool
• Number of free connections
• System resources such as CPU and I/O access
17.5 Test Methodologies
This concept has 4 scenarios used for defining and testing the performance goals:
1. Single component tests
2. Combined component tests
Page 86 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Defining Performance Tests on Your Publish Environment
3. Going Live scenario
4. Error scenarios
Based on the following principles.
Component Breakpoints
Each component has a specific breaking point when related to performance. This means
that a component can show good performance until a specific point is reached, after which
performance will degrade rapidly.
To get a full overview of the application, you must first verify your components to determine
when the breakpoint of each is reached.
To find the breakpoint you can perform a load test where, over a period of time, you increase
the number of users to create an increasing load. By monitoring this load, and the response of
the components, you will encounter specific performance behavior when the breaking point of
the component is reached. The point can be qualified by the number of concurrent transactions
per second, together with the number of concurrent users (if the component is sensitive to this
KPI).
This information can then act as a benchmark for improvements, indicate the efficiency of the
measures being used, and help define test scenarios.
Transactions
The term transaction is used to represent the request of a complete web page, including the
page itself and all subsequent calls; i.e. the page request, any AJAX calls, images and other
objects.
Request Drill Down
To fully analyze each request you can represent each element of the call stack, then total the
average processing time for each.
17.6 Defining the Performance Goals
Once the scope, and related KPIs have been defined, the specific performance goals can be set.
This involves devising test scenarios, together with target values.
You will need to test performance under both average and peak conditions. In addition, you will
need Going Live scenario tests to ensure that you can cater for increased interest in your website
when it is first made available.
Any experience, or statistics which you may have collected from an existing website can also be
useful in determining future goals; for example top traffic from your live website.
Note
As already mentioned, performance is of prime importance to a CQ5 project. Therefore
the goals (for both individual components and scenarios) should be defined at the
beginning of the project and verified during the implementation phase.
See also the Target Metrics section in the Project Manager Guide.
17.6.1 Single Component Tests
Critical components will need to be tested - under both average and peak conditions.
In both cases, you can define the expected number of transactions per second when a predefined
number of users are using the system.
Page 87 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Defining Performance Tests on Your Publish Environment
Table 17.1. Example - Single Component Test
Component
Test Type
Homepage Single User
Homepage 100 Users
#Users
Tx/sec
(Expected)
Average
1
1
Peak
1
3
Average
100
3
Peak
100
3
Tx/sec
(Tested)
Description
17.6.2 Combined Component Tests
Testing the components in combination gives a closer reflection of the applications behavior. Again
average and peak conditions must be tested.
Table 17.2. Example - Combined Component Tests
Scenario
Component
Mixed average Homepage
Mixed peak
#Users
Tx/sec
(Expected)
10
1
Search
10
1
News
10
2
Events
10
1
Activations
10
3
Homepage
100
5
Search
50
5
News
100
10
Events
100
10
Activations
20
20
Tx/sec
(Tested)
Description
Simulation of author
behavior.
Simulation of author
behavior.
17.6.3 Going Live Tests
During the first few days after your website is made available, you can expect an increased level
of interest. This will probably be even greater than the peak values you have been testing for. It
is strongly recommended to test Going Live scenarios to ensure that the system can cater for this
situation.
Table 17.3. Example - Going Live Tests
Scenario
Going Live peak
Test Type
#Users
Tx/sec
(Expected)
Homepage
200
20
Search
100
10
News
200
20
Events
200
20
Activations
20
20
Page 88 of 117
Tx/sec
(Tested)
Description
Simulation
of author
behavior.
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Defining Performance Tests on Your Publish Environment
17.6.4 Error Tests
Error scenarios must also be tested to ensure that the system reacts correctly and appropriately.
Not only in how the error itself is handled, but the impact it may have on performance. For
example:
• what happens when the user tries to input an invalid search term in the search box
• what happens when the search term is so general that it returns an excessive number of results
When devising these tests it should be remembered that not all scenarios will occur regularly.
However, their impact on the entire system is important.
Table 17.4. Example - Error Scenario Tests
Error
Scenario
Search
component
overload
Error Type
#Users
Tx/sec
(Expected)
Tx/sec
(Tested)
Description
Search on global
wildcard (asterisk)
10
1
Only *** are
searched.
Stop word
20
2
Searching for a
stop word.
Empty string
10
1
Searching
for an empty
string.
Special characters
10
1
Searching
for special
characters.
17.6.5 Endurance Tests
Certain issues will only be encountered after the system has been running for a continued period of
time; be that either hours or even days. An endurance test is used to test an constant average load
over a required period of time. Any performance degradation can then be analyzed.
Table 17.5. Example - Endurance Tests
Scenario
Test Type
Endurance test Homepage
(72 hours)
#Users
Tx/sec
(Expected)
10
1
Search
10
1
News
20
2
Events
10
1
Activations
1
3
Tx/sec
(Tested)
Description
Simulation of author
behavior.
17.7 Optimization
In the later stages of implementation you will need to optimize the application to fulfill / maximize
the performance goals.
Any optimizations made must be tested to ensure they have not affected the functionality and
verified with the load tests before being released.
Page 89 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Defining Performance Tests on Your Publish Environment
A selection of tools is available to help you with load-generation, performance monitoring and/or
results analysis:
• JMeter
• Load Runner (HP)
• CA Wily Introscope
• Determyne InsideApps
• InfraRED
• Java Interactive Profile
• many more...
After optimization, you will need to test again to confirm the impact.
17.8 Reporting
On-going reporting will be needed to keep everyone informed of the status; as mentioned
previously with color-coding the Architecture Map can be used for this.
After all tests have been completed you will want to report on:
• any critical errors encountered
• non-critical issues which will still need further investigation
• any assumptions made during testing
• any recommendations to arise from the testing
Page 90 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
18 How to Create a Fully Featured
Internet Website
How to Create a Fully Featured Internet Website
Page 91 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
19 How to Set Up the Development
Environment with Eclipse
19.1 How to Set Up the Development Environment with Eclipse
This document describes the process of setting up a local development environment for a simple
CQ5 project with Eclipse. It then describes how to integrate logic into the project through Java
coding and JSP scripting. Lastly, it points to open source software to enable collaborative and
automated developing.
The setup described here is an alternative among others and may vary from project to project.
The local development environment involves:
• A CQ5 installation that will act as your local environment.
• CRX Explorer within the CQ5 instance to create and edit nodes and properties within the CRX
repository.
• FileVault (VLT), a Day developed utility that maps the CRX repository to your file system.
• Eclipse to edit the project source on your local file system.
• Apache Maven to run local snapshot builds.
19.1.1 Creating the Project Structure in CQ5
This section describes the creation of a simple project structure in CQ5:
1.
Install CQ5 on your machine. Please refer to the section called “Installing a CQ WCM
instance - Generic procedure” for the detailed procedure. In the current context, CQ5 runs
locally on port 4502.
If already installed then ensure it is running and connect.
2.
3.
In the CRX Explorer, create the project structure:
1.
Under the /apps folder, create the nt:folder myApp.
2.
Under the myApp folder, create the nt:folder components.
3.
Under the myApp folder, create the nt:folder templates.
4.
Under the myApp folder, create the nt:folder install.
In your browser, navigate to the Miscellaneous tab. Under designs, create the design
page of your application:
• Title: My Application Design Page.
• Name: myApp.
• Template: Design Page Template.
19.1.2 Installing FileVault (VLT)
FileVault (VLT) is a tool developed by Day that maps the content of a CRX instance to your
file system. The VLT tool has similar functionalities to those of an SVN client, providing normal
check in, check out and management operations, as well as configuration options for flexible
representation of the project content.
Page 92 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up the Development Environment with Eclipse
To install VLT, follow the steps:
1.
In your file system, go to <cq-installation-dir>/crx-quickstart/opt/filevault.
The build is available in both tgz and zip formats.
2.
Extract the archive.
3.
Add <cq-installation-dir>/crx-quickstart/opt/filevault/vault-cli<version>/bin to your environment PATH so that the command files vlt or vlt.bat are
accessed as appropriate. For example, <cq-installation-dir>/crx-quickstart/
opt/filevault/vault-cli-1.1.2/bin
4.
Open a command line shell and execute vlt --help. Make sure it displays the following help
screen:
19.1.3 Installing Eclipse
Eclipse is open source software used to edit the project source locally on your file system. Apache
Maven is also open source software, used to run local snapshot builds: it compiles Java code and
stores the compiled code in a jar file.
In this section, you will install Eclipse and a Maven plugin which embeds the Maven functionality
within Eclipse:
1.
Download Eclipse - select the Eclipse IDE for Java EE Developers option.
2.
Install Eclipse: extract from the downloaded zip file to your destination directory.
3.
Start Eclipse:
4.
a.
Navigate to the directory into which you extracted the contents of the Eclipse installation
zip file. For example C:\Program Files\Eclipse\.
b.
Double-click on eclipse.exe (or eclipse.app) to start Eclipse.
Create a new workspace for your project and name it myApp.
Page 93 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up the Development Environment with Eclipse
5.
Install the Maven plugin (m2) from Sonatype. Disable Maven SCM handler for Subclipse
(Optional) and Maven Integration for AJDT (Optional).
6.
After installation it is recommended to restart Eclipse.
19.1.4 Creating the Project Structure in Eclipse
In this section, you will create 2 Maven projects:
• one called UI (after User Interface) which contains the CQ5 project structure with the JSP scripts.
• the other called Core which contains the Java code (source and compiled). The compiled code is
stored in a jar file.
The advantage of such a structure is that it adds modularity and autonomy to the logic your
application because each jar file (bundle) can be managed separately.
19.1.4.1 Create the UI Maven Project
To create the UI Maven project, follow the steps:
1.
In Eclipse open the Workbench.
2.
Create the UI Maven project:
1.
In the Menu bar, click File, select New, then Other... .
2.
In the dialog, expand the Maven folder, select Maven Project and click Next.
3.
Check the Create a simple project box and the Use default Workspace
locations box, then click Next.
4.
Define the Maven project:
• Group Id: com.day.cq5.myapp
• Artifact Id: ui
• Name: CQ5 MyApp UI
• Description: This is the UI module
5.
3.
Click Finish.
Set the Java Compiler to version 1.5:
1.
Right-click the ui project, select Properties.
2.
Select Java Compiler and set following properties to 1.5:
• Compiler compliance level
• Generated .class files compatibility
• Source compatibility
4.
3.
Click OK.
4.
In the dialog window, click Yes.
Create the filter.xml file which defines the content that will be exported by VLT:
1.
In Eclipse, navigate to ui/scr/main and create the content folder.
Page 94 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up the Development Environment with Eclipse
2.
Under content, create the META-INF folder.
3.
Under META-INF, create the vault folder.
4.
Under vault, create the filter.xml file.
5.
In filter.xml, copy the following code to filter.xml:
<?xml version="1.0" encoding="UTF-8"?>
<!-Defines which repository items are generally included
-->
<workspaceFilter vesion="1.0">
<filter root="/apps/myApp" />
<filter root="/etc/designs/myApp" />
</workspaceFilter>
6.
5.
Save the changes.
Check out the CQ5 content into your ui project with VLT:
1.
From the system command line, navigate to the directory holding your Eclipse
workspace <eclipse>/<workspace>/myApp/ui/src/main/content.
2.
Execute the command: vlt --credentials admin:admin co http://localhost:4502/crx
This command creates the folder jcr_root under <eclipse>/<workspace>/
myApp/ui/src/main/content. This maps to the CRX root (/). Under jcr_root the
following files and folders are created, as defined in filter.xml:
• apps/myApp
• etc/designs/myApp
It also creates two files, config.xml and settings.xml in <eclipse>/
<workspace>/myApp/ui/src/main/content/META-INF/vault. These are used
by VLT.
6.
7.
To enable Eclipse to map the file paths used in the JSP scripts, create a link to the apps
folder under ui:
1.
Right-click ui, select New, then Folder.
2.
In the dialog window, click Advanced and check the Link to folder in the file
system box.
3.
Click Browse, then specify <eclipse>/<workspace>/myApp/ui/src/main/
content/jcr_root/apps.
4.
Click OK.
5.
Click Finish.
To enable Eclipse to identify the Java classes, methods and objects used in the JSP scripts,
export the needed Java libraries from the CQ5 server to your file system and reference them
in the ui project.
In this example, you will reference the following libraries:
• libs/cq/install stored in the CQ5 server
• libs/sling/install stored in the CQ5 server
Page 95 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up the Development Environment with Eclipse
• libs/wcm/install stored in the CQ5 server
• <cq-installation-dir>/crx-quickstart/server/lib/container stored in
your file system
Proceed as follows:
1.
In your file system, create a CQ5 libraries folder called cq5libs. This folder can be
created anywhere.
2.
Under cq5libs, create the folders: cq, sling and wcm.
3.
From the system command line go to .../cq5libs/cq and execute vlt co http://
localhost:4502/crx /libs/cq/install . to export the libraries stored under /libs/cq/
install from the CQ5 server.
4.
From the system command line go to .../cq5libs/sling and execute vlt co http://
localhost:4502/crx /libs/sling/install . to export the libraries stored under /libs/
sling/install from the CQ5 server.
5.
From the system command line go to .../cq5libs/wcm and execute vlt co http://
localhost:4502/crx /libs/wcm/install . to export the libraries stored under /libs/wcm/
install from the CQ5 server.
6.
In Eclipse, right-click the ui project, select Build Path, then Configure Build
Path. In the dialog select the Libraries tab.
7.
Click Add External JARS..., navigate to .../cq5libs/cq/jcr_root, select all
the jar files and click Open.
8.
Click Add External JARS..., navigate to .../cq5libs/sling/jcr_root, select
all the jar files and click Open.
9.
Click Add External JARS..., navigate to .../cq5libs/wcm/jcr_root, select all
the jar files and click Open.
10. Click Add External JARS..., navigate to <cq-installation-dir>/crxquickstart/server/lib/container, select all the jar files and click Open.
11. Click OK.
19.1.4.2 Create the Core Maven Project
To create the Core Maven project, follow the steps:
1.
In Eclipse, create the Core Maven project:
1.
In the Menu bar, click File, select New, then Other... .
2.
In the dialog, expand the Maven folder, select Maven Project and click Next.
3.
Check the Create a simple project box and the Use default Workspace
locations box, then click Next.
4.
Define the Maven project:
• Group Id: com.day.cq5.myapp
• Artifact Id: core
• Name: CQ5 MyApp Core
Page 96 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up the Development Environment with Eclipse
• Description: This is the Core module
5.
2.
Click Finish.
Add the necessary plugins and dependencies to the core project:
1.
Open the pom.xml file under core.
2.
Copy-paste following code before the </project> tag:
<packaging>bundle</packaging>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.5</source>
<target>1.5</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<version>1.4.3</version>
<extensions>true</extensions>
<configuration>
<instructions>
<Export-Package> com.day.cq5.myapp.*;version=
${pom.version}
</Export-Package>
</instructions>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>com.day.cq.wcm</groupId>
<artifactId>cq-wcm-api</artifactId>
<version>5.1.20</version>
</dependency>
<dependency>
<groupId>com.day.cq</groupId>
<artifactId>cq-commons</artifactId>
<version>5.1.18</version>
</dependency>
<dependency>
<groupId>org.apache.sling</groupId>
<artifactId>org.apache.sling.api</artifactId>
<version>2.0.3-incubator-R708951</version>
</dependency>
</dependencies>
3.
3.
Save the changes.
Deploy the CQ5 specific artifacts as defined in the pom.xml (cq-wcm-api, cq-commons and
org.apache.sling.api) to the local Maven repository:
Page 97 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up the Development Environment with Eclipse
1.
From the system command line go to <your-user-dir>/.m2/repository/com/
day/cq/wcm/cq-wcm-api/5.1.20 (create the folders if they don't exist) and execute
vlt co http://localhost:4502/crx /libs/wcm/install/cq-wcm-api-5.1.20.jar . to export the
library from the CQ5 server.
2.
From the system command line go to <your-user-dir>/.m2/repository/com/
day/cq/cq-commons/5.1.18 (create the folders if they don't exist) and execute vlt
co http://localhost:4502/crx /libs/cq/install/cq-commons-5.1.18.jar . to export the
library from the CQ5 server.
3.
From the system command line go to <your-user-dir>/.m2/repository/org/
apache/sling/org.apache.sling.api/2.0.3-incubator-R708951 (create
the folders if they don't exist) and execute vlt co http://localhost:4502/crx /libs/sling/
install/org.apache.sling.api-2.0.3-incubator-R708951.jar . to export the library from
the CQ5 server.
Note
You don't need to perform this step if the three CQ5 artifacts are globally deployed
for the project on a Maven repository (e.g. using Apache Archiva).
4.
Set the Java Compiler to version 1.5:
1.
Right-click the core project, select Properties.
2.
Select Java Compiler and set following properties to 1.5:
• Compiler compliance level
• Generated .class files compatibility
• Source compatibility
5.
3.
Click OK.
4.
In the dialog window, click Yes.
Create the package com.day.cq5.myapp that will contain the Java classes under core/
src/main/java:
1.
Under core, right-click src/main/java, select New, then Package.
2.
Name it com.day.cq5.myapp and click Finish.
19.1.5 Scripting with Eclipse and CQ5
When editing UI code use the following sequence:
• Create a template and a component with the CRX Explorer.
• Update the changes with VLT (export from the repository to your file system) .
• Create a component script (JSP) with Eclipse.
• Check in the changes from the file system into the repository with VLT.
The following example illustrates this process:
1.
Create a new template with the CRX Explorer:
1.
In the CRX Explorer, under /apps/myApp/templates, create a new template: Name:
contentpage Type: cq:Template
Page 98 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up the Development Environment with Eclipse
2.
2.
Under the contentpage Node, edit the Property jcr:title and add as Value:
MyApp Content Page Template
3.
Under the contentpage Node, add a new Node: Name: jcr:content Type:
cq:PageContent
4.
Under the jcr:content Node, edit the Property sling:resourceType and add as
Value: myApp/components/contentpage
5.
Under the jcr:content Node, add a new Property: Name: personName Value:
myName
Create a new component with the CRX Explorer:
•
3.
4.
In the CRX Explorer, under /apps/myApp/components, create a new component:
Name: contentpage Type: cq:Component
Use VLT to update the changes made from your repository to your file system, and therefore
Eclipse:
1.
From the system command line navigate to <eclipse>/<workspace>/myApp/ui/
src/main/content/jcr_root.
2.
Execute: vlt st --show-update to see the changes made on the repository.
3.
Execute: vlt up to update the changes from the repository to your file system.
Create the component script (JSP) with Eclipse:
1.
In Eclipse, navigate to ui/src/main/content/jcr_root/apps/myApp/
components/contentpage.
2.
Right-click contentpage, select New, then File.
3.
In the dialog, name the file contentpage.jsp and click Finish.
4.
Copy the following code into contentpage.jsp:
This is the contentpage component.
5.
5.
6.
Save the changes.
With VLT check in the changes from the file system into the repository:
1.
From the system command line navigate to <eclipse>/<workspace>/myApp/ui/
src/main/content/jcr_root.
2.
Execute: vlt st to see the changes made on the file system.
3.
Execute: vlt add apps/myApp/components/contentpage/contentpage.jsp to add the
contentpage.jsp file to VLT control.
4.
Execute: vlt ci to commit the contentpage.jsp file to the repository.
From CQ5 create a page based on this template. Open the page to make sure it displays the
following message:
This is the contentpage component.
Page 99 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up the Development Environment with Eclipse
Tip
It is possible to define the VLT commands as External Tools in Eclipse. This enables you
to run the VLT commands from within Eclipse.
19.1.6 Java Developing with Eclipse and CQ5
When editing Core code use the following sequence:
• Create a Java class.
• Compile the Java class.
• Reference the jar file in the ui library.
• Embed the Java Class logic into the JSP script.
• Use VLT to check these changes to the JSP script (in the file system) into the repository.
• Use VLT to deploy the jar file (with the compiled class) from the file system into the repository.
The following example illustrates this process:
1.
Create the Java class:
1.
In Eclipse, under core/src/main/java, right-click the com.day.cq5.myapp
package, select New, then Class.
2.
In the dialog window, name the Java Class HelloPerson and click Finish. Eclipse
creates and opens the file HelloPerson.java.
3.
In HelloPerson.java replace the existing code with the following:
package com.day.cq5.myapp;
import com.day.cq.wcm.api.Page;
public class HelloPerson {
private Page personPage;
public static final String PN_PERSON_NAME = "personName";
public HelloPerson(Page personPage) {
this.personPage = personPage;
}
public String getHelloMessage() {
String personName = personPage.getProperties().get(PN_PERSON_NAME).toString();
return personName != null ? personName : "--empty--";
}
}
4.
2.
3.
Save the changes.
Compile the Java class:
1.
Right-click the core project, select Run As, then Maven Install.
2.
Make sure that a new file core-0.0.1-SNAPSHOT.jar (containing the compiled
class) is created under core/target.
Reference this jar file in the ui library to enable the code completion when accessing this
class with the JSP script:
Page 100 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up the Development Environment with Eclipse
4.
1.
In Eclipse, right-click the ui project, select Build Path, then Configure Build
Path. In the dialog select the Libraries tab.
2.
Click Add JARS... and navigate to core/target, select the core-0.0.1SNAPSHOT.jar file and click OK.
3.
Click OK to close the dialog.
Embed the Java Class logic into the JSP script:
1.
In Eclipse, open the JSP script contentpage.jsp in ui/src/main/content/
jcr_root/apps/myApp/components/contentpage.
2.
Replace the existing code with the following:
<%@ page import="com.day.cq5.myapp.HelloPerson" %>
<%@include file="/libs/wcm/global.jsp"%>
<%
HelloPerson hello = new HelloPerson(currentPage);
String msg = hello.getHelloMessage();
%>
Hello, <%= msg %>.</br></br>
This is the contenpage component.
3.
5.
6.
7.
Save the changes.
With VTL check in the changes to the JSP script from the file system to the repository:
1.
From the system command line navigate to <eclipse>/<workspace>/myApp/ui/
src/main/content/jcr_root.
2.
Execute: vlt st to see the changes made on the file system.
3.
Execute: vlt ci to commit the modified contentpage.jsp file to the repository.
Deploy the jar file containing the compiled class from the file system into the repository with
VLT:
1.
In Eclipse, under core/target, copy the core-0.0.1-SNAPSHOT.jar file.
2.
In Eclipse navigate to ui/scr/main/content/jcr_root/apps/myapp/install
and paste the copied file.
3.
From the system command line navigate to <eclipse>/<workspace>/myApp/ui/
src/main/content/jcr_root.
4.
Execute: vlt st to see the changes made on the file system.
5.
Execute: vlt add apps/myApp/install/core-0.0.1-SNAPSHOT.jar to add the jar file to
VLT control.
6.
Execute: vlt ci to commit the jar file to the repository.
In your browser, refresh the CQ5 page to make sure it displays following message:
Hello, myName.
This is the contentpage component.
8.
In CRX Explorer, change the value myName and make sure that the new value is displayed
when you refresh the page.
Page 101 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Set Up the Development Environment with Eclipse
19.1.7 Building collaborative and automated projects
This section points to three open source softwares which enhance the development of CQ5
projects by adding collaboration and automation features:
• Subversion (SVN) to manage a central repository where all the developers involved in the project
can commit and retrieve the code and the content they generate on their local instance.
• Apache Archiva to centrally store and retrieve the project libraries.
• Apache Continuum to automate the build process.
19.1.7.1 Collaboration with Subversion (SVN)
As the CQ5 repository can be mapped to your file system with VLT, it is now easy to set up a
central repository with SVN. This is used by all developers in the project as a place they can
commit, and retrieve, the code and content they generate on their local instances.
The setup of an SVN server is not covered in this document as many tutorials are already available
online.
When VLT is in operation it creates .vlt files within the local directory structure. These .vlt files hold
timestamps and other VLT-specific information that should not be checked into the SVN repository.
This can be prevented by adding .vlt to the ignore list of the local SVN setup. To do this you add
the following code to the local SVN setup file - settings.xml in the .subversion directory of your
user's HOME directory:
[miscellany]
### Set global-ignores to a set of whitespace-delimited globs
### which Subversion will ignore in its 'status' output, and
### while importing or adding files and directories.
global-ignores = .vlt
19.1.7.2 Central dependency management with Apache Archiva
Java libraries, called artifacts in Maven language, can be managed centrally through Apache
Archiva, an artifact repository that is used to store and retrieve the project artifacts. The setup of
Archiva is well detailed online and can be referenced during setup. The Archiva server requires
little management outside that of configuring local developer accounts to obtain access to the
snapshots and full releases.
19.1.7.3 Build automation with Apache Continuum
Once the project content and code is centrally available through an SVN server, it is possible to
automate the build process and run the build on a daily basis (for example a nightly build). This is
done with Apache Continuum, a continuous integration server with the sole duty of providing build
management of artifacts and releases.
The setup of Continuum is also well detailed online.
Page 102 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
20 How to Model Data
20.1 Data Modeling - David Nuescheler's Model
20.1.1 Source
The following details are ideas and comments expressed by David Nuescheler.
David is co-founder and CTO of Day Software AG, a leading provider of global content
management and content infrastructure software. He also leads the development of JSR-170, the
Java Content Repository (JCR) application programming interface (API), the technology standard
for content management.
Further updates can also be seen on http://wiki.apache.org/jackrabbit/DavidsModel.
20.1.2 Introduction from David
In various discussions I found that developers are somewhat at unease with the features and
functionalities presented by JCR when it comes to content modeling. There is no guide and very
little experience yet on how to model content in a repository and why one content model is better
than the other.
While in the relational world the software industry has a lot of experience on how to model data, we
are still at the early stages for the content repository space.
I would like to start filling this void by expressing my personal opinions on how content should
be modeled, hoping that this could some day graduate into something more meaningful to the
developers community, which is not just "my opinion" but something that is more generally
applicable. So consider this my quickly evolving first stab at it.
Important
Disclaimer: These guidelines express my personal, sometimes controversial views. I am
looking forward to debate these guidelines and refine them.
20.1.3 Seven Simple Rules
20.1.3.1 Rule #1: Data First, Structure Later. Maybe.
20.1.3.1.1 Explanation
I recommend not to worry about a declared data structure in an ERD sense. Initially.
Learn to love nt:unstructured (& friends) in development.
I think Stefano pretty much sums this one up.
My bottom-line: Structure is expensive and in many cases it is entirely unnecessary to explicitly
declare structure to the underlying storage.
There is an implicit contract about structure that your application inherently uses. Let's say I store
the modification date of a blog post in a lastModified property. My App will automatically know
to read the modification date from that same property again, there is really no need to declare that
explicitly.
Further data constraints like mandatory or type and value constraints should only be applied where
required for data integrity reasons.
Page 103 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Model Data
20.1.3.1.2 Example
The above example of using a "lastModified" Date property on for example "blog post" node, really
does not mean that there is a need for a special nodetype. I would definitely use "nt:unstructured"
for my blog post nodes at least initially. Since in my blogging application all I am going to do is to
display the lastModified date anyway (possibly "order by" it) I barely care if it is a Date at all. Since
I implicitly trust my blog-writing application to put a "date" there anyway, there really is no need to
declare the presence of a "lastModified" date in the form a of nodetype.
20.1.3.1.3 Discussion
http://www.nabble.com/DM-Rule-#1:-Data-First,-Structure-Later.-Maybe.-tf4039967.html
20.1.3.2 Rule #2: Drive the content hierarchy, don't let it happen.
20.1.3.2.1 Explanation
The content hierarchy is a very valuable asset. So don't just let it happen, design it. If you don't
have a "good", human-readable name for a node, that's probably that you should reconsider.
Arbitrary numbers are hardly ever a "good name".
While it may be extremely easy to quickly put an existing relational model into a hierarchical model,
one should put some thought in that process.
In my experience if one thinks of access control and containment usually good drivers for the
content hierarchy. Think of it as if it was your file system. Maybe even use files and folders to
model it on your local disk.
Personally I prefer hierarchy conventions over the nodetyping system in a lot of cases initially, and
introduce the typing later.
20.1.3.2.2 Example
I would model a simple blogging system as follows. Please note that initially I don't even care about
the respective nodetypes that I use at this point.
/content/myblog
/content/myblog/posts
/content/myblog/posts/what_i_learned_today
/content/myblog/posts/iphone_shipping
/content/myblog/comments/iphone_shipping/i_like_it_too
/content/myblog/comments/iphone_shipping/i_like_it_too/i_hate_it
I think one of the things that become apparent is that we all understand the structure of the content
based on the example without any further explanations.
What may be unexpected initially is why I wouldn't store the "comments" with the "post", which is
due to access control which I would like to be applied in a reasonably hierarchical way.
Using the above content model I can easily allow the "anonymous" user to "create" comments, but
keep the anonymous user on a read-only basis for the rest of the workspace.
20.1.3.2.3 Discussion
http://www.nabble.com/DM-Rule-#2:-Drive-the-content-hierarchy,-don't-let-it-happen.tf4039994.html
20.1.3.3 Rule #3: Workspaces are for clone(), merge() and update().
20.1.3.3.1 Explanation
If you don't use clone(), merge() or update() methods in your application a single workspace is
probably the way to go.
Page 104 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Model Data
"Corresponding nodes" is a concept defined in the JCR spec. Essentially, it boils down to nodes
that represent the same content, in different so-called workspaces.
JCR introduces the very abstract concept of Workspaces which leaves a lot of developers unclear
on what to do with them. I would like to propose to put your use of workspaces to the following to
test.
If you have a considerable overlap of "corresponding" nodes (essentially the nodes with the same
UUID) in multiple workspaces you probably put workspaces to good use.
If there is no overlap of nodes with the same UUID you are probably abusing workspaces.
Workspaces should not be used for access control. Visibility of content for a particular group of
users is not a good argument to separate things into different workspaces. JCR features "Access
Control" in the content repository to provide for that.
Workspaces are the boundary for references and query.
20.1.3.3.2 Example
Use workspaces for things like:
• v1.2 of your project vs. a v1.3 of your project
• a "development", "QA" and a "published" state of content
Do not use workspaces for things like:
• user home directories
• distinct content for different target audiences like public, private, local, ...
• mail-inboxes for different users
20.1.3.3.3 Discussion
http://www.nabble.com/DM-Rule-#3:-Workspaces-are-for-corresponding-nodes.-tf4040010.html
20.1.3.4 Rule #4: Beware of Same Name Siblings.
20.1.3.4.1 Explanation
While Same Name Siblings (SNS) have been introduced into the spec to allow compatibility with
data structures that are designed for and expressed through XML and therefore are extremely
valuable to JCR, SNS come with a substantial overhead and complexity for the repository.
Any path into the content repository that contains an SNS in one of its path segments becomes
much less stable, if an SNS is removed or reordered, it has an impact on the paths of all the other
SNS and their children.
For import of XML or interaction with existing XML SNS maybe necessary and useful but I have
never used SNS, and never will in my "green field" data models.
20.1.3.4.2 Example
Use
/content/myblog/posts/what_i_learned_today
/content/myblog/posts/iphone_shipping
instead of
Page 105 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Model Data
/content/blog[1]/post[1]
/content/blog[1]/post[2]
20.1.3.4.3 Discussion
http://www.nabble.com/DM-Rule-#4:-Beware-of-Same-Name-Siblings.-tf4040024.html
20.1.3.5 Rule #5: References considered harmful.
20.1.3.5.1 Explanation
References imply referential integrity. I find it important to understand that references do not just
add additional cost for the repository managing the referential integrity, but they also are costly
from a content flexibility perspective.
Personally I make sure I only ever use references when I really cannot deal with a dangling
reference and otherwise use a path, a name or a string UUID to refer to another node.
20.1.3.5.2 Example
Let's assume I allow "references" from a document (a) to another document (b). If I model this
relation using reference properties this means that the two documents are linked on a repository
level. I cannot export/import document (a) individually, since the reference property's target may
not exist. Other operations like merge, update, restore or clone are affected as well.
So I would either model those references as "weak-references" (in JCR v1.0 his essentially boils
down to string properties that contain the uuid of the target node) or simply use a path. Sometimes
the path is more meaningful to begin with.
I think there are use cases where a system really can't work if a reference is dangling, but I just
can't come up with a good "real" yet simple example from my direct experience.
20.1.3.5.3 Discussion
http://www.nabble.com/DM-Rule-#5:-References-considered-harmful.-tf4040042.html
20.1.3.6 Rule #6: Files are Files are Files.
20.1.3.6.1 Explanation
If a content model exposes something that even remotely smells like a file or a folder I try to use (or
extend from) nt:file, nt:folder and nt:resource.
In my experience a lot of generic applications allow interaction with nt:folder and nt:files implicitly
and know how to handle and display those event if they are enriched with additional metainformation. For example a direct interaction with file server implementations like CIFS or WebDAV
sitting on top of JCR become implicit.
I think as good rule of thumb one could use the following: If you need to store the filename and
the mime-type then nt:file/nt:resource is a very good match. If you could have multiple "files" an
nt:folder is a good place to store them.
If you need to add meta information for your resource, let's say an "author" or a "description"
property, extend nt:resource not the nt:file. I rarely extend nt:file and frequently extend nt:resource.
20.1.3.6.2 Example
Let's assume that someone would like to upload an image to a blog entry at:
/content/myblog/posts/iphone_shipping
Page 106 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Model Data
and maybe the initial gut reaction would be to add a binary property containing the picture.
While there certainly are good use cases to use just a binary property (let's say the name is
irrelevant and the mime-type is implicit) in this case I would recommend the following structure for
my blog example.
/content/myblog/posts/iphone_shipping/attachments [nt:folder]
/content/myblog/posts/iphone_shipping/attachments/front.jpg [nt:file]
/content/myblog/posts/iphone_shipping/attachments/front.jpg/jcr:content [nt:resource]
20.1.3.6.3 Discussion
http://www.nabble.com/DM-Rule-#6:-Files-are-Files-are-Files.-tf4040063.html
20.1.3.7 Rule #7: IDs are evil.
20.1.3.7.1 Explanation
In relational databases IDs are a necessary means to express relations, so people tend to use
them in content models as well. Mostly for the wrong reasons through.
If your content model is full of properties that end in "Id" you probably are not leveraging the
hierarchy properly.
It is true that some nodes need a stable identification throughout their live cycle. Much fewer than
you might think though. mix:referenceable provides such a mechanism built into the repository,
so there really is no need to come up with an additional means of identifying a node in a stable
fashion.
Keep also in mind that items can be identified by path, and as much as "symlinks" make way
more sense for most users than hardlinks in a unix filesystem, a path makes a sense for most
applications to refer to a target node.
More importantly, it is **mix**:referenceable which means that it can be applied to a node at the
point in time when you actually need to reference it.
So let's say just because you would like to be able to potentially reference a node of type
"Document" does not mean that your "Document" nodetype has to extend from mix:referenceable
in a static fashion since it can be added to any instance of the "Document" dynamically.
20.1.3.7.2 Example
use:
/content/myblog/posts/iphone_shipping/attachments/front.jpg
instead of:
[Blog]
- blogId
- author
[Post]
- postId
- blogId
- title
- text
- date
[Attachment]
- attachmentId
- postId
- filename
Page 107 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
How to Model Data
+ resource (nt:resource)
20.1.3.7.3 Discussion
http://www.nabble.com/DM-Rule-#7:-IDs-are-evil.-tf4040076.html
Page 108 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
21 JSP Tag Libraries
21.1 JSP Tag Libraries
The CQ and Sling tab libraries give you access to specific functions for use in the JSP script of
your templates and components.
21.1.1 CQ Tag Library
The CQ tag library contains helpful CQ functions.
To use the CQ Tag Library in your script, the script must start with the following code:
<%@taglib prefix="cq" uri="http://www.day.com/taglibs/cq/1.0" %>
Note
When the /libs/wcm/global.jsp file is included in the script, the cq taglib is
automatically declared.
Tip
When you develop the jsp script of a CQ5 component, it is recommended to include
following code at the top of the script:
<%@include file="/libs/wcm/global.jsp"%>
It declares the sling, cq and jstl taglibs and exposes the regularly used scripting objects
defined by the <cq:defineObjects /> tag. This shortens and simplifies the jsp code of your
component.
21.1.1.1 <cq:setContentBundle>
The <cq:setContentBundle> tag creates an i18n localization context and stores it in the
javax.servlet.jsp.jstl.fmt.localizationContext configuration variable.
It has the following attribute:
language
The language of the locale for which to retrieve the resource bundle.
The "content bundle" can be simply used by standard JSTL <fmt:message> tags. The lookup of
messages by keys is two-fold:
1. First, the JCR properties of the underlying resource that is currently rendered are searched for
translations. This allows you to define a simple component dialog to edit those values.
2. If the node does not contain a property named exactly like the key, the fallback is to load a
resource bundle from the sling request (SlingHttpServletRequest.getResourceBundle(Locale)).
The language or locale for this bundle is defined this way:
a. First, if the parameter language of the<cq:setContentBundle> tag is set, this is used.
b. Otherwise, the locale of the page is looked up. This is taken from the page path (eg. the path
/content/site/en/some/page produces the "en" locale).
Example:
<%@include file="/libs/wcm/global.jsp"%><%
Page 109 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
JSP Tag Libraries
%><%@ page import="com.day.cq.wcm.foundation.forms.ValidationInfo,
com.day.cq.wcm.foundation.forms.FormsConstants,
com.day.cq.wcm.foundation.forms.FormsHelper,
org.apache.sling.api.resource.Resource,
org.apache.sling.api.resource.ResourceUtil,
org.apache.sling.api.resource.ValueMap" %><%
%><cq:setContentBundle/>
21.1.1.2 <cq:include>
The <cq:include> tag includes a resource into the current page.
It has the following attributes:
flush
A boolean defining whether to flush the output before including the target.
path
The path to the resource object to be included in the current request processing. If this path is
relative it is appended to the path of the current resource whose script is including the given
resource. Either path and resourceType, or script must be specified.
resourceType
The resource type of the resource to be included. If the resource type is set, the path must be
the exact path to a resource object: in this case, adding parameters, selectors and extensions
to the path is not supported.
If the resource to be included is specified with the path attribute that cannot be resolved to a
resource, the tag may create a synthetic resource object out of the path and this resource type.
Either path and resourceType, or script must be specified.
script
The jsp script to include. Either path and resourceType, or script must be specified.
ignoreComponentHierarchy
A boolean controlling whether the component hierarchy should be ignored for script resolution.
If true, only the search paths are respected.
Example:
<%@taglib prefix="cq" uri="http://www.day.com/taglibs/cq/1.0" %><%
%><div class="center">
<cq:include path="trail" resourceType="foundation/components/breadcrumb" />
<cq:include path="title" resourceType="foundation/components/title" />
<cq:include script="redirect.jsp"/>
<cq:include path="par" resourceType="foundation/components/parsys" />
</div>
Note
Should you use <%@ include file="myScript.jsp" %> or <cq:include script="myScript.jsp"
%> to include a script?
• The <%@ include file="myScript.jsp" %> directive informs the JSP compiler to include
a complete file into the current file. It is as if the contents of the included file were
pasted directly into the original file.
• With the <cq:include script="myScript.jsp" %> directive, the file is included at runtime.
Note
Should you use <cq:include> or <sling:include>?
Page 110 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
JSP Tag Libraries
• When developing CQ5 components, Day recommends that you use <cq:include>.
• <cq:include> allows you to directly include script files by their name when using the
script attribute. This takes component and resource type inheritance into account, and
is often simpler than strict adherence to Sling's script resolution using selectors and
extensions.
21.1.1.3 <cq:defineObjects>
The <cq:defineObjects> tag exposes the following, regularly used, scripting objects which can be
referenced by the developer. It also exposes the objects defined by the <sling:defineObjects> tag.
componentContext
the current component context object of the request
(com.day.cq.wcm.api.components.ComponentContext interface).
component
the current CQ5 component object of the current resource
(com.day.cq.wcm.api.components.Component interface).
currentDesign
the current design object of the current page (com.day.cq.wcm.api.designer.Design interface).
currentPage
the current CQ WCM page object (com.day.cq.wcm.api.Page interface).
currentStyle
the current style object of the current cell (com.day.cq.wcm.api.designer.Style interface).
designer
the designer object used to access design information (com.day.cq.wcm.api.designer.Designer
interface).
editContext
the edit context object of the CQ5 component (com.day.cq.wcm.api.components.EditContext
interface).
pageManager
the page manager object for page level operations (com.day.cq.wcm.api.PageManager
interface).
pageProperties
the page properties object of the current page (org.apache.sling.api.resource.ValueMap).
properties
the properties object of the current resource (org.apache.sling.api.resource.ValueMap).
resourceDesign
the design object of the resource page (com.day.cq.wcm.api.designer.Design interface).
resourcePage
the resource page object (com.day.cq.wcm.api.Page interface).
It has the following attributes:
requestName
inherited from sling
responseName
inherited from sling
Page 111 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
JSP Tag Libraries
resourceName
inherited from sling
nodeName
inherited from sling
logName
inherited from sling
resourceResolverName
inherited from sling
slingName
inherited from sling
componentContextName
specific to wcm
editContextName
specific to wcm
propertiesName
specific to wcm
pageManagerName
specific to wcm
currentPageName
specific to wcm
resourcePageName
specific to wcm
pagePropertiesName
specific to wcm
componentName
specific to wcm
designerName
specific to wcm
currentDesignName
specific to wcm
resourceDesignName
specific to wcm
currentStyleName
specific to wcm
Example:
<%@page session="false" contentType="text/html; charset=utf-8" %><%
%><%@ page import="com.day.cq.wcm.api.WCMMode" %><%
%><%@taglib prefix="cq" uri="http://www.day.com/taglibs/cq/1.0" %><%
%><cq:defineObjects/>
Note
When the /libs/wcm/global.jsp file is included in the script, the <cq:defineObjects /
> tag is automatically included.
Page 112 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
JSP Tag Libraries
21.1.1.4 <cq:requestURL>
The <cq:requestURL> tag writes the current request URL to the JspWriter. The two tags
<cq:addParam> and <cq:removeParam> may be used inside the body of this tag to modify the
current request URL before it is written.
It allows you to create links to the current page with varying parameters. For example, it enables
you to transform the request:
mypage.html?mode=view&query=something into mypage.html?query=something.
The use of addParam or removeParam only changes the occurence of the given parameter, all
other parameters are unaffected.
<cq:requestURL> does not have any attribute.
Examples:
<a href="<cq:requestURL><cq:removeParam name="language"/></cq:requestURL>">remove filter</
a>
<a title="filter results" href="<cq:requestURL><cq:addParam name="language"
value="${bucket.value}"/></cq:requestURL>">${label} (${bucket.count})</a>
21.1.1.5 <cq:addParam>
The <cq:addParam> tag adds a request parameter with the given name and value to the enclosing
<cq:requestURL> tag.
It has the following attributes:
name
name of the parameter to be added
value
value of the parameter to be added
Example:
<a title="filter results" href="<cq:requestURL><cq:addParam name="language"
value="${bucket.value}"/></cq:requestURL>">${label} (${bucket.count})</a>
21.1.1.6 <cq:removeParam>
The <cq:removeParam> tag removes a request parameter with the given name and value from
the enclosing <cq:requestURL> tag. If no value is provided all parameters with the given name are
removed.
It has the following attributes:
name
name of the parameter to be removed
Example:
<a href="<cq:requestURL><cq:removeParam name="language"/></cq:requestURL>">remove filter</
a>
21.1.2 Sling Tag Library
The Sling tag library contains helpful Sling functions.
Page 113 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
JSP Tag Libraries
When you use the Sling Tag Library in your script, the script must start with the following code:
<%@ taglib prefix="sling" uri="http://sling.apache.org/taglibs/sling/1.0" %>
Note
When the /libs/wcm/global.jsp file is included in the script, the sling taglib is
automatically declared.
21.1.2.1 <sling:include>
The <sling:include> tag includes a resource into the current page.
It has the following attributes:
flush
A boolean defining whether to flush the output before including the target.
resource
The resource object to be included in the current request processing. Either resource or path
must be specified. If both are specified, the resource takes precedence.
path
The path to the resource object to be included in the current request processing. If this path is
relative it is appended to the path of the current resource whose script is including the given
resource. Either resource or path must be specified. If both are specified, the resource takes
precedence.
resourceType
The resource type of the resource to be included. If the resource type is set, the path must be
the exact path to a resource object: in this case, adding parameters, selectors and extensions
to the path is not supported.
If the resource to be included is specified with the path attribute that cannot be resolved to a
resource, the tag may create a synthetic resource object out of the path and this resource type.
replaceSelectors
When dispatching, the selectors are replaced with the value of this attribute.
addSelectors
When dispatching, the value of this attribute is added to the selectors.
replaceSuffix
When dispatching, the suffix is replaced by the value of this attribute.
Note
The resolution of the resource and the script that are included with the <sling:include> tag
is the same as for a normal sling URL resolution. By default, the selectors, extension, etc.
from the current request are used for the included script as well. They can be modified
through the tag attributes: for example replaceSelectors="foo.bar" allows you to overwrite
the selectors.
Examples:
<div class="item"><sling:include path="<%= pathtoinclude %>"/></div>
<sling:include resource="<%= par %>"/>
<sling:include addSelectors="spool"/>
Page 114 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
JSP Tag Libraries
<sling:include resource="<%= par %>" resourceType="<%= newType %>"/>
<sling:include replaceSelectors="content" />
21.1.2.2 <sling:defineObjects>
The <sling:defineObjects> tag exposes the following, regularly used, scripting objects which can be
referenced by the developer:
slingRequest
SlingHttpServletRequest object, providing access to the HTTP request header information extends the standard HttpServletRequest - and provides access to Sling-specific things like
resource, path info, selector, etc.
slingResponse
SlingHttpServletResponse object, providing access for the HTTP response that is created by
the server. This is currently the same as the HttpServletResponse from which it extends.
request
The standard JSP request object which is a pure HttpServletRequest.
response
The standard JSP response object which is a pure HttpServletResponse.
resourceResolver
The current ResourceResolver object. It is the same as slingRequest.getResourceResolver().
sling
A SlingScriptHelper object, containing convenience methods for scripts, mainly sling.include('/
some/other/resource') for including the responses of other resources inside this response (eg.
embedding header html snippets) and sling.getService(foo.bar.Service.class) to retrieve OSGi
services available in Sling (Class notation depending on scripting language).
resource
the current Resource object to handle, depending on the URL of the request. It is the same as
slingRequest.getResource().
currentNode
If the current resource points to a JCR node (which is typically the case in Sling), this gives
direct access to the Node object. Otherwise this object is not defined.
log
Provides an SLF4J Logger for logging to the Sling log system from within scripts, eg.
log.info("Executing my script").
It has the following attributes:
requestName
responseName
resourceName
nodeName
logName
resourceResolverName
slingName
Page 115 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
JSP Tag Libraries
Example:
<%@page session="false" %><%
%><%@page import="com.day.cq.wcm.foundation.forms.ValidationHelper"%><%
%><%@taglib prefix="sling" uri="http://sling.apache.org/taglibs/sling/1.0" %><%
%><sling:defineObjects/>
Page 116 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG
Appendix A. Copyright, Licenses and
Formatting Conventions
For all copyright statements and license agreements see Copyright, Licenses and Disclaimers.
A.1 Formatting Conventions
The following tables detail formatting conventions used within this guide:
Table A.1. Formatting Conventions - Text
Style
Description
Example
Cross-reference
Cross-reference to external documents.
See the Microsoft Manual of
Style for Technical Publications.
GUI Item
User interface items.
Click Save.
Keyboard shortcut
Keyboard shortcuts.
Press Ctrl+A.
Mouse Button
Mouse buttons.
Secondary-mouse button
(usually the right-mouse
button).
Link
Link to anchor-points within the current
document and/or external sources.
http://www.day.com
Code
Example of programming code.
if (weather == sunny) smile;
User Input
Example of text, or commands, that you
type.
<Variable User
Input>
Example of variable text - you type the
actual value needed.
ls <cq-installation-dir>
[Optional
Parameter]
An optional parameter.
ls [<option>] [<filename>]
Computer Output
Logging and error messages.
ls *.xml
ls: cannot access
error.log:
Table A.2. Formatting Conventions - Actions
When you see this...
It means do this...
Ctrl+A
Hold down the Ctrl key, then press the A key.
Right-click
Press the right-mouse button (or the left-mouse button if your mouse
has been configured for left-handed use).
Drag
Hold down the left mouse button while moving the item, then release the
mouse button at the new location (or the right mouse button if your mouse
has been configured for left-handed use).
Page 117 of 117
CQ 5.1 WCM
Copyright 1993-2008 Day Management AG