Cq5 Guide Developer | Eclipse (Software) | Application Programming Interface

CQ5 WCM Developer's Guide

CQ5 WCM Developer's Guide

CQ 5.2 WCM Copyright 1993-2009 Day Management AG

Contents
1. Introduction ........................................................................................................................ 1 1.1. Introduction ............................................................................................................. 1 1.2. Purpose of this Document ........................................................................................ 1 1.3. Target Audience ...................................................................................................... 1 1.4. Prerequisites for development within CQ .................................................................. 1 2. CQ in-depth ....................................................................................................................... 2 2.1. JSR-170 and the JCR API ....................................................................................... 2 2.2. CQ DAM ................................................................................................................. 2 2.3. Widgets .................................................................................................................. 2 2.4. FileVault (source revision system) ............................................................................ 2 2.5. Workflow Engine ..................................................................................................... 2 2.6. Dispatcher ............................................................................................................... 2 2.7. Localization ............................................................................................................. 2 2.8. Sling Request Processing ........................................................................................ 3 2.8.1. Introduction to Sling ...................................................................................... 3 2.8.2. Sling is Content Centric ................................................................................ 3 2.8.3. RESTful Sling ............................................................................................... 3 2.8.4. URL Decomposition ...................................................................................... 3 2.8.5. From URL to Content and Scripts .................................................................. 4 2.8.6. Sling API ...................................................................................................... 8 2.8.7. Referencing existing elements using sling:include ........................................... 8 2.8.8. First Steps - an example for using Sling ......................................................... 8 2.9. OSGI ...................................................................................................................... 8 3. CQ5 WCM - Architecture and Concepts ............................................................................ 10 3.1. Development objects ............................................................................................. 10 3.2. Structure within the repository ................................................................................ 11 4. Development Tools ........................................................................................................... 12 4.1. Working with the CQ Development Environment (CQDE) ......................................... 12 4.1.1. Setting up CQDE ........................................................................................ 12 4.1.2. Configuring CQDE ...................................................................................... 12 4.2. How to Set Up the Development Environment with Eclipse ....................................... 12 4.2.1. Creating the Project Structure in CQ5 .......................................................... 13 4.2.2. Installing FileVault (VLT) ............................................................................. 13 4.2.3. Installing Eclipse ......................................................................................... 14 4.2.4. Creating the Project Structure in Eclipse ...................................................... 14 4.2.5. Scripting with Eclipse and CQ5 .................................................................... 19 4.2.6. Java Developing with Eclipse and CQ5 ........................................................ 20 4.2.7. Building collaborative and automated projects ............................................... 22 5. Designer .......................................................................................................................... 24 6. Templates ........................................................................................................................ 25 6.1. What are Templates? ............................................................................................ 25 6.2. Overview of templates ........................................................................................... 25 6.3. How Templates are structured ................................................................................ 25 6.3.1. The structure of a Template ........................................................................ 25 6.3.2. The content produced by a Template ........................................................... 27 6.4. Developing Page Templates ................................................................................... 28 6.4.1. Creating a new Template (based on an existing template) ............................. 28 6.5. Summary .............................................................................................................. 29 7. Components ..................................................................................................................... 30 7.1. What exactly is a Component? ............................................................................... 30 7.2. Default Components within CQ WCM ..................................................................... 30 7.3. Components and their structure .............................................................................. 31 7.3.1. Component definitions ................................................................................. 31 7.3.2. Component definitions and the content they create ....................................... 33 7.3.3. Component Hierarchy and Inheritance .......................................................... 35

Page iii of 106

CQ 5.2 WCM Copyright 1993-2009 Day Management AG

CQ5 WCM Developer's Guide

7.3.4. Summary .................................................................................................... 35 7.4. Developing Components ........................................................................................ 36 7.4.1. Developing a new component by adapting an existing component .................. 36 7.4.2. Adding a new component to the paragraph system (design mode) .................. 37 7.4.3. Extending the Text and Image Component - An Example .............................. 38 7.5. Further Development of Specific Components and Tools .......................................... 44 7.5.1. Developing the Bulk Editor .......................................................................... 44 7.6. Scripts .................................................................................................................. 52 7.6.1. global.jsp .................................................................................................... 52 7.6.2. JSP Tag Libraries ....................................................................................... 53 7.7. A closer look at a few of the foundation components... ............................................. 60 7.7.1. Top Navigation Component ......................................................................... 60 7.7.2. List Children Component ............................................................................. 62 7.7.3. Logo Component ........................................................................................ 63 7.7.4. Paragraph System ...................................................................................... 64 7.7.5. Image Component ...................................................................................... 64 7.7.6. Text & Image Component ........................................................................... 66 7.7.7. Search Component ..................................................................................... 67 8. Guidelines for Using Templates and Components .............................................................. 68 9. Java WCM API ................................................................................................................ 69 10. Multi Site Manager for Developers ................................................................................... 70 10.1. MSM in the Repository ........................................................................................ 70 10.1.1. MSM-specific Nodes, Node Types, and Properties ...................................... 70 10.1.2. MSM mechanisms in the repository ............................................................ 73 10.2. Extending MSM Functionalities ............................................................................. 74 10.2.1. How to extend synchronization actions ....................................................... 74 10.2.2. How to define the properties and the nodes that are copied to the Live Copy .................................................................................................................... 83 10.2.3. How to remove the "Chapters" step in the "Create Site" wizard ..................... 84 11. How to Create a Fully Featured Internet Website ............................................................. 85 12. DAM Media Handlers ..................................................................................................... 86 12.1. Default Media Handlers ........................................................................................ 86 12.2. Using Media Handlers in Workflows to perform tasks on Assets .............................. 87 12.3. Disabling/Enabling a Media Handler ...................................................................... 90 12.4. Creating a new Media Handler ............................................................................. 91 12.4.1. Important Classes and Interfaces ............................................................... 91 12.4.2. Example: create a specific Text Handler ..................................................... 91 13. Data Modelling ............................................................................................................... 98 13.1. Data Modeling - David Nuescheler's Model ........................................................... 98 13.1.1. Source ...................................................................................................... 98 13.1.2. Introduction from David ............................................................................. 98 13.1.3. Seven Simple Rules .................................................................................. 98 A. Keyboard Shortcuts ........................................................................................................ 104 B. Security Checklist ........................................................................................................... 105 B.1. Use the user session, not the administrative session ............................................. 105 B.2. Check for Cross-Site Scripting (XSS) .................................................................... 105 C. Copyright, Licenses and Formatting Conventions ............................................................. 106 C.1. Formatting Conventions ....................................................................................... 106

Page iv of 106

CQ 5.2 WCM Copyright 1993-2009 Day Management AG

1 Introduction
1.1 Introduction
Day's CQ5 platform allows you to build compelling content-centric applications that combine Web Content Management, Workflow Management, Digital Asset Management and Social Collaboration. The product has been completely redesigned from Communiqué 4, allowing Day to use new architecture and technologies, thus increasing functionality while reducing complexity. Extensive use of standards helps ensure long-term stability.

1.2 Purpose of this Document
To provide the information necessary for developing new components, applications and other elements within CQ. Warning This document is not a programming guide; it is assumed that you have the necessary skills for writing code in the appropriate language. Important This document is designed to be read in conjunction with the CQ5 WCM Architect Guide.

1.3 Target Audience
• Developers

1.4 Prerequisites for development within CQ
For development within CQ, you need the following skills: • Basic knowledge of web application techniques, including: • the request -response (XMLHttpRequest / XMLHttpResponse) cycle • HTML • CSS • JavaScript • Working knowledge of CRX; including the Content Explorer • Basic knowledge of JSP (JavaServer Pages), with the ability to understand and modify simple JSP examples

Page 1 of 106

CQ 5.2 WCM Copyright 1993-2009 Day Management AG

2 CQ in-depth
2.1 JSR-170 and the JCR API
JSR 170 is the Java Specification Request for the Content Repository for JavaTM technology API. Specification lead is held by Day Software AG. The JCR API package, javax.jcr.* is used for the direct access and manipulation of repository content. CRX is Day's proprietary implementation of the JCR. Apache Jackrabbit is an open source, fully conforming, implementation of this API.

2.2 CQ DAM
CQ DAM (Communiqué Digital Asset Management) is used to centrally manage all digital media files and essential metadata information.

2.3 Widgets
CQ WCM has been developed using the ExtJS library of widgets.

2.4 FileVault (source revision system)
FileVault provides your JCR repository with file system mapping and version control. It can be used to manage CQ development projects with full support for storing and versioning project code, content, configurations and so on, in standard version control systems (for example, Subversion).

2.5 Workflow Engine
Your content is often subject to organizational processes, including steps such as approval and sign-off by various participants. These processes can be represented as workflows, defined within CQ, then applied to the appropriate content pages or digital assets as required. The Workflow Engine is used to manage the implementation of your workflows, and their subsequent application to your content. More information on how to use Workflows is given in the Chapter 8, .

2.6 Dispatcher
The Dispatcher is Day's tool for both caching and/or load balancing. Further information can be found under Tools - the Dispatcher.

2.7 Localization
Localization is at the core of CQ5. It provides support for adapting applications, created using the CQ5 platform, into different languages and regional configurations . While processing the request, the Locale is extracted. This is then used to reference a language code, and optionally a country code, which can be used for controlling either the specific content or format of certain output. Localization will be used throughout CQ5 - wherever reasonable. One notable exception is the system log information of CQ5 itself, this is never localized and always in English.

Page 2 of 106

CQ 5.2 WCM Copyright 1993-2009 Day Management AG

8. processing is driven by the URL of the user request. This means that processing is focused on the content as each (HTTP) request is mapped onto content in the form of a JCR resource (a repository node): • the first target is the resource (JCR node) holding the content • secondly.3 RESTful Sling Due to the content-centric philosophy. Sling has since been contributed to the Apache Software Foundation . such as Apache Jackrabbit. Sling implements a REST-oriented server and thus features a new concept in web application frameworks. URL Decomposition protocol http:// host myhost content path tools/spy selector(s) . Instead the main consideration is whether the URL resolves to a content object for which a script can then be found to perform the rendering.html/a/b?x=12 We can break it down into its composite parts: Table 2.CQ in-depth 2.2 WCM Copyright 1993-2009 Day Management AG .printable. DB schema. • this is now reduced to: URL = resource = JCR structure 2. The advantages are: • very RESTful. This provides excellent support for web content authors to build pages which are easily customized to their requirements.2 Sling is Content Centric Sling is content-centric.8. or script. 2.4 URL Decomposition In Sling. In particular.8 Sling Request Processing 2. a Web application framework based on REST principles that provides easy development of content-oriented applications.a4. extension html / suffix a/b ? param(s) x=12 Page 3 of 106 CQ 5. The advantages of this flexibility are apparent in applications with a wide range of different content elements.printable. Sling started as an internal project of Day Management AG and is included in the installation of CQ5. business objects.further information can be found at Apache. or Day's CRX. selectors and/or the extension) 2.8. To do this.1 Introduction to Sling CQ5 is built using Sling. and therefore also CQ5. This defines the content to be displayed by the appropriate scripts.a4. If we analyze the following URL: http://myhost/tools/spy. Using Sling. or when you need pages that can be easily customized.g. the type of content to be rendered is not the first processing consideration.1. resources and representations are correctly modelled inside the server • removes one or more data models • previously the following were needed: URL structure. as its data store. the representation.8. information is extracted from the URL. is located from the resource properties in combination with certain parts of the request (e. when implementing a Web Content Management system such as CQ WCM. Sling uses a JCR repository.

extension Content format.5 From URL to Content and Scripts Using these principles: • the mapping uses the content path extracted from the request to locate the resource • when the appropriate resource is located.html.8.CQ in-depth protocol HTTP. suffix Can be used to specify additional information. Is used in combination with the extension. content path Path specifying the content to be rendered. which will be discussed in more detail in the following sections. 2. param(s) Any parameters required for dynamic content.1. host Name of the website. also specifies the script to be used for rendering. the sling resource type is extracted. Figure 2. How Sling locates the content and scripts Therefore: CQ 5. in this example they translate to tools/spy.2 WCM Copyright 1993-2009 Day Management AG Page 4 of 106 . selector(s) Used for alternative methods of rendering the content. and used to locate the script to be used for rendering the content The figure below illustrates the mechanism used. in this example a printer-friendly version in A4 format.

All Sling scripts are stored in subfolders of either /apps or /libs. ./content/ corporate/jobs/developer • if no node is found then Sling will return the http code 404 (Not Found). e.g.ecma: ECMAScript (JavaScript) Pages (server-side execution) • .1 Mapping requests to resources The request is broken down and the necessary information extracted.8. e.esp. Page 5 of 106 CQ 5. which will be searched in this order. the sling resource type is extracted.2 WCM Copyright 1993-2009 Day Management AG .esp (see below) • various script engines are supported: • . POST) is required. This is a path. the extension is dropped and the search repeated.CQ in-depth • DO NOT specify which data entities to access in your scripts (as an SQL statement in a PHP script would do) • DO specify which script renders a certain entity (by setting the sling:resourceType property in the JCR node) 2. but this is an advanced feature. . to a configuration parameter Note Relative paths are recommended by Day as they increase portability.js: ECMAScript / JavaScript (client-side execution) The list of script engines supported by the given instance of CQ are listed on the Felix Management Console (http://localhost:4502/system/console/scriptengines ).POST.jsp: Java Server Pages (server-side execution) • . 2.2 Locating the script When the appropriate resource (content node) is located.java: Java Servlet Compiler (server-side execution) • .jst: JavaScript templates (client-side execution) • .g. The path specified by the sling:resourceType can be either: • absolute • relative. The repository is searched for the requested resource (content node): • first Sling checks whether a node exists at the location specified in the request..5.html • if no node is found. Note Sling also allows things other than JCR nodes to be resources.5. A few other points to note are: • when the Method (GET. it will be specified in uppercase as according to the HTTP specification e./ content/corporate/jobs/developer.g. which locates the script to be used for rendering the content. jobs.8.. .

HTML (.pdf.pdf The script will be /apps/hr/jobs/jobs. jobs. JRuby.a4.res.. the selector is added to the script name.esp.CQ in-depth Additionally. the method name must be uppercase) POST will be used in the script name. • If no script is found at all then the default script will be used. the suffix is added to the script name. jobs.esp. is to spool the resource (where possible). • URLs in other formats. If multiple scripts apply for a given request. Freemarker). the script with the best match is selected. • URLs with selectors Selectors can be used to display the same content in an alternative format. The script will be /apps/hr/jobs/POST. For example a printer friendly version. Groovy. an rss feed or a summary. not ending with . as in ./content/corporate/jobs/developer.html would generate a search in /apps/content/corporate/jobs/.html (default request types. consider a request to access the resource /content/corporate/jobs/ developer. Apache Sling supports integration with other popular scripting engines (e. if the sling:resourceType is hr/jobs then for: • GET/HEAD requests.html The script will be /apps/hr/jobs/jobs. respectively. and URLs ending in . and provides a way of integrating new scripting engines. the last section of the sling:resourceType forms the file name. or requests without a request extension. The more specific a match is.esp./content/ corporate/jobs/developer./content/corporate/jobs/developer. regardless of any request extension or method name match.esp CQ 5. the better it is. the script for . default format) The script will be /apps/hr/jobs/jobs. The default rendition is currently supported as plain text (.esp 2.g. the more selector matches the better.json)..esp. The default rendition for the extension . • For http error handling (codes 404 or 500) Sling will look for a script at /libs/sling/ servlet/errorhandler/404.html For example . • POST requests (all request types excluding GET/HEAD.html) and JSON (.esp. all of which will list the node's properties (suitably formatted).html of type sling:resourceType="hr/jobs". • the primary node type will be used. If we look at a printer friendly version where the selector could be print.. Assuming we have the following list of scripts in the correct location: 1.GET.print. Using the above example..esp.txt).print. For example. or 500. For example.2 WCM Copyright 1993-2009 Day Management AG Page 6 of 106 .print. in other words. • If no sling:resourceType has been defined then: • the content path will be used to search for an appropriate script (if the path based ResourceTypeProvider is active).

esp 7.esp 4. a.print.print.print. For example: • / • a • b • sling:resourceSuperType = a • c • sling:resourceSuperType = b • x • sling:resourceType = c • y • sling:resourceType = c • sling:resourceSuperType = a The type hierarchy of /x is [ c.CQ in-depth 3.GET. jobs.GET.html.esp 5.(8) . b.html.(4) . 2. <default> ] while for /y the hierarchy is [ c. In addition to the resource types (primarily defined by the sling:resourceType property) there is also the resource super type.html. jobs.esp 10.esp 8. a.(2) . because it matches more selectors even though (8) has a method name and extension match where (6) does not. jobs.a4.(3) .(9) . Page 7 of 106 CQ 5. by the sling:resourceSuperType property of the resource. jobs.(6) .print. jobs.(7) .jobs. Note (6) is a better match than (8).esp Then the order of preference would be (10) .html.a4.print. by the sling:resourceSuperType property of the node to which the sling:resourceType points.esp 9.print.GET.(1).a4. The advantage of resource super types is that they may form a hierarchy of resources where the default resource type sling/servlet/default (used by the default servlets) is effectively the root.html. These super types are also considered when trying to find a script. jobs. This is generally indicated by the sling:resourceSuperType property. jobs.html. <default> ] because /y has the slingresourceSuperType property whereas /x does not and therefore its supertype is taken from its resource type.2 WCM Copyright 1993-2009 Day Management AG .esp 6. The resource super type of a resource may be defined in two ways: 1.(5) .

More complex scripts (aggregating scripts) might need to access multiple resources (for example navigation.CQ in-depth 2. PUT. OSGi containers allow you to break your application into individual modules (are jar files with additional meta information and called bundles in OSGi terminology) and manage the cross-dependencies between them with: • services implemented within the container • a contract between the container and your application These services and contracts provide an architecture which enables individual elements to dynamically discover each other for collaboration. and tag libraries. Note Full information on OSGi technology can be found at the OSGi Alliance Technology Overview. you would mix resources and representations.8 First Steps .9 OSGI OSGi defines an architecture for developing and deploying modular applications and libraries (it is also known as the Dynamic Module System for Java). scripts cannot be called directly as this would break the strict concept of a REST server.7 Referencing existing elements using sling:include A final consideration is the need to reference existing elements within the scripts. as in the following statement which references an existing definition for rendering images: %><sling:include resourceType="geometrixx/components/image/img"/><% 2.8. footer.without requiring restarts.*. An OSGi framework then offers you dynamic loading/unloading.8. including: • POST. 2. so the framework (Sling) no longer knows about it.8. This will effectively include the definition of the referenced resource. elements of a list) and do so by including the resource.1 Sling Scripts cannot be called directly Within Sling.2 WCM Copyright 1993-2009 Day Management AG Page 8 of 106 . DELETE which are handled with a sling default implementation • the POST.2.apache.6 Sling API This uses the Sling API package. 2. CQ 5.5.com/.sling. configuration and control of these bundles .8. of prime importance for large-scale development 2.day.an example for using Sling An introduction the first steps of developing with Sling (and CRX) can be seen on http:// dev. org.js script in your sling:resourceType location • your code architecture is no longer as clean nor as clearly structured as it should be. sidebar. To do this you can use the sling:include("/<path>/<resource>") command. If you call the representation (the script) directly you hide the resource inside your script. Thus you lose certain features: • automatic handling of http methods other than GET.

their Basic Education page holds a collection of presentations and tutorials.CQ in-depth In particular. etc) about the specific bundles Page 9 of 106 CQ 5. location. symbolic name. Sling. They are both collections of OSGi bundles running within an OSGi framework. version.2 WCM Copyright 1993-2009 Day Management AG .g. This enables you to perform the following actions on any of the packages within your installation: • install • start • stop • update • uninstall • see the current status • access more detailed information (e. uses the Apache Felix implementation of OSGI (Open Services Gateway initiative). and therefore CQ5. This architecture allows you to extend Sling with application specific modules.

Dialog A dialog is a special type of widget. The new page is then created by copying this template. CQ object definitions. for example. WCM is the Web Content Management solution within CQ. Nodes define the content structure. everything is stored in the repository. Note In CQ.3 CQ5 WCM .2 WCM Copyright 1993-2009 Day Management AG Page 10 of 106 . and able to communicate with other components. 3. the component rendering it is called a Top-Level Component or a Pagecomponent. The property sling:resourceType of this node points to the Sling rendering component to be used. a navigation component will display information about multiple resources. Dialogs are also used for editing metadata. Widget In CQ all user input is managed by widgets. To edit content. CQ uses dialogs defined by the application developer. The definition of a component includes:. These combine a series of widgets to present the user with all fields and actions necessary to edit the related content. is also called a resource in the Sling environment. These are often used to control the editing of a piece of content. which gives an overview of the architecture and related concepts within CQ5. • the code used to render the content • a dialog for the user input and the configuration of the resulting content. Within CQ a component is often used to render the content of a resource. Template A template is the blueprint for a specific type of page. CQ 5. nor be linked to a specific resource. Component A software component is a system element offering a predefined service or event. When creating a page in the siteadmin the user has to select a template. When the resource is a page. which is a JCR name. This section should be read in conjunction with the CQ5 WCM Architect Guide. Content nodes drive the rendering. Dialogs are built by combining Widgets. rendering scripts and other data. and by various administrative tools. However.1 Development objects The following are of interest at the development level: Node (and their properties) Nodes and their properties store content. Sling gets the content node from the incoming request. a component does not have to render content. and their properties store the actual content and metadata. A node.Architecture and Concepts CQ5 is Day's suite of products based on a standard JCR repository.

• /etc Initialization and configuration information. Changes are needed when you are developing. Page 11 of 106 CQ 5.CQ5 WCM .2 Structure within the repository The following list gives an overview of the structure you will see within the repository. includes component definitions specific to your website. A page has a hierarchy node of type cq:Page and a content node of type cq:PageContent. Page A page is an 'instance' of a template. Page Component (Top-Level Component) The component to be used to render the page. or the files within it. but without any actual content.2 WCM Copyright 1993-2009 Day Management AG . For configuration and other changes copy the item in libs/ to apps/ and make any changes within apps/. but you should take care that you fully understand the implications of any changes you make. • /tmp Temporary working area. • /libs Libraries and definitions that belong to the core of CQ WCM. The content defines how it is rendered as CQ is content-centric. • /var Files that change and are updated by the system.Architecture and Concepts A template is a hierarchy of nodes that has the same structure as the page to be created. 3. such as audit logs. should be made with care. The property sling:resourceType of the content node points to the Page Component used for rendering the page. statistics. • /apps Application related. • /content Content created for your website. Warning Changes to this structure. Warning You must not change anything in the libs/ path. event-handling. It defines the page component used to render the page and the default content (primary toplevel content). • /home User and Group information.

project. if omitted root is mounted) + cqdeVersions (optional multivalue string property defining the CQDE5 versions that can use this profile) + cqdeOS (optional multivalue string property defining the operating systems that can use this profile) 4. 5.4 Development Tools 4. Double-click the executable.xslt (mandatory template for generating . Enter your username and password. It then describes how to integrate logic into the project through Java coding and JSP scripting.etc . Ensure that CQ is installed and running. proceed as follows: 1. 4. including version.classpath files) + mountPaths (optional multivalue string property defining the paths that should be mounted. It is custom-built specifically for CQ and therefore recommended by Day.[Name of Profile] (for example. 2.1 Setting up CQDE To set up CQDE. another host. it points to open source software to enable collaborative and automated developing. as well as additional settings.project files) .1. Lastly. .2 WCM Copyright 1993-2009 Day Management AG Page 12 of 106 . Enter the location of your CQ5 installation. This is the location where CQDE can find the CRX WebDAV server. The profile folder contains XSLT templates for generating CQDE project and classpath files. Extract the package to your required installation location. When CQDE is started.xml. it sends information about the users environment to CQ5.the default profile that is distributed with CQ5) . 3.1. Click OK. 4. Download the CQDE package. where each profile must have its own folder. 4. OS and a profile ID. default . port or context path) you also need to update the CRX server endpoint. 6. The standard profile is default.xml.xslt (mandatory template for generating . This can be done in the configuration section of the CQDE servlet which is available on the Felix Management Console (http://localhost:4502/system/console/ configMgr ).1 Working with the CQ Development Environment (CQDE) The CQ5 IDE (CQDE) provides a development platform for CQ5 applications.2 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. CQDE is built on Eclipse RCP and EFS and comes as a set of Eclipse plugins. 7. for example http://localhost:4502 for CQ5 Quickstart. CQ 5. CQ5 stores this information under /etc/cqde/profiles.2 Configuring CQDE If the location of your installation is different from above (for example.cqde .profiles .classpath.

• Eclipse to edit the project source on your local file system. create the nt:folder myApp. create the nt:folder components. In the current context. 4. Add <cq-installation-dir>/crx-quickstart/opt/filevault/vault-cli<version>/bin to your environment PATH so that the command files vlt or vlt. • Apache Maven to run local snapshot builds. 3. CQ5 runs locally on port 4502. The local development environment involves: • A CQ5 installation that will act as your local environment. • Name: myApp.2.Generic Procedure” for the detailed procedure. The build is available in both tgz and zip formats. Under the myApp folder.1 Creating the Project Structure in CQ5 This section describes the creation of a simple project structure in CQ5: 1. 2. 3. Under the /apps folder. In your browser. If already installed then ensure it is running and connect. Under the myApp folder. • Template: Design Page Template. as well as configuration options for flexible representation of the project content. create the nt:folder install. For example. 2.Development Tools The setup described here is an alternative among others and may vary from project to project.2 Installing FileVault (VLT) FileVault (VLT) is a tool developed by Day that maps the content of a CRX instance to your file system. 4. To install VLT. 3. • CRX Explorer within the CQ5 instance to create and edit nodes and properties within the CRX repository.bat are accessed as appropriate. check out and management operations. In your file system. Please refer to the section called “Installing a CQ WCM Instance . 2. • FileVault (VLT). Install CQ5 on your machine.2/bin CQ 5. Under the myApp folder. Under designs.2 WCM Copyright 1993-2009 Day Management AG Page 13 of 106 .1. create the design page of your application: • Title: My Application Design Page. Extract the archive.2. create the project structure: 1. In the CRX Explorer. The VLT tool has similar functionalities to those of an SVN client. 4. create the nt:folder templates. follow the steps: 1. <cq-installation-dir>/crx-quickstart/ opt/filevault/vault-cli-1. providing normal check in. go to <cq-installation-dir>/crx-quickstart/opt/filevault. navigate to the Tools tab. a Day developed utility that maps the CRX repository to your file system.

3 Installing Eclipse Eclipse is open source software used to edit the project source locally on your file system.exe (or eclipse.select the Eclipse IDE for Java EE Developers option.4 Creating the Project Structure in Eclipse In this section.2. 3. Create a new workspace for your project and name it myApp.2. CQ 5. Make sure it displays the following help screen: 4.2 WCM Copyright 1993-2009 Day Management AG Page 14 of 106 . Download Eclipse . For example C:\Program Files\Eclipse\.Development Tools 4. Navigate to the directory into which you extracted the contents of the Eclipse installation zip file. Start Eclipse: a. b. 4. Install Eclipse: extract from the downloaded zip file to your destination directory.app) to start Eclipse. Disable Maven SCM handler for Subclipse (Optional) and Maven Integration for AJDT (Optional). In this section. Double-click on eclipse. 4. Open a command line shell and execute vlt --help. Install the Maven plugin (m2) from Sonatype. you will install Eclipse and a Maven plugin which embeds the Maven functionality within Eclipse: 1. Apache Maven is also open source software. 5. you will create two Maven projects: • one called UI (after User Interface) which contains the CQ5 project structure with the JSP scripts. 6. used to run local snapshot builds: it compiles Java code and stores the compiled code in a jar file. 2. After installation it is recommended to restart Eclipse.

5: 1.cq5.xml file which defines the content that will be exported by VLT: 1. 2.5: • Compiler compliance level • Generated . then click Next. 4. Define the Maven project: • Group Id: com. 4. In the dialog window. select New. create the filter. 4. 4. The compiled code is stored in a jar file.2. then Other.0" encoding="UTF-8"?> Page 15 of 106 CQ 5. Select Java Compiler and set following properties to 1. Create the UI Maven project: 1.xml. Click OK. The advantage of such a structure is that it adds modularity and autonomy to the logic of your application because each jar file (bundle) can be managed separately.class files compatibility • Source compatibility 3. click Yes.1 Create the UI Maven Project To create the UI Maven project. Right-click the ui project. 3. navigate to ui/scr/main and create the content folder. In Eclipse. Click Finish. 4. 3. follow the steps: 1. In the Menu bar. Under META-INF. 2. expand the Maven folder. select Maven Project and click Next. In Eclipse open the Workbench.. select Properties.Development Tools • the other called Core which contains the Java code (source and compiled).xml: <?xml version="1. Under content. Check the Create a simple project box and the Use default Workspace locations box. Set the Java Compiler to version 1. Create the filter. In the dialog. 2.myapp • Artifact Id: ui • Name: CQ5 MyApp UI • Description: This is the UI module 5. In filter. . 2. Under vault. create the META-INF folder. 5. 3.2 WCM Copyright 1993-2009 Day Management AG ..4. copy the following code to filter.day.xml file. create the vault folder. click File.

xml in <eclipse>/ <workspace>/myApp/ui/src/main/content/META-INF/vault. 5. Click Finish. select New. Check out the CQ5 content into your ui project with VLT: 1. 2. This maps to the CRX root (/).Development Tools <!-Defines which repository items are generally included --> <workspaceFilter vesion="1.xml: • apps/myApp • etc/designs/myApp It also creates two files. This folder can be created anywhere. 2. Click OK. then specify <eclipse>/<workspace>/myApp/ui/src/main/ content/jcr_root/apps. create a CQ5 libraries folder called cq5libs. click Advanced and check the Link to folder in the file system box. then Folder.2 WCM Copyright 1993-2009 Day Management AG . create a link to the apps folder under ui: 1. methods and objects used in the JSP scripts. In this example. Click Browse. you will reference the following libraries: • libs/cq/install stored in the CQ5 server • libs/sling/install stored in the CQ5 server • 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. 7. navigate to the directory holding your Eclipse workspace <eclipse>/<workspace>/myApp/ui/src/main/content. 3. 4.xml and settings. Save the changes. Right-click ui. To enable Eclipse to identify the Java classes. 6. 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. In your file system.0"> <filter root="/apps/myApp" /> <filter root="/etc/designs/myApp" /> </workspaceFilter> 6. In the dialog window. From the system command line. as defined in filter. Page 16 of 106 CQ 5. These are used by VLT. 5. export the needed Java libraries from the CQ5 server to your file system and reference them in the ui project. config. Under jcr_root the following files and folders are created. To enable Eclipse to map the file paths used in the JSP scripts.

xml file under core./cq5libs/wcm and execute vlt co http:// localhost:4502/crx /libs/wcm/install . Click OK. Under cq5libs.. 4.2. Click Add External JARS. navigate to <cq-installation-dir>/crxquickstart/server/lib/container./cq5libs/cq/jcr_root. 3.. 6... right-click the ui project.2 WCM Copyright 1993-2009 Day Management AG Page 17 of 106 . sling and wcm. select Maven Project and click Next. create the Core Maven project: 1.2 Create the Core Maven Project To create the Core Maven project. select all the jar files and click Open. click File. expand the Maven folder.. 2.. Define the Maven project: • Group Id: com. 8. Click Add External JARS.. then click Next.day.4. 2.cq5.Development Tools 2.. 11.. navigate to . 7. From the system command line go to . Open the pom./cq5libs/sling/jcr_root.... then Configure Build Path.../cq5libs/sling and execute vlt co http:// localhost:4502/crx /libs/sling/install . 5. 4. In the dialog select the Libraries tab. In the dialog. Check the Create a simple project box and the Use default Workspace locations box.. follow the steps: 1. Copy-paste following code before the </project> tag: CQ 5.. . Add the necessary plugins and dependencies to the core project: 1. to export the libraries stored under /libs/wcm/ install from the CQ5 server. In Eclipse. Click Finish.. In Eclipse. select all the jar files and click Open... navigate to . to export the libraries stored under /libs/ sling/install from the CQ5 server. select Build Path. From the system command line go to .. Click Add External JARS.. 2. In the Menu bar. Click Add External JARS. then Other. select all the jar files and click Open.myapp • Artifact Id: core • Name: CQ5 MyApp Core • Description: This is the Core module 5. 9.. 4.. From the system command line go to .. create the folders: cq./cq5libs/wcm/jcr_root. 10../cq5libs/cq and execute vlt co http:// localhost:4502/crx /libs/cq/install . 3.. to export the libraries stored under /libs/cq/ install from the CQ5 server. select New. navigate to . select all the jar files and click Open.

2 WCM Copyright 1993-2009 Day Management AG .day.maven.apache.cq</groupId> <artifactId>cq-commons</artifactId> <version>5.1.4.wcm</groupId> <artifactId>cq-wcm-api</artifactId> <version>5. From the system command line go to <your-user-dir>/.18 (create the folders if they don't exist) and execute vlt co http://localhost:4502/crx /libs/cq/install/cq-commons-5.jar .m2/repository/com/ day/cq/wcm/cq-wcm-api/5.0.sling.18</version> </dependency> <dependency> <groupId>org.Development Tools <packaging>bundle</packaging> <build> <plugins> <plugin> <groupId>org.20. to export the library from the CQ5 server.xml (cq-wcm-api. Save the changes.1. 2.apache. to export the library from the CQ5 server.version} </Export-Package> </instructions> </configuration> </plugin> </plugins> </build> <dependencies> <dependency> <groupId>com.5</source> <target>1.3-incubator-R708951</version> </dependency> </dependencies> 3. Deploy the CQ5 specific artifacts as defined in the pom.1.5</target> </configuration> </plugin> <plugin> <groupId>org.day.api</artifactId> <version>2.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.*.20</version> </dependency> <dependency> <groupId>com. From the system command line go to <your-user-dir>/.1.cq5.api) to the local Maven repository: 1.sling</groupId> <artifactId>org. cq-commons and org.cq.version= ${pom. Page 18 of 106 CQ 5.apache.20 (create the folders if they don't exist) and execute vlt co http://localhost:4502/crx /libs/wcm/install/cq-wcm-api-5.18.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <version>1.1. 3.jar .day.3</version> <extensions>true</extensions> <configuration> <instructions> <Export-Package> com.apache.myapp.sling.1.m2/repository/com/ day/cq/cq-commons/5.apache.

sling. From the system command line go to <your-user-dir>/.2 WCM Copyright 1993-2009 Day Management AG . The following example illustrates this process: 1. to export the library from the CQ5 server. Click OK.3-incubator-R708951 (create the folders if they don't exist) and execute vlt co http://localhost:4502/crx /libs/sling/ install/org. Under core. Page 19 of 106 CQ 5. 2.g.myapp and click Finish. 5.5: • Compiler compliance level • Generated .apache.api/2.3-incubator-R708951. • Check in the changes from the file system into the repository with VLT. create a new template: Name: contentpage Type: cq:Template Under the contentpage Node.myapp that will contain the Java classes under core/ src/main/java: 1.day. • Update the changes with VLT (export from the repository to your file system) . under /apps/myApp/templates. edit the Property sling:resourceType and add as Value: myApp/components/contentpage 2.cq5.api-2.apache. Name it com.cq5. edit the Property jcr:title and add as Value: MyApp Content Page Template Under the contentpage Node.5 Scripting with Eclipse and CQ5 When editing UI code use the following sequence: • Create a template and a component with the CRX Explorer. 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. In the dialog window.jar . 4. Create the package com. add a new Node: Name: jcr:content Type: cq:PageContent Under the jcr:content Node.class files compatibility • Source compatibility 3. click Yes. Right-click the core project.m2/repository/org/ apache/sling/org. Select Java Compiler and set following properties to 1. 2.0.5: 1.sling. Set the Java Compiler to version 1.2. right-click src/main/java.day. • Create a component script (JSP) with Eclipse. 4. select New. In the CRX Explorer. 4. select Properties. Create a new template with the CRX Explorer: 1.0. using Apache Archiva).Development Tools 3. then Package. 3. 4.

Execute: vlt ci to commit the contentpage. Execute: vlt st --show-update to see the changes made on the repository. CQ 5.2 WCM Copyright 1993-2009 Day Management AG Page 20 of 106 . 2.jsp file to VLT control. 3. Save the changes. In the dialog. Right-click contentpage. add a new Property: Name: personName Value: myName 2. Copy the following code into contentpage. then File. 4. 2.Development Tools 5. Tip It is possible to define the VLT commands as External Tools in Eclipse. Execute: vlt st to see the changes made on the file system. Create a new component with the CRX Explorer: • In the CRX Explorer. 3. In Eclipse. Create the component script (JSP) with Eclipse: 1.jsp: This is the contentpage component. From the system command line navigate to <eclipse>/<workspace>/myApp/ui/ src/main/content/jcr_root. 6.6 Java Developing with Eclipse and CQ5 When editing Core code use the following sequence: • Create a Java class. Use VLT to update the changes made from your repository to your file system. From the system command line navigate to <eclipse>/<workspace>/myApp/ui/ src/main/content/jcr_root. 4. navigate to ui/src/main/content/jcr_root/apps/myApp/ components/contentpage. Under the jcr:content Node. With VLT check in the changes from the file system into the repository: 1.jsp and click Finish. 2. Execute: vlt up to update the changes from the repository to your file system. 5. name the file contentpage. From CQ5 create a page based on this template. select New. create a new component: Name: contentpage Type: cq:Component 3. This enables you to run the VLT commands from within Eclipse. 4. 4.jsp file to the repository.2. 5.jsp to add the contentpage. Execute: vlt add apps/myApp/components/contentpage/contentpage. and therefore Eclipse: 1. Open the page to make sure it displays the following message: This is the contentpage component. 3. under /apps/myApp/components.

1SNAPSHOT. Click Add JARS. } } 4.day. • Use VLT to deploy the jar file (with the compiled class) from the file system into the repository. public HelloPerson(Page personPage) { this. select Run As.0. select the core-0. under core/src/main/java. Compile the Java class: 1. Save the changes.java replace the existing code with the following: package com. In Eclipse.toString().jar (containing the compiled class) is created under core/target. name the Java Class HelloPerson and click Finish. then Maven Install. In the dialog select the Libraries tab.getProperties().myapp. • Reference the jar file in the ui library. 2. public class HelloPerson { private Page personPage. Make sure that a new file core-0. 2. In HelloPerson. 3.api. • Use VLT to check these changes to the JSP script (in the file system) into the repository. Eclipse creates and opens the file HelloPerson. right-click the com. In Eclipse.wcm. 2. Reference this jar file in the ui library to enable the code completion when accessing this class with the JSP script: 1. then Configure Build Path.cq.Page.get(PN_PERSON_NAME).0. Embed the Java Class logic into the JSP script: CQ 5.. and navigate to core/target.myapp package.java.1-SNAPSHOT.cq5. • Embed the Java Class logic into the JSP script. return personName != null ? personName : "--empty--". public static final String PN_PERSON_NAME = "personName". 3. In the dialog window. Right-click the core project. Create the Java class: 1. 2. Click OK to close the dialog.2 WCM Copyright 1993-2009 Day Management AG Page 21 of 106 ..Development Tools • Compile the Java class.day.jar file and click OK. } public String getHelloMessage() { String personName = personPage. select Build Path. The following example illustrates this process: 1. right-click the ui project.personPage = personPage.cq5. select New. import com. then Class. 3. 4.day.

jar file.day.Development Tools 1. 6.0. 3. In Eclipse. open the JSP script contentpage. 5.myapp.1-SNAPSHOT.1-SNAPSHOT. String msg = hello.0. In your browser.2. Replace the existing code with the following: <%@ page import="com. Execute: vlt ci to commit the jar file to the repository.jsp in ui/src/main/content/ jcr_root/apps/myApp/components/contentpage. • Apache Archiva to centrally store and retrieve the project libraries. change the value myName and make sure that the new value is displayed when you refresh the page. Execute: vlt ci to commit the modified contentpage.cq5. From the system command line navigate to <eclipse>/<workspace>/myApp/ui/ src/main/content/jcr_root. 8. 2. 4. In Eclipse navigate to ui/scr/main/content/jcr_root/apps/myapp/install and paste the copied file. From the system command line navigate to <eclipse>/<workspace>/myApp/ui/ src/main/content/jcr_root. under core/target. 2. Execute: vlt st to see the changes made on the file system. Deploy the jar file containing the compiled class from the file system into the repository with VLT: 1. 2.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. With VTL check in the changes to the JSP script from the file system to the repository: 1. myName. This is the contentpage component. <%= msg %>. 6.getHelloMessage().jsp file to the repository. 3.jsp"%> <% HelloPerson hello = new HelloPerson(currentPage).HelloPerson" %> <%@include file="/libs/wcm/global.2 WCM Copyright 1993-2009 Day Management AG . In CRX Explorer.</br></br> This is the contenpage component. copy the core-0. Save the changes.jar to add the jar file to VLT control. Page 22 of 106 CQ 5. 7. In Eclipse. 3. 4. 5. Execute: vlt st to see the changes made on the file system. %> Hello. Execute: vlt add apps/myApp/install/core-0. refresh the CQ5 page to make sure it displays following message: Hello.

The setup of Continuum is also well detailed online.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.7.2 WCM Copyright 1993-2009 Day Management AG . it is possible to automate the build process and run the build on a daily basis (for example a nightly build). it is now easy to set up a central repository with SVN. Page 23 of 106 CQ 5.vlt files hold timestamps and other VLT-specific information that should not be checked into the SVN repository.settings.2.vlt files within the local directory structure. When VLT is in operation it creates . and ### while importing or adding files and directories.xml in the .2 Central dependency management with Apache Archiva Java libraries. This is used by all developers in the project as a place they can commit. This can be prevented by adding .vlt 4. The setup of an SVN server is not covered in this document as many tutorials are already available online. These .7.Development Tools • Apache Continuum to automate the build process.3 Build automation with Apache Continuum Once the project content and code is centrally available through an SVN server. The Archiva server requires little management outside that of configuring local developer accounts to obtain access to the snapshots and full releases. a continuous integration server with the sole duty of providing build management of artifacts and releases. the code and content they generate on their local instances. global-ignores = . To do this you add the following code to the local SVN setup file .2.vlt to the ignore list of the local SVN setup. The setup of Archiva is well detailed online and can be referenced during setup. 4.1 Collaboration with Subversion (SVN) As the CQ5 repository can be mapped to your file system with VLT. and retrieve. called artifacts in Maven language.2.7. can be managed centrally through Apache Archiva. This is done with Apache Continuum. 4. an artifact repository that is used to store and retrieve the project artifacts.

Your design can be defined in the designs section of the Tools tab: Here you can create the structure required to store the design and upload the cascaded style sheets and images required. Designs are stored under /etc/designs.2 WCM Copyright 1993-2009 Day Management AG . Page 24 of 106 CQ 5. The path to the design to be used for a website is specified using the cq:designPath property of the jcr:content node.5 Designer You will need a design to define for your website.

• Templates are built up of Components. Widgets and these are used to render the Content. but without any actual content. 6.2 WCM Copyright 1993-2009 Day Management AG . Page 25 of 106 CQ 5. Table 6.3 How Templates are structured There are two aspects to be considered: • the structure of the template itself • the structure of the content produced when a template is used 6. Templates within CQ5 (/apps/geometrixx/components and /libs/ foundation/components) Title Home Page Content Page Redirect Component homepage contentpage redirect Location Purpose geometrixx The Geometrixx home page template. A template is a hierarchy of nodes that has the same structure as the page to be created.3. Each Template will present you with a selection of components available for use. and allow access to. geometrixx The Geometrixx content page template. libs Redirect.2 Overview of templates CQ WCM comes with several templates including a contentpage. Component and Template.1. and home page.6 Templates 6. redirect page.1 The structure of a Template A Template is created under a node of type cq:Template. • Components use. 6.1 What are Templates? A Template is used to create a Page and defines which components can be used within the selected scope.

using sling:resourceType. This component is used to define the structure and design of the content when a new page is created. • jcr:description .2 WCM Copyright 1993-2009 Day Management AG Page 26 of 106 .Templates Various properties can be set. in particular: • jcr:title . This node contains a jcr:content (cq:PageContent) node which be used as the basis for the content node of resulting pages.title for the template. the component to be used for rendering the actual content of a new page. appears in the dialog when creating a page. this references.description for the template. CQ 5. appears in the dialog when creating a page.

3.2 The content produced by a Template Templates are used to create Pages of type cq:Page (as mentioned earlier. a Page is a special type of Component).Templates 6.2 WCM Copyright 1993-2009 Day Management AG . This: • is of type cq:PageContent • is a structured node-type holding a defined content-definition • has a property sling:resourceType to reference the component holding the sling scripts used for rendering the content Page 27 of 106 CQ 5. Each CQ WCM Page has a structured node jcr:content.

with the required properties (primarily sling:resourceType) set to allow editing and rendering.Templates 6. You can also update the jcr:description if appropriate. Note Templates are usually stored in /apps/<website-name>/templates/ <template-name>. Change the jcr:title of the new template node to reflect its new role. initial content as needed.2 WCM Copyright 1993-2009 Day Management AG .4. but often an existing template will be copied and updated to save you time and effort. Page 28 of 106 CQ 5.1 Creating a new Template (based on an existing template) Needless to say a new template can be created completely from scratch. 2. Copy an existing template (preferably with a definition as close as possible to what you want to achieve) to a new node. their role being to create the correct initial node structures. 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. They can contain as little. 3. For example. 6. the templates within Geometrixx can be used to get you started. or as much. 1.4 Developing Page Templates CQ5 page templates are simply models used to create new pages.

5. You can now create a page within your website using the new template. 4. the path to the page component that is used to render the page (everything in the child node jcr:content).Content node for template instantiations Vital Properties of Child Node jcr:content: • sling:resourceType . Changes made to the /apps/<website>/templates/<template-name> node will affect the template instance (as in the selection list). 7. Update the sling:resourceType of the template's jcr:content node to reference the new component. Replace the thumbnail. Changes made to the /apps/<website>/components/<component-name> node will affect the content page created when the template is used.Templates Note Components are usually stored in /apps/<website-name>/components/ <component-name>. Update the jcr:title and jcr:description of the new component. appears in the Create Page Dialog • jcr:description . Page 29 of 106 CQ 5.2 WCM Copyright 1993-2009 Day Management AG .Template description. Make any further changes to the functionality or design of the template and/or its underlying component.Hierarchy node of the template Vital Properties: • jcr:title .Template title.png if you want a new thumbnail picture to be shown in the template selection list. To create a page the template must be copied (node-tree /apps/<myapp>/templates/<mytemplate>) to the corresponding position in the site-tree (this is what happens if a page is created using the siteadmin). This copy action also gives the page its initial content (usually Top-Level Content only) and the property sling:resourceType.5 Summary Summary: Location: /apps/<myapp>/templates Root Node: • <mytemplate> (cq:Template) . appears in the Create Page Dialog Vital Child Nodes: • jcr:content (cq:PageContent) . 6.Reference to the rendering component The template is a blueprint of a specific type of page. 6.

These components and their usage within the installed "Geometrixx" website are a reference on how to implement and use components. then deploy this seamlessly to your test. Each CQ component: • is a resource type • is a collection of scripts that completely realize a specific function • can function in "isolation". 7. then live environments.1 What exactly is a Component? Components: • are modular units which realize specific functionality to present your content on your website • are re-usable • are developed as self-contained units within one folder of the repository • have no hidden configuration files • can contain other components • run anywhere within any CQ system • have a standardized user interface • use widgets As components are modular. you can develop a new component on your local instance. with accompanying text • toolbar Note The functionality provided by Components and Widgets was implemented by the cfc libraries in Communiqué 4.2 Default Components within CQ WCM CQ WCM comes with a variety of out-of-the-box components that provide comprehensive functionality for website authors.2 WCM Copyright 1993-2009 Day Management AG Page 30 of 106 . the default components can be found in the following locations: CQ 5.7 Components 7. this means either within CQ or a portal Components included with CQ include: • paragraph system • header • image. Using CRX. The components are provided with all source code and can be used “as is” or as starting point for modified or extended components.

• CQ5 standard components are defined as cq:Component and have the elements: • a list of jcr properties.3 Components and their structure 7. see Chapter 4. 7. these are variable and some may be optional though the basic structure of a component node. its properties and subnodes are defined by the cq:Component definition • the dialog defines the interface allowing the user to configure the component • the dialog (of type cq:Dialog) and cq:editConfig (of type cq:EditConfig) must both be defined as otherwise the component will not appear • resources: define static elements used by the component • scripts are used to implement the behavior of the resulting instance of the component • thumbnail: image to be shown if this component is listed within the paragraph system If we take the text component. this is a particular type of resource which is important for content management.1 Component definitions As already mentioned. we can see these elements: Page 31 of 106 CQ 5. including those that are not available out-ofthe-box in CQ WCM. the definition of a component can be broken down into: • CQ components are based on Sling • CQ WCM components are located under /libs/foundation/components • site specific components are located under /apps/<sitename>/components • CQ WCM has the page component.2 WCM Copyright 1993-2009 Day Management AG .3.Components • /libs/foundation/components • /apps/geometrixx/components • /libs/collab/components • /libs/collab/blog/components • /libs/collab/calendar/components • /libs/dam/components • /libs/personalization/components • /libs/replication/components • /libs/search/components • /libs/security/components • /libs/tagging/components For detailed information on all the default components.

components which are allowed as children • allowedParents . it can define the appearance of a bar or widget.specifies the design editing options for this component 7.png .graphics file to be used as a thumbnail for the component Child nodes of particular interest include: • cq:editConfig (cq:EditConfig) . again appears in the component list within sidekick • allowedChildren .2 WCM Copyright 1993-2009 Day Management AG Page 32 of 106 .this controls visual aspects.png .Components Properties of particular interest include: • jcr:title .3. for example. or can add customized controls • cq:childEditConfig(cq:EditConfig) .title of the component.defines the dialog for editing content of this component • design_dialog (nt:unstructured) .1 Dialogs Dialogs are a key element of your component as they provide an interface for authors to configure and provide input to that component.graphics file to be used as an icon for the component • thumbnail. CQ 5. for example.description for the component. appears in the component list within sidekick • jcr:description .1.components which can be specified as parents • icon.this controls the visual aspects for child components that do not have their own definitions • dialog (nt:unstructured) .

a cq:WidgetCollection (items) is used to provide a base for either input fields (cq:Widget) or further tabs (cq:Widget).as in the text component.3.hml page: Page 33 of 106 CQ 5. which will provide a single tab . the dialog can be defined as cq:TabPanel: Within a dialog. as with the textimage component. you can create the dialog as cq:Dialog.to keep the dialog short and to sort the input fields. or if you need multiple tabs.2 WCM Copyright 1993-2009 Day Management AG . This hierarchy can be extended. For example.Components Depending on the complexity of the component your dialog may need one or more tabs . 7.2 Component definitions and the content they create If we create an instance of the Text paragraph (as above) on the <content-path>/Test.

2 WCM Copyright 1993-2009 Day Management AG Page 34 of 106 .Components then we can see the structure of the content created within the repository: In particular. if you look at the title: CQ 5.

including layout information. For example.Hierarchy node of the component. Page 35 of 106 CQ 5. for example a text component will inherit various attributes from the standard component. configuration settings for the edit bar buttons.2 WCM Copyright 1993-2009 Day Management AG .3.4 Summary The following summary applies for every component. • scripts (resolved by Sling) • dialogs • descriptions (including thumbnail images. control set layout (editbars. css information. for example. follow the same basic principles. The properties defined are dependent on the individual definitions.Component description. Summary: Location: /apps/<myapp>/components Root Node: • <mycomponent> (cq:Component) . used as a label when the component is listed within the sidekick. which in turn acts as the base for various design aspects of the rendering. 7. which although they can be more complex than above.Component title. dialog layout (inline. icons. rollover). for example. This enables the component to inherit.3. also shown in the component list of the sidekick. • jcr:description .3 Component Hierarchy and Inheritance Components within CQ are subject to 3 different hierarchies: • Resource Type Hierarchy: This is used to extend components using the property sling:resourceSuperType.Components • the definition of /libs/foundation/components/text/dialog/items/title has the property name=. the available components in a parsys among others. Configuration settings (related to edit functionality) in cq:editConfig and cq:childEditConfig are propagated. • Include Hierarchy This is imposed at runtime by the sequence of includes. 7. This hierarchy is used by the Designer. this generates the property jcr:title holding the input Test Title. floating) can be defined on the parent component and propagated to the child components. Vital Properties: • jcr:title ./jcr:title • within the content. etc) • Container Hierarchy : This is used to populate configuration settings to the child component and is most commonly used in a parsys scenario.

CQ 5.An Example.Specifies the allowed child components. you copy the component and create a javascript file for the new component and store it in a location accessible to CQ5: 1. A quick way to get started is to copy an existing component and then make the changes you want.Icon & thumbnail for this component.Design editing for this component.Content editing dialog for this component. An example of how to develop a component is described in detail in Extending the Text and Image Component . • allowedParents . • icon. • cq:childEditConfig (cq:EditConfig) .Controls author UI aspects.Controls author UI aspects for child components that do not define their own cq:editConfig.Specifies the allowed parent components. bar or widget appearance. 2. for example. You can also use this method to edit existing components (although Day recommends that you back up the original component). • dialog (cq:Dialog) . 7. In the CRX Explorer.png .4. Vital Child Nodes: • cq:editConfig (cq:EditConfig) .2 WCM Copyright 1993-2009 Day Management AG Page 36 of 106 . 7. modify the jcr:description and jcr:title to reflect its new name. • design_dialog (cq:Dialog) . Create a new component folder in /apps/<website-name>/ components/<MyComponent> by copying an existing component. such as the Text component.Components • allowedChildren .1 Developing a new component by adapting an existing component To develop new components for CQ WCM based on existing component.png/thumbnail. adds custom controls. and renaming it.4 Developing Components This section describes how to create your own components and add them to the paragraph system.

you can use Ctrl-Shift-U . A list of components belonging to the paragraph system are shown (all those defined with the property allowedParents=*/parsys). you can add an additional field to the dialog box. Your new component is also listed. if you take a copy of the standard Text component. Page 37 of 106 CQ 5. Note To see timing statistics for page loading. 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. for example <contextPath>/ Test.2 Adding a new component to the paragraph system (design mode) After the component has been developed. dialog.jsp file (name it after your new component) • or completely reworking the entire component if you want For example. Open the new component folder and make the changes you require. navigate to the component and change the allowedParents property to */parsys. You can make changes such as: • adding a new field in the dialog box • replacing the . also. In the Content Explorer.html?cmsmode=design. Access a page within your authoring environment that uses the paragraph system. for example <contentPath>/Test. you add it to the paragraph system.with ? debugClientLibs=true set in the URL. 1. Note Either cq:editConfig node.Components 3. • clicking Design in Sidekick You are now in designmode and can edit the paragraph system: 2. 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. then update the . 7.2 WCM Copyright 1993-2009 Day Management AG . or design_dialog node should be present and properly initialized for the new component to appear. which enables authors to select and use the component when editing a page. The components can be activated (or deactivated) to determine which are offered to the author when editing a page.4. Click Edit. 6. Switch to Design mode by either: • adding ?cmsmode=design to the end of the URL and accessing again. 3. In CQ WCM. 5. delete any extraneous information in the folder.html.jsp to process the input made there. which makes it available to the paragraph system. 4.

using textimage as the target node name. right-clicking and selecting Copy and browsing to the target directory.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. then return to normal edit mode to confirm that it is available for use. including inheritance of widgets from parent dialog boxes • Modifying the component's script to implement the new functionality 7.1 Extending the existing textimage component To create the new component. /apps/geometrixx/components.2 WCM Copyright 1993-2009 Day Management AG . We store the new component in the Geometrixx CQ WCM example application. 1.4. 7. The following techniques are described in this exercise: • Copying existing component node and modifying its metadata • Modifying the component's dialog. To extend the textimage component. (Copy the component by navigating to the component. 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 After extending this component.4.) Page 38 of 106 CQ 5. you can configure the image placement through the component's dialog box. Activate your component.Components 4. Copy the standard textimage component from /libs/foundation/components/ textimage into the Geometrixx component folder.3 Extending the Text and Image Component . we use the standard textimage component as a basis and modify it. go to the CRX Explorer (server name:port number/crx) and log in as admin and then navigate to the Content Explorer.3.

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. To keep this example simple. 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.Components 2.2 WCM Copyright 1993-2009 Day Management AG .jsp 3. 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: Page 39 of 106 CQ 5.

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 CQ 5. representing the three tabs of the textimage dialog box. with options Left and Right: • Leave the textimage/dialog properties unchanged. and under it create two nodes. • For tab3: • Leave the properties and subnodes without changes • Add a new field definition to tab3/items.json. node position of type cq:Widget • Set the following properties (of type String) for the new tab3/items/position node • name: . Modify the component's dialog box to include the new option.infinity. tab1 to tab3. • Note how textimage/dialog/items has three subnodes. The new component inherits the parts of the dialog box that are the same as in the original. respectively. adding an Image Position dropdown list. • For the first two tabs (tab1 and tab2): • Change xtype to cqinclude (to inherit from the standard component)./imagePosition • xtype: selection • fieldLabel: Image Position • type: select • Add subnode position/options of type cq:WidgetCollection to represent the two choices for image placement. • Remove all other properties or subnodes.Components 4. 40 of 106 Page Copyright 1993-2009 Day Management AG . The only addition we make is to extend the Advanced tab.2 WCM representing textimage paragraph. • Add a pathParameter property with values /libs/foundation/components/ textimage/dialog/items/tab1.infinity.json and /libs/foundation/ components/textimage/dialog/items/tab2.

if (img. • The code fragment. • We are going to manipulate the style of the <div class="image"> tag. } %><div <%= style %> class="image"><% Note that for simplicity we are hard-coding the style to the HTML tag.fromRequest(request) == WCMMode. "image").EDIT) { %><div class="image"><% img.jsp script for editing. after the change. • Open the /apps/geometrixx/components/textimage/textimage.EDIT) { // todo: add new CSS class for the 'right image' instead of using // the style attribute Page 41 of 106 CQ 5.equals("right")) { style = "style=\"float:right\"". 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="". textimage.fromRequest(request) == WCMMode.loadStyleData(currentStyle).jsp. It is located in the following area of the code: Image img = new Image(resource.2 WCM Copyright 1993-2009 Day Management AG . if (properties. 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.hasContent() || WCMMode.hasContent() || WCMMode. should look like this (new code emphasized): Image img = new Image(resource. the component dialog box looks like this: 5. Extend the component script. We are going to replace the emphasized code fragment %><div class="image"><% with new code generating a custom style for this tag.get("imagePosition". with extra handling of the new parameter. generated by the component. "image"). if (img. • Copy the following code fragment. to float the image to the right. "left").Components After these steps.

3. • Save the script to the repository. Activate it for the paragraph system by selecting it and clicking OK. Add the Text Image (Extended) paragraph to the paragraph system. 5. and it should include your newly developed component.loadStyleData(currentStyle). Text Image (Extended).3.equals("right")) { style = "style=\"float:right\"". Open the dialog of the text and image paragraph. which enables authors to select and use the component when editing a page. A list of components. Page 42 of 106 CQ 5. 2. 6.2 WCM Copyright 1993-2009 Day Management AG . if (properties. 1. and click OK to save the changes.4.get("imagePosition". initialize text and image with sample content. English/Company Switch to design mode by clicking Design in Sidekick Edit the paragraph system design by clicking Edit on the paragraph system in the middle of the page. 7. Save and you should see the default rendering of Text and Image component: 4. Open a page in Geometrixx. } %><div <%= style %> class="image"><% img. which can be placed in the paragraph system are shown. you can add it to the paragraph system.Components String style="".2 Checking the new component After the component has been developed. "left"). The component is ready to test. and change the Image Position on the Advanced tab to Right. 6. for example. Switch back to the editing mode. These steps allow you to test the component.

with the node representing the paragraph we have just created. Page 43 of 106 CQ 5. You see the paragraph rendered with the image on the right: 8. The component stores its content in a paragraph on the Company page. The component is now ready to use. The following screenshot shows how our new configuration parameter is persisted in the repository.Components 7.2 WCM Copyright 1993-2009 Day Management AG .

1 Developing the Bulk Editor This section describes how to develop the bulk editor tool and how to extend the Product List component.jsp)or create a component with the specific configuration. The following is a list of the bulk editor query parameters: accepted parameters If name is null. Changes made using query parameters are not permanent."rootPath". then you need to modify bulkeditor. hrp=true hides the field. If you want the bulk editor to always be used with a certain configuration. search root path String rootPath = getString(request. CQ 5.5. short name is read from request.Components The textimage/imagePosition parameter represents the position of the image for this paragraph on /content/geometrixx/en/company page.jsp (located in/libs/wcm/bulkeditor/bulkeditor. 7. there are several query parameters that you can add to call the bulk editor with a specific configuration.5. as in the Product List component. 7. For example if you type the following in your browser's URL: http://<servername>:<port_number>/etc/importers/ bulkeditor.1. hrp=false displays it (the default value). which is based on the bulk editor.html?rootPath=/content/geometrixx/ en&queryParams=geometrixx&initialSearch=true&hrp=true the bulk editor displays without the root path field."rp").2 WCM Copyright 1993-2009 Day Management AG Page 44 of 106 .1 Bulk editor query parameters When working with the bulk editor. for example.5 Further Development of Specific Components and Tools 7.

"hideResultNumber". hide save button Boolean hideSaveButton = getBoolean(request."hideQueryParams"."initialSearch"."extraCols"."hcs")."ec")."hrp"). CQ 5. hide import button Boolean hideImportButton = getBoolean(request."hideExportButton"."hideExtraCols"."spc")."qp"). is content mode enabled Properties are read on jcr:content node and not on search result node Boolean contentMode = getBoolean(request. hide content mode field Boolean hideContentMode = getBoolean(request."hrn")."sgo")."hsearchb")."hqp").2 WCM Copyright 1993-2009 Day Management AG Page 45 of 106 ."cm"). hide cols selection field Boolean hideColsSelection = getBoolean(request."hideRootPath"."cs")."colsSelection"."hexpb"). on load. is query performed on page load Boolean initialSearch = getBoolean(request."hideImportButton"."hideColsSelection". show only the grid and not the search panel Note: Be sure to set initialSearch to true Boolean showGridOnly = getBoolean(request."colsValue". extra searched properties (displayed in a comma-separated text field) String[] extraCols = getStringArray(request. hide export button Boolean hideExportButton = getBoolean(request."cv"). search panel is collapsed Boolean searchPanelCollapsed = getBoolean(request."hideSaveButton". searched properties selection (displayed as checkboxes) String[] colsSelection = getStringArray(request."hideContentMode"."showGridOnly". hide grid search result number text Boolean hideResultNumber = getBoolean(request."searchPanelCollapsed". searched properties (checked values from colsSelection displayed as checkboxes) String[] colsValue = getStringArray(request."queryParams". hide query field Boolean hideQueryParams = getBoolean(request. hide root path field Boolean hideRootPath = getBoolean(request."contentMode". hide extra cols field Boolean hideExtraCols = getBoolean(request."hib")."hcm")."hsavep")."hideSearchButton"."hec"). hide search button Boolean hideSearchButton = getBoolean(request."is").Components search query String queryParams = getString(request.

Every cell is a property of each node.Attribute4]" colsValue="[CatalogCode. Configure the dialog to match the needs of the component: columns available and possible actions performed on the grid or on the search. • Edit dialog."hideDeleteButton". Here is an XML representation of the repository nodes: <editor jcr:primaryType="cq:Widget" colsSelection="[CatalogCode."hidePathCol". 7. The information is presented in a standard HTML table and any editing is performed in the Edit dialog.GroupId. save modifications.Attribute3. The source code of the Product List component is available in the repository at path /apps/ geometrixx/components/productlist and is composed of several parts like all CQ5 components: • HTML rendering: the rendering is done in a JSP file (\apps\geometrixx\components \productlist\productlist. This is a design choice and it can easily be changed.2 Developing a Bulk Editor-based component: the Product List component This section provides an overview of how to use the bulk editor and gives a description of the existing Geometrixx component based on the bulk editor: the Product List component. Every row is stored as a node under the Product List component instance itself. which contains a BulkEditor widget. The query servlet's role is to return the list of the nodes to display. With the bulk editor. Every part of the bulk editor (or components derived from the bulk editor) can be configured. and export the rows.SellingSku. filter. you can add.GroupId.Attribute2. you can use the Product List component to represent products in a catalog. modify."hideInsertButton". For example.2 WCM Copyright 1993-2009 Day Management AG . The Product List component has been configured for specific.Attribute1. hide grid "path" column Boolean hidePathCol = getBoolean(request. The Product List component lets users display and edit a table of data.jsp).Attribute3. (This Bulk Editor is exactly the same as the one accessible at /etc/importers/ bulkeditor.5. See bulk editor configuration properties for information on all of the configuration properties.1.Components hide grid insert button Boolean hideInsertButton = getBoolean(request. limited bulk editor functionality. JSP reads the subnodes of the current Product List component and displays each of them as a row of an HTML table.SellingSku.Attribute2. hide grid delete button Boolean hideDeleteButton = getBoolean(request."hinsertb"). which is where you define the Bulk Editor configuration. and import a set of rows.ProductName. delete."hdelb").Attribute1.ProductName.Attribute4]" contentMode="false" exportURL="/etc/importers/bulkeditor/export.tsv" hideColsSelection="false" hideContentMode="true" hideDeleteButton="false" hideExportButton="false" hideExtraCols="true" hideImportButton="false" hideInsertButton="false" hidePathCol="true" hideRootPath="true" hideSaveButton="false" hideSearchButton="false" importURL="/etc/importers/bulkeditor/import" Page 46 of 106 CQ 5. the search path is defined as a Product List instance.html (or through the Tools menu))."hpc"). you could store nodes somewhere else in the repository. for example.

The following table lists all the configuration properties for the bulk editor.Components initialSearch="true" insertedResourceType="geometrixx/components/productlist/sku" queryParams="" queryURL="/etc/importers/bulkeditor/query.2 WCM Copyright 1993-2009 Day Management AG Definition Search root path Search query True to enable content mode: properties are read on jcr:content node and not on search result node Page 47 of 106 .1.1.5."/> <SellingSku jcr:primaryType="nt:unstructured" cellCls="productlist-cell-sellingSku"/> <Selection> jcr:primaryType="nt:unstructured" checkbox="true" forcedPosition="0"/> </colsMetadata> </editor> 7. Bulk Editor Configuration Properties Property name rootPath queryParams contentMode colsValue CQ 5.1 Bulk Editor configuration properties Every part of the bulk editor can be configured."/> <ProductName jcr:primaryType="nt:unstructured" cellStyle="background-color: #FFCC99.2."/> <GroupId jcr:primaryType="nt:unstructured" cellStyle="background-color: #8080FE.json" xtype="bulkeditor"> <saveButton jcr:primaryType="nt:unstructured" text="Save modifications"/> <searchButton jcr:primaryType="nt:unstructured" text="Apply filter"/> <queryParamsInput jcr:primaryType="nt:unstructured" fieldDescription="Enter here your filters" fieldLabel="Filters"/> <searchPanel jcr:primaryType="nt:unstructured" height="200"> <defaults jcr:primaryType="nt:unstructured" labelWidth="150"/> </searchPanel> <grid jcr:primaryType="nt:unstructured" height="275"/> <store jcr:primaryType="nt:unstructured"> <sortInfo jcr:primaryType="nt:unstructured" direction="ASC" field="Attribute2"/> </store> <colModel jcr:primaryType="nt:unstructured" width="150"/> <colsMetadata jcr:primaryType="nt:unstructured"> <CatalogCode jcr:primaryType="nt:unstructured" cellStyle="background-color: #EDEDED. Table 7.

Possible properties are (applied to all cells of the column): Page 48 of 106 CQ 5.2 WCM Copyright 1993-2009 Day Management AG .Components Property name Definition Searched properties (checked values from colsSelection displayed as checkboxes) extraCols initialSearch colsSelection showGridOnly searchPanelCollapsed hideRootPath hideQueryParams hideContentMode hideColsSelection hideExtraCols hideSearchButton hideSaveButton hideExportButton hideImportButton hideResultNumber hideInsertButton hideDeleteButton hidePathCol queryURL exportURL importURL insertedResourceType saveButton searchButton exportButton importButton searchPanel grid store colModel rootPathInput queryParamsInput contentModeInput colsSelectionInput extraColsInput colsMetadata Extra searched properties (displayed in a textfield comma separated) True to perform query on page load Searched properties selection (displayed as checkboxes) True to show only the grid and not the search panel (do not forget to set the initialSearch to true) True to collapse search panel by default Hide root path field Hide query field Hide content mode field Hide cols selection field Hide extra cols field Hide search button Hide save button Hide export button Hide import button Hide grid search result number text Hide grid insert button Hide grid delete button Hide grid "path" column Path to query servlet Path to export servlet Path to import servlet Resource type added to node when a row is inserted Save button widget config Search button widget config Export button widget config Import button widget config Search panel widget config Grid widget config Store config Grid column model config rootPath widget config queryParams widget config contentMode widget config colsSelection widget config extraCols widget config Column metadata config.

The grid can then display rows that are an aggregate of several nodes in the repository.Components Property name • cellStyle: html style • cellCls: css class Definition • readOnly: true to not being able to change value • checkbox: true to define all cells of the column as checkboxes (true/false values) • forcedPosition: integer value to specify where column must be placed in grid (between 0 and number of colums-1) 7. For example. You can configure another path to retrieve the data. a query could be • query: "path /content/brand/ chair" • cols: "nameID.2 Query servlet By default. In the Product List component case. The modification and the saving of these rows must in that case be managed by the Save Servlet. results: 2 } Each hit corresponds to one node and its properties and is displayed as a row in the grid.2. and sends the results back to the bulk editor as a JSON stream. the Query servlet can be found at /libs/wcm/bulkeditor/json.5.1. computes the results.{ jcr:path: "/content/geometrixx/en/customers/jcr:content/par/productlist/1243436455361" CatalogCode: "CC2" GroupId: "GI2" SellingSku: "SS2" ProductName: "PN2" }].ProductName" and the JSON stream returned is as follows: { hits: [{ jcr:path: "/content/geometrixx/en/customers/jcr:content/par/productlist/1243436455359" CatalogCode: "CC1" GroupId: "GI1" SellingSku: "SS1" ProductName: "PN1" }.SellingSku. The Query servlet can be used to do any kind of complex computation.catalogCode…" You can extend the Query servlet to return a complex inheritance model or return nodes stored at a specific logic place. the two parameters sent to the Query servlet are as follows: • query: "path:/content/geometrixx/en/customers/jcr:content/par/productlist aFilter" • cols: "CatalogCode. Page 49 of 106 CQ 5.sku. The Query servlet works as follows: it receives a GQL query and the columns to return.GroupId.2 WCM Copyright 1993-2009 Day Management AG .java.

It takes all parameters received (format "jcr path"/"property name") and writes properties on nodes using the JCR API.2 WCM Copyright 1993-2009 Day Management AG Page 50 of 106 . "readOnly": true/false } } This example can be found in the productlist component (/apps/geometrixx/components/ productlist/dialog/items/editor/colsMetadata): CQ 5.Components 7. the default code provided in this file re-implements what the server does natively (a POST on "jcr path"/"property name") and therefore is only a good starting point for building a Save servlet that will manage a property inheritance model.5. • Read only (readOnly): read only is set for each cell of the configured column.1.4.1. Each updated property is sent to servlet in this format: Parameter name: "jcr path"/"property name" Value: new value Example: /content/brand/season/fall/groups/group1/sku1/catalogCode = 123456 This servlet should know where the catalogCode property is stored.3 Save servlet Currently. This gives this servlet the possibility to analyze the modifications and save the properties on the right node. a POST query is sent to each path with the updated properties values. • Cell style (cellStyle): an HTML style that is added on each cell of the configured column.1. Do not use the default code as is.2.jsp ) and is in use in the ProductList component. A default Save servlet implementation is available (/libs/wcm/bulkeditor/save/POST.5.1 CSS and read-only columns The bulk editor has three column configurations: • Cell CSS class name (cellCls): a CSS class name that is added on each cell of the configured column. Configuration must be defined like this: "colsMetadata": { "Column name": { "cellStyle": "html style".4 Metadata configuration You can configure metadata in the following ways: • CSS and read-only columns • Checkbox and forced position 7. this model cannot work: a property returned by the Query servlet can be inherited from another node. each row is a node and the path of this node is stored in the row record. This is the basis of the Sling concept and it works well if each cell is a property of the node. The Bulk Editor keeps the link between the row and the node because of the jcr path. But because the Query servlet makes inheritance computation.2. 7. a list of all of the modifications is built. It also creates node if they do not exist (grid inserted rows).2. When a user edits the grid.5. The Save servlet concept is that the modifications are not directly posted to each node but that they are posted to one servlet that does the saving job. When a user clicks Save. "cellCls": "CSS class".

A checked box sends true to server Save servlet.1. These options are enabled if the selected header is the header of a checkbox column. This example can be found in the productlist component (/apps/geometrixx/components/productlist/ dialog/items/editor/colsMetadata): selection column contains only checkboxes and is always the first column."/> <GroupId jcr:primaryType="nt:unstructured" cellStyle="background-color: #8080FE. <colsMetadata jcr:primaryType="nt:unstructured"> <CatalogCode jcr:primaryType="nt:unstructured" cellStyle="background-color: #EDEDED.4. Any other value is ignored. then all the cells of the columns are rendered as checkboxes."/> <ProductName jcr:primaryType="nt:unstructured" cellStyle="background-color: #FFCC99.4. <colsMetadata jcr:primaryType="nt:unstructured"> <CatalogCode jcr:primaryType="nt:unstructured" cellStyle="background-color: #EDEDED."/> <GroupId jcr:primaryType="nt:unstructured" cellStyle="background-color: #8080FE."/> <SellingSku jcr:primaryType="nt:unstructured" cellCls="productlist-cell-sellingSku"/> <Selection jcr:primaryType="nt:unstructured" checkbox="true" forcedPosition="0"/> Page 51 of 106 CQ 5. In the header menu. you can also select all and select none.2 WCM Copyright 1993-2009 Day Management AG ."/> <SellingSku jcr:primaryType="nt:unstructured" cellCls="productlist-cell-sellingSku"/> <Selection jcr:primaryType="nt:unstructured" checkbox="true" forcedPosition="0"/> </colsMetadata> 7.5.2.2."/> <ProductName jcr:primaryType="nt:unstructured" cellStyle="background-color: #FFCC99.3 Forced position Forced position (forcedPosition) metadata lets you specify where the column must always be placed within the grid: 0 is the first place and <number of columns>-1 is the last position."/> <SellingSku jcr:primaryType="nt:unstructured" cellCls="productlist-cell-sellingSku"/> </colsMetadata> 7.5."/> <ProductName jcr:primaryType="nt:unstructured" cellStyle="background-color: #FFCC99.Components <colsMetadata jcr:primaryType="nt:unstructured"> <CatalogCode jcr:primaryType="nt:unstructured" cellStyle="background-color: #EDEDED."/> <GroupId jcr:primaryType="nt:unstructured" cellStyle="background-color: #8080FE.1. false otherwise.2 Checkbox If the checkbox configuration property is set to true.

jsp The JSP script file global.jsp should be included in every component rendering JSP script where one or more of the objects provided in global.6.jsp) Summary: • <cq:defineObjects /> • slingRequest . According to the request processing rules of Sling the name for the default script is <componentname>.jsp are used. • component .class).6 Scripts JSP Scripts or Servlets are usually used to render components.The designer object for retrieving design information (resourceResolver. • sling . • pageProperties .The resolved JCR node for the request.1 Function of global.jsp: Page 52 of 106 CQ 5. • resource .adaptTo(PageManager.adaptTo(Designer.class).The Sling Resource Resolver Object (slingRequest.getResource().2 Accessing Content There are three methods to access content in CQ5 WCM: • Via the properties object introduced in global. 7..1 global.The Default logger ().Components </colsMetadata> 7.adaptTo(ValueMap.The properties of the addressed resource (resource.e.jsp.2 WCM Copyright 1993-2009 Day Management AG .1. • currentNode .6. to access content) to any JSP script file used to render a component. Therefore global. • currentDesign . 7. • properties . • pageManager .The properties of the page of the addressed resource.The Sling Resource Object (slingRequest. • designer .).). used APIs and Taglibs The following lists the most important objects provided from the default global.The wrapped Request Object (SlingHttpServletRequest).The design of the addressed resource.).The style of the addressed resource.The component object of the current CQ5 component.getResoucreResolver().6.The wrapped Response Object (SlingHttpServletResponse).The Sling script helper.The page manager for accessing CQ content pages (resourceResolver.jsp (/libs/ wcm/global.jsp is used to provide quick access to specific objects (i.jsp.class). • currentStyle . • log . • resourceResolver .). 7.).1. • slingResponse .

"no title"). To use the CQ Tag Library in your script. Tip When you develop the jsp script of a CQ5 component. Example: String pageTitle = currentPage.1.jsp.Components The properties object is an instance of a ValueMap (see Sling API) and contains all properties of the current resource. • Via currentNode object introduced in global.com/taglibs/cq/1.getTitle().getProperty("jcr:title"). used in the rendering script of a standard paragraph component.6. Example: String paragraphTitle = properties. 7.1 <cq:setContentBundle> The <cq:setContentBundle> tag creates an i18n localization context and stores it in the javax. This shortens and simplifies the jsp code of your component. Example: String pageTitle = currentNode.jsp"%> It declares the sling.2.2 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.jsp file is included in the script. it is recommended to include following code at the top of the script: <%@include file="/libs/wcm/global. cq and jstl taglibs and exposes the regularly used scripting objects defined by the <cq:defineObjects /> tag.fmt.1 CQ Tag Library The CQ tag library contains helpful CQ functions. Example: String pageTitle = properties.jsp: The currentPage object is an instance of a page (see CQ5 API).get("jcr:title". "no title").6.day. The properties of a node can be accessed by the getProperty() method.jsp: The currentNode object is an instance of a node (see JCR API).jstl. Page 53 of 106 CQ 5. CQ5 is a Sling Application and therefore we deal with resources and not nodes.2 WCM Copyright 1993-2009 Day Management AG .0" %> Note When the /libs/wcm/global.localizationContext configuration variable.6. the script must start with the following code: <%@taglib prefix="cq" uri="http://www. 7. used in the rendering script of a page component.get("jcr:title". The page class provides some methods to access content. the cq taglib is automatically declared.2. Note Day does not recommend using the JCR API directly in CQ5 if not really necessary. 7. • Via the currentPage object introduced in global.servlet.

2 <cq:include> The <cq:include> tag includes a resource into the current page. The lookup of messages by keys is two-fold: 1. the JCR properties of the underlying resource that is currently rendered are searched for translations. It has the following attributes: flush A boolean defining whether to flush the output before including the target.Resource. If the node does not contain a property named exactly like the key.ResourceUtil. b.foundation.resource.getResourceBundle(null). this is used. Either path and resourceType.1. path The path to the resource object to be included in the current request processing.sling.resource. adding parameters. the tag may create a synthetic resource object out of the path and this resource type.resource. Example: <%@include file="/libs/wcm/global.apache. resourceType The resource type of the resource to be included. CQ 5. Finally. Either path and resourceType. if there is no page language defined.apache.2 WCM Copyright 1993-2009 Day Management AG Page 54 of 106 . If the resource type is set. This allows you to define a simple component dialog to edit those values.foundation.api. or script must be specified. if the parameter language of the<cq:setContentBundle> tag is set. org. the fallback is to load a resource bundle from the sling request (SlingHttpServletRequest. or script must be specified.ValueMap" %><% %><cq:setContentBundle/> 7.day.ValidationInfo. The "content bundle" can be simply used by standard JSTL <fmt:message> tags.foundation.sling. c. which is typically taken from the page path (eg. If the resource to be included is specified with the path attribute that cannot be resolved to a resource.getResourceBundle(Locale)). First. Either path and resourceType. the locale of the page is looked up.jsp"%><% %><%@ page import="com. which is equivalent to calling request.forms. org.apache. the path must be the exact path to a resource object: in this case.Components It has the following attribute: language The language of the locale for which to retrieve the resource bundle. com.api. org. The language or locale for this bundle is defined this way: a.day. the default locale of the current request is used.forms. or script must be specified.cq. com.cq.2.wcm.wcm.6.day. the path / content/site/en/some/page produces the "en" locale).FormsConstants.forms.api. 2.FormsHelper.cq. First. This is defined by the LanguageManager of CQ5 (language copy function).wcm. selectors and extensions to the path is not supported. Otherwise. If this path is relative it is appended to the path of the current resource whose script is including the given resource. script The jsp script to include.sling.

cq.2.day.wcm. component the current CQ5 component object of the current resource (com.jsp"/> <cq:include path="par" resourceType="foundation/components/parsys" /> </div> Note Should you use <%@ include file="myScript. Example: <%@taglib prefix="cq" uri="http://www.jsp" %> or <cq:include script="myScript. If true. Note Should you use <cq:include> or <sling:include>? • When developing CQ5 components.cq.day. • <cq:include> allows you to directly include script files by their name when using the script attribute.components.components.api. scripting objects which can be referenced by the developer.wcm.api.com/taglibs/cq/1. 7.Design interface).day.cq.Component interface).designer.day. It also exposes the objects defined by the <sling:defineObjects> tag.1. This takes component and resource type inheritance into account.cq.api.ComponentContext interface). Page 55 of 106 CQ 5.jsp" %> directive.6.wcm. • With the <cq:include script="myScript.Page interface).3 <cq:defineObjects> The <cq:defineObjects> tag exposes the following.designer. It is as if the contents of the included file were pasted directly into the original file.jsp" %> to include a script? • The <%@ include file="myScript.Style interface). componentContext the current component context object of the request (com. currentPage the current CQ WCM page object (com.wcm.api.cq. regularly used.day.day.api.api.designer.wcm.day. and is often simpler than strict adherence to Sling's script resolution using selectors and extensions. currentDesign the current design object of the current page (com.Designer interface).wcm.cq.2 WCM Copyright 1993-2009 Day Management AG . Day recommends that you use <cq:include>. currentStyle the current style object of the current cell (com. the file is included at runtime.Components ignoreComponentHierarchy A boolean controlling whether the component hierarchy should be ignored for script resolution. designer the designer object used to access design information (com. only the search paths are respected.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" %> directive informs the JSP compiler to include a complete file into the current file.

components.PageManager interface).resource.resource.day.Components editContext the edit context object of the CQ5 component (com.api.wcm.day. resourcePage the resource page object (com.cq. It has the following attributes: requestName inherited from sling responseName inherited from sling 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 CQ 5. resourceDesign the design object of the resource page (com.api.Page interface).apache.designer.sling. pageManager the page manager object for page level operations (com.day. properties the properties object of the current resource (org.api.wcm.cq.Design interface).api.api.wcm.ValueMap).api. pageProperties the page properties object of the current page (org.2 WCM Copyright 1993-2009 Day Management AG Page 56 of 106 .sling.day.cq.apache.EditContext interface).cq.ValueMap).wcm.

value}"/></cq:requestURL>">${label} (${bucket.html?mode=view&query=something into mypage.html?query=something. all other parameters are unaffected. charset=utf-8" %><% %><%@ page import="com.2.4 <cq:requestURL> The <cq:requestURL> tag writes the current request URL to the JspWriter. it enables you to transform the request: mypage.1. 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.5 <cq:addParam> The <cq:addParam> tag adds a request parameter with the given name and value to the enclosing <cq:requestURL> tag.1.2 WCM Copyright 1993-2009 Day Management AG Page 57 of 106 .wcm.Components 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.day. 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.jsp file is included in the script. The use of addParam or removeParam only changes the occurence of the given parameter.com/taglibs/cq/1. It allows you to create links to the current page with varying parameters.count})</a> 7.0" %><% %><cq:defineObjects/> Note When the /libs/wcm/global.day.WCMMode" %><% %><%@taglib prefix="cq" uri="http://www. the <cq:defineObjects / > tag is automatically included. 7. For example.6.6. <cq:requestURL> does not have any attribute.2. It has the following attributes: name name of the parameter to be added CQ 5.cq.api.

When you use the Sling Tag Library in your script. 7. the path must be the exact path to a resource object: in this case. If no value is provided all parameters with the given name are removed. the resource takes precedence. Either resource or path must be specified.2 Sling Tag Library The Sling tag library contains helpful Sling functions. CQ 5.6. resourceType The resource type of the resource to be included. resource The resource object to be included in the current request processing. adding parameters.org/taglibs/sling/1.1 <sling:include> The <sling:include> tag includes a resource into the current page.jsp file is included in the script.2 WCM Copyright 1993-2009 Day Management AG Page 58 of 106 .2.6.1.0" %> Note When the /libs/wcm/global. If this path is relative it is appended to the path of the current resource whose script is including the given resource. 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> 7.2. the script must start with the following code: <%@ taglib prefix="sling" uri="http://sling. If both are specified. the sling taglib is automatically declared. If the resource type is set. path The path to the resource object to be included in the current request processing.6.Components value value of the parameter to be added Example: <a title="filter results" href="<cq:requestURL><cq:addParam name="language" value="${bucket.count})</a> 7.2.value}"/></cq:requestURL>">${label} (${bucket.2.6 <cq:removeParam> The <cq:removeParam> tag removes a request parameter with the given name and value from the enclosing <cq:requestURL> tag. If both are specified.apache. selectors and extensions to the path is not supported. It has the following attributes: flush A boolean defining whether to flush the output before including the target. Either resource or path must be specified. the resource takes precedence.

resourceResolver The current ResourceResolver object.Service.getResourceResolver().6. embedding header html snippets) and sling. the selectors.2 <sling:defineObjects> The <sling:defineObjects> tag exposes the following. etc. slingResponse SlingHttpServletResponse object.2 WCM Copyright 1993-2009 Day Management AG Page 59 of 106 . response The standard JSP response object which is a pure HttpServletResponse.class) to retrieve OSGi services available in Sling (Class notation depending on scripting language).Components If the resource to be included is specified with the path attribute that cannot be resolved to a resource. regularly used. replaceSelectors When dispatching. request The standard JSP request object which is a pure HttpServletRequest. from the current request are used for the included script as well. extension. They can be modified through the tag attributes: for example replaceSelectors="foo. selector. 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. the value of this attribute is added to the selectors.include('/ some/other/resource') for including the responses of other resources inside this response (eg. scripting objects which can be referenced by the developer: slingRequest SlingHttpServletRequest object. By default.getService(foo. replaceSuffix When dispatching. providing access for the HTTP response that is created by the server. containing convenience methods for scripts. mainly sling.2. etc.2. the selectors are replaced with the value of this attribute. CQ 5. It is the same as slingRequest. the tag may create a synthetic resource object out of the path and this resource type.bar. This is currently the same as the HttpServletResponse from which it extends. providing access to the HTTP request header information extends the standard HttpServletRequest . path info. the suffix is replaced by the value of this attribute.bar" allows you to overwrite the selectors. addSelectors When dispatching. sling A SlingScriptHelper object.and provides access to Sling-specific things like resource. Examples: <div class="item"><sling:include path="<%= pathtoinclude %>"/></div> <sling:include resource="<%= par %>"/> <sling:include addSelectors="spool"/> <sling:include resource="<%= par %>" resourceType="<%= newType %>"/> <sling:include replaceSelectors="content" /> 7.

info("Executing my script").wcm.7.apache. log Provides an SLF4J Logger for logging to the Sling log system from within scripts.Components resource the current Resource object to handle. It is the same as slingRequest.2 WCM Copyright 1993-2009 Day Management AG . It has the following attributes: requestName responseName resourceName nodeName logName resourceResolverName slingName Example: <%@page session="false" %><% %><%@page import="com.cq. currentNode If the current resource points to a JCR node (which is typically the case in Sling). This navigation component is placed at the top of the content pages in the website. only rendering.7 A closer look at a few of the foundation components. this gives direct access to the Node object. Therefore there is no need for a dialog. Otherwise this object is not defined. depending on the URL of the request. • Displays as in the following screenshot: Page 60 of 106 CQ 5. 7. There is no content to be handled by this component..0" %><% %><sling:defineObjects/> 7.org/taglibs/sling/1.1 Top Navigation Component The Top Navigation Component displays the top level pages of the website.getResource().foundation.forms.ValidationHelper"%><% %><%@taglib prefix="sling" uri="http://sling. eg.day.. The following sections explain how the most commonly used components of the reference website Geometrixx have been developed. log. Specification summary: • /libs/foundation/components/topnav • Displays level one pages (below Homepage). • Respects On/Off status and uses image rendering.

day.day. /contentpage/navimage.png. To achieve this a specific selector is added to the request for the navigation item image of a page.wcm.core.day.day. performing checks on On-/Offtime etc).wcm.png. By overwriting the createLayer() method.Layer For more detailed information please have a look at the Javadoc provided with CQ5 WCM.core. can be used instead of isValid() and isHideInNav() For more detailed information please have a look at the Javadoc provided with CQ5 WCM.cq. this handles all requests with the specific selector (for example. a mechanism is needed to request a page in an “image navigation item view”.commons.core.day.foundation.day.getAbsoluteParent(int level): Get the the parent page on an absolute level • PageFilter(): The default CQ Page filter: checks if the page is valid (by checking that the property hideInNav is not set. For rendering text images the abstract servlet AbstractImageServlet is very helpful.cq. 7.isHideInNav(): checks if the page is valid or the hide in navigation property is set respectively • com.cq.image.cq.day.getPage(String path): get the page related to a path • com.cq.png.Page.java). an image processing script (or servlet) is added.cq.Components 7.navimage.Font • com. The following are an introduction to the relevant functionality (API calls): • com.core.wcm. To achieve this.listChildren(): get the childpages of the page • com.Page.day.1.WCMUtils • com.wcm.wcm.2 WCM Copyright 1993-2009 Day Management AG Page 61 of 106 .wcm. The following lists the relevant functionalities (API calls): • com.AbstractImageServlet • com.Page.day. it is possible to programmatically create a fully customized image. Sling's request processing mechanism is used for this.isValid() + . Also required is the functionality to: get the path of the parent page of any page on a specific absolute level (start page of the navigation).jsp or /contentpage/ navimage.ImageHelper • com.getTitle(): get the path or title of the page respectively • com.cq. Requests with such a selector have to be handled by an image processing mechanism.wcm.getPath() + .core. functionality to “get the childpages” of a specific page is essential. for example. CQ 5.7. check the validity of a page and of course get the path and title of a page.1.commons. /path/to/a/page.wcm.Page.PageManager.1 Navigation Essentials The main function of a navigation component is to: • show the hierarchical page structure of a website • provide the possibility to access the pages within this structure.7. To realize this.image.cq.2 Image Rendering Essentials To be able to use image based navigation items.day.

description and date.node for the dialog Vital Properties: • xtype=panel .2 WCM Copyright 1993-2009 Day Management AG Page 62 of 106 . description and date. a specific URL selector ('navimage') is added. referring to pages which are below either the current page or a root page defined by the path provided in a dialog • /libs/foundation/components/listchildren • Respects the On/Off status of displayed pages • The following screenshot shows an example of how it displays: 7.1. Below the tab-nodes.Components 7.1 Dialog & Widgets The Dialog of a component is defined in a subtree of nodes below the component's root node. If no root page is set. title sets the title of the dialog Vital Child Nodes of Dialog Node: • items (cq:WidgetCollection) .3 Image based Top Navigation Component The Top Navigation component renders graphical (image based) navigation items.tab nodes within the dialog Vital Child Nodes of Tab Node: • <mywidget> (cq:Widget) . root nodes for the individual tabs of the dialog are added.2. To identify the view (kind of presentation) the resource (page) is rendered by.7. Specification summary: • Display a list of links with title.Defines the dialog's xtype as panel. These tab nodes are of nodeType cq:WidgetCollection. The root node of the dialog is of nodeType cq:Dialog and named dialog. The component displays a list of links with title. 7. This means. The root page can be configured for every instance of this component (for every paragraph which is rendered by this component). Summary: Location: /apps/<myapp>/<mycomponent>/dialog Root Node: • dialog (cq:Dialog) .7.widget nodes within the tab CQ 5. the widget nodes are added. the paths of the image tags for the navigation items are equivalent to the paths of the pages that the navigation items represent.7.2 List Children Component The List Children component displays the child pages under a given root page. the current page is taken as the root page. Below this. The images for the navigation items are requested from the page resources in a specific view. these are of nodeType cq:Widget. Therefore a dialog is needed to store the path of the root page as content in the corresponding paragraph resource.

CQ 5. Design dialogs are structured in the same way as normal dialogs but are named design_dialog. including the path to the tool-pages.1 Designer The Designer is used to manage the look-and-feel of the global content. The Logo component is placed in the upper left corner of all pages on the website. Therefore a design dialog is needed to provide the image and path of the home link to the design of the corresponding Page.Content node for the design Vital Properties of Child Node jcr:content: • sling:resourceType = “wcm/designer” .3./mypropertyname) • xtype . Summary: Location: /etc/designs Root Node: • <mydesign> (cq:Page) .Defines the name of the property where the content provided by this widget is stored (usually something like .Components Vital Properties: • name . Specification summary: • /libs/foundation/components/logo • Displays a linked logo image in the upper left corner (spooled image.Reference to the designer rendering component The Designer values can be accessed by the currentStyle object provided in global.jsp.7.Defines the widget's xtype • fieldLabel . size and so on. store the logo image and level in the design of geometrixx • Displays as in the following screenshot 7.Hierarchy node of the design page Vital Child Nodes: • jcr:content (cq:PageContent) .The text displayed in the dialog as a label for this widget 7. image of the logo. design values such as text family. The logo image and the home link can be configured globally (same for every page of the website) so that every instance of this component is identical. no rendering) • The path for the link is the path of a page on a defined absolute level • The logo image and the level are the same for all pages on the website.2 WCM Copyright 1993-2009 Day Management AG Page 63 of 106 .7.3 Logo Component The Logo component displays the logo of the website Geometrixx.

/image/imageRotate or . • ddGroups . • fileReferenceParameter ./image. • There is the possibility to crop. • fileNameParameter ./image/fileReference or . It also supports the cropping and mapping of images amongst other functions. usually . The most important properties of the smartimage widget are: • xtype .png or ./imageMap.Groups in contentfinder from where assets can be dragged to this widget.Where to store the map data.Where to store the rotation specification./ imageCrop. usually . description. map etc the image.Location to store the image reference when an image from the media library is used.Specifies where the name of the image file will be stored. 7.png.1 Widget smartimage The smartimage widget is an extended widget used to handle the most common aspects of image handling in a WCM system.7. CQ 5.The type of widget ('smartimage'). usually . It is used to structure the individual pieces of content on a website.2 WCM Copyright 1993-2009 Day Management AG Page 64 of 106 ./fileReference./file.7. You can create paragraphs inside the Paragraph System. usually . usually ./fileName.7. • The image and certain paragraph-related display properties (title.4 Paragraph System The Paragraph System is a key part of a website as it manages a list of paragraphs. maximal size). usually . • rotateParameter . move. 7. The Paragraph System provided in CQ5 WCM foundations covers most of the variants needed and can also be configured by allowing you to select the components to be activated/deactivated within your current paragraph system. copy and delete paragraphs and also use a column control to structure your content in columns. • title . • mapParameter . valid for all paragraphs of this type (minimal size.The place to store the crop coordinates./image/imageCrop or . • Some global design properties./img. • requestSuffix ./ image/fileName or .The default suffix to be used when browsing for an image with this widget. Specification summary: • /libs/foundation/components/image • Displays an image in the main paragraph system. usually .The title displayed in the dialog.Components 7. are stored in the design by a design dialog. • name . • cropParameter .5.5 Image Component The Image component displays images in the main paragraph system.The place to store the image file (binary)./image/file or .img. It controls the upload of the image file and stores the reference to the media library./imageRotate. size) are stored in the paragraph resource by a dialog./image/imageMap or .

cq.2 Contentfinder Essentials To be able to drag assets from the contentfinder to a component there must be a drop target configuration node called cq_dropTargets below the edit configuration node (cq:editConfig).Hierarchy Node of the drop target configuration. usually /tmp/uploaded_test/ *.5.day.Where the reference will be stored.5.The resource type to be stored in the case that a complete paragraph has to be created (as when dragging an asset to the paragraphsystem while pressing the Alt button). 7./image/ fileReference or .The media types to be accepted. • uploadUrl . 100.e.Maximum size limit.foundation. Below this node the following node tree (with vital properties) must be created for the smartimage: • image (nt:unstructured) with the following vital properties: • accept . usually .3 Image Component Essentials This section lists the most relevant functionalities (API calls) for the programmatic manipulation of images: • com.7. • groups . i. i. as with textimage. media • propertyName .Groups in the contentfinder from where assets can be accepted.e.Components • sizeLimit .Image • addCssClass • loadStyleData • setSelector • setSuffix CQ 5. when the image is not the only data to be stored for the resource) the following two nodes must also be created: • parameters (nt:unstructured) below the image node • image (nt:unstructured) below the parameters node with the following vital properties: • sling:resourceType . image/gif.The path to be used when storing data temporarily./fileReference In the case that the image is stored in a separate image node in the content (for example.e. i. Summary: Location: /apps/<myapp>/components/<mycomponent>/cq:editConfig/ cq:dropTargets Root node: • cq:dropTargets (cq:DropTargetConfig) .7.2 WCM Copyright 1993-2009 Day Management AG Page 65 of 106 .wcm. image/jpeg or image/png. 7.

6 Text & Image Component The Text & Image Component displays text and images in the main paragraphsystem. It stores the text with the formatting information.wcm.cq. For an introduction to the AbstractImageServlet. the AbstractImageServlet is used to render the images.commons.DropTarget • com.4 Image Rendering Essentials As for the Top Navigation component. As the request to the resource in the 'image view' has to be detected. ignoreData=true and value=true .day. • There is the possibility to manipulate the image. usually false.6.7.cq.wcm./textIsRich.api. size) are stored in the paragraph resource (dialog).day.7.1 Widget richtext The richtext widget is an extended widget used to handle the most common aspects of text handling in a WCM system. Requests with such a selector are handled by the image processing servlet.2 WCM Copyright 1993-2009 Day Management AG . description. 7.components.Defines whether the label should be displayed. • The text and image together with specific paragraph related display properties (title. usually .components. 7. see the section called “Image Rendering Essentials”. The most important properties of the richtext widget are: • xtype . • hideLabel .EditConfig • com.day.The type of the widget ('richtext') • name .img.api.Used to define that format is rich text format.cq.WCMUtils For more detailed information please look at the Javadoc provided with CQ5 WCM. /path/to/the/resource.2 Text & Image Component Essentials This section lists the most relevant functionalities (API calls) for the programmatic manipulation of texts and images: Page 66 of 106 CQ 5.7. Specification summary: • /libs/foundation/components/textimage • Displays a text and image in the main paragraphsystem. a specific selector to the request of the image (i.6.5. 7./text. including cropping and mapping amongst other functions.Where the text is stored. • richFlag (xtype=hidden) with name .png) needs to be added.7. • For the image rendering use the servlet created for the image component (to inherit from the image component set resourceSuperType) 7.wcm.e.Components • draw • getDescription • com.

wcm.Search Class to be used for almost every aspect of the search.TextFormat • com.cq.Search .7 Search Component The Search component can be placed in the paragraph system of any page. • Provides a dialog to define some properties • Search button text • No results text • Previous label • Next label • Provides pagination 7.Result • getResultPages • getPreviousPage • getNextPage For more detailed information please have a look at the API documentation provided with CQ5 WCM.api. 7.7.2 WCM Copyright 1993-2009 Day Management AG .day.cq.cq. • Displays the result of the search for a query provided in the request (if a query was provided).foundation.7.1 Search Essentials This section lists the most relevant functionalities (API calls) for the programmatic manipulation of searches: • com.cq.foundation. Page 67 of 106 CQ 5. It searches the content of the site for a query provided in the request.wcm.day.7.WCMMode For more detailed information please have a look at the Javadoc provided with CQ5 WCM.Get the result object • com. Specification summary: • /libs/foundation/components/search • Displays a search form.Components • com.Search.day.wcm. The query is expected in a request parameter named 'q' • getResult .foundation.wcm.day.

2 WCM Copyright 1993-2009 Day Management AG .the parsys & iparsys components. so that only authorized people (usually the administrator) can change them. graphics). • Provide necessary flexibility and configuration capabilities to your custom components. without requiring the involvement of development teams. This makes the whole process much longer and costly.as low as the number of fundamentally different page structures on the web sites. Page 68 of 106 CQ 5. and administrators with the functionality to adapt their websites to changing business needs (content agility) while retaining the uniform layout of the sites (brand protection). is usually a costly exercise. such as creating a new template. Alternative methods. is to introduce a new type of content presentation on their websites. • Maximize use of the power and flexibility of CQ paragraph system . They can be used by developers to provide website business users. The recommended way to approach such a challenge would be to: • Reuse an existing template to create a new type of page. • Editors add and configure the allowed components. The following general rules for developers make sense in majority of usual projects: • Keep the number of templates low . requiring a change management process and involvement of the development team. Let us assume there is a need to add a “newslist” page to the websites. to deliver the requested functionality (information) to the business. In our case it could be a “list” component. A typical challenge for a person responsible for a website. The template roughly defines page structure (navigation elements. The developers of CQ based systems should therefore use: • templates and access control to paragraph system design for uniformity and brand protection • paragraph system including its configuration options for flexibility. which lists extracts from other articles already published. which is further fine-tuned by its design (CSS. • Define access right to the Design mode of the paragraph systems. which can traverse a subtree of pages and extract the information according to predefined rules. • Define the components allowed in the given paragraph system so that editors can then place the required components on the page. editors. or set of websites (for example in a branch office of a global enterprise). This illustrates how this approach empowers the contributing users and administrators of the website to respond to business needs quickly. • Use the paragraph system (parsys/iparsys) on the new pages. and so on). panels. The page should have the same design and structure as the rest of the website. on the pages they are responsible for.8 Guidelines for Using Templates and Components CQ components and templates form a very powerful toolkit.

day.cq. com. Page 69 of 106 CQ 5. is used to access CQ WCM functionality.9 Java WCM API The WCM API package.2 WCM Copyright 1993-2009 Day Management AG .*.wcm.

1.1. Please refer to Chapter 1.1. The first part describes the Nodes. and Properties This section describes the Nodes. Node Types. 10.2 WCM Copyright 1993-2009 Day Management AG Page 70 of 106 .1.1 MSM in the Repository This section describes what happens in the repository when you set up MSM. and Properties that are specific to MSM. 10. • How MSM can be extended to meet the specific needs of your application.1 cq:LiveRelationship mixin The cq:LiveRelationship mixin is used as a supertype for the cq:LiveSync mixin.1 MSM-specific Nodes.2 cq:LiveSync mixin The cq:LiveSync mixin adds the following nodes and properties to the jcr:content node of the Live Copy page: CQ 5. Node Types. and Properties that are specific to MSM.10 Multi Site Manager for Developers This document describes: • What happens in the repository when you set up MSM. 10. The second part describes how MSM works at the repository level. Node Types.1. It adds the following properties to the jcr:content node of the Live Copy page: cq:lastRolledout date and time of the last rollout cq:lastRolledoutBy indicates who performed the last rollout cq:msmSyncState not used anymore 10. for instructions on setting up MSM.

10. The default values are rollout.1. cq:master String defining the path of the Blueprint. • the cq:LiveSyncConfig and the cq:LiveSyncAction nodes (see the following description).1.3 cq:LiveSyncConfig node and node type The cq:LiveSyncConfig node is of type cq:LiveSyncConfig and has the three following properties storing the configuration of the Live Copy page: cq:isDeep Boolean defining whether the Live Copy is only for the page (when false) or for the complete sub tree (when true). which has the following three properties: cq:lastRolledout. The default value is true. Page 71 of 106 CQ 5. modification.2 WCM Copyright 1993-2009 Day Management AG . which is the supertype of cq:LiveSync.Multi Site Manager for Developers • the three properties defined by the cqLiveRelationship mixin. or publish. It is not accessible through the Siteadmin of CQ5. cq:lastRolledoutBy and cq:msmSyncState. cq:trigger String defining the event triggering the synchronization.

Multi Site Manager for Developers 10.1. the cq:LiveSyncCancelled mixin is added to the jcr:content node of the page or to the paragraph node.1.1.4 cq:LiveSyncAction node and node type The cq:LiveSyncAction node is of the type cq:LiveSyncAction and defines the synchronization actions performed on the Live Copy page and on each node of its jcr:content node (paragraphs) when the Blueprint is rolled out.1. for example: /etc/workflow/models/dam/ update_asset. notify this node has a property called target defining whether the notification has been enabled (when true). 10. Page 72 of 106 CQ 5. for example: surfer. The following nodes exist by default: mandatory this node has a property called target defining the group that has read-only access to the Live Copy. Each of its child node is an action: its name is the action name and its node type is cq:LiveSyncAction. It must match one action in the client side action set and one server synchronization action service.5 cq:LiveSyncCancelled mixin When a Live Copy is suspended.2 WCM Copyright 1993-2009 Day Management AG . the Live Copy is cancelled for the complete sub tree. workflow this node has a property called target defining the path of the workflow that is started when the synchronization actions are triggered. updateContent this node has a property called status defining whether modifications to the Blueprint will be propagated (when true). The cq:LiveSyncCancelled mixin adds the boolean property cq:isCancelledForChildren: when true. This property is not accessible through the Siteadmin of CQ5.

a cq:LiveSyncConfig node and a cq:LiveSyncAction node are created under the jcr:content node of the Live Copy root page and only there. • When a synchronization action is configured on a Live Copy page. following mechanisms take place in the repository: • When a Blueprint is created. • When a Live Copy is created. 10.6 cq:BlueprintAction node and node type The cq:BlueprintAction node is the equivalent of the cq:LiveSyncAction node on the Blueprint side. notify this node has a property called target defining whether the notification has been enabled (when true). a cq:Page node is created under /etc/blueprints. a cq:BlueprintAction node is created under the jcr:content node of the page. a cq:LiveSyncConfig node and a cq:LiveSyncAction node are created under the jcr:content node of the Live Copy page. Each one of its child node represents an action: its name is the action name and its node type is cq:LiveSyncAction. • When a synchronization action is configured on a Blueprint page. For each action a cq:LiveSyncAction node is created under the cq:BlueprintAction node. It must match one action in the client side action set and one server synchronization action service. The following nodes exist by default: mandatory this node has a property called target defining the group who has a read only access to the Live Copy. for example: /etc/workflow/models/dam/ update_asset.2 MSM mechanisms in the repository When configuring synchronization actions. It defines the synchronization actions performed on the Live Copy page and on each node of its jcr:content node (paragraphs) when the Blueprint is rolled out.1.2 WCM Copyright 1993-2009 Day Management AG Page 73 of 106 .1.Multi Site Manager for Developers 10. workflow this node has a property called target defining the path of the workflow that is started when the synchronization actions are triggered. for example: surfer.1. updateContent this node has a property called status defining whether modifications to the Blueprint will be propagated (when true). CQ 5.

MSM.wcm.form.msm. • otherwise.wcm.wcm.msm.MSM.msm. The code for CQ.MSM. If for this given Live Copy page.1.msm.2 Extending MSM Functionalities 10. the actions are inherited from the first parent page with a cq:LiveSyncAction node stored to it.2 WCM Copyright 1993-2009 Day Management AG . It is rendered into a CQ.MSM. • if the action exists on the Live Copy page. 10.ACTIONS = [ CQ.Multi Site Manager for Developers • The configuration of a Live Copy page is defined as follows: • if a cq:LiveSyncConfig node is stored under its jcr:content node.2.wcm.2.wcm.ACTIONS and removing an action from it. • otherwise.msm.msm. the Blueprint action replaces it and is performed.1 How to extend synchronization actions The set of synchronization actions available in the Create Site and Create Live Copy dialogs or in the Live Copy and the Blueprint tabs is extensible: custom actions can be added or complete actions set can be refactored. the cq:LiveSyncCancelled mixin is added to the jcr:content node of the page or to the paragraph node. the actions are taken from the cq:LiveSyncAction node.FieldSet. Page 74 of 106 CQ 5. CQ.Ext. 10. • The actions to be performed on a Live Copy page are defined according to the following process: 1. CQ.UpdateContentAction.MSM. the configuration is taken from this cq:LiveSyncConfig node.msm.wcm. CQ.MSM.UpdateContentAction. CQ.msm.wcm.1. CQ.wcm.WorkflowAction and CQ. the configuration is inherited from the first parent page with a cq:LiveSyncConfig node stored to it.MandatoryAction are objects representing the default configurations for standard synchronization actions.wcm.ACTIONS and reordering the actions within it.ACTIONS looks as follows: CQ.NotifyAction.msm.1 How to change the order of appearance of an action You can customize the order of the actions by editing the array CQ.MSM.MSM.wcm. • When a Live Copy is suspended. CQ.msm.MSM.2. CQ.MSM.msm. an action is defined on its Blueprint page (it has a cq:LiveSyncAction node stored to it): • if the action does not exist on the Live Copy page. 10.NotifyAction. In a first step: • if a cq:LiveSyncAction node is stored under its jcr:content node.MSM.MSM. the Blueprint action is added to the action set and is performed.wcm.msm.wcm.MandatoryAction ].msm.MSM.WorkflowAction.ACTIONS is a static JavaScript array that contains client-side configuration from the synchronization actions.2 How to remove an action You can remove an action by editing the array CQ. 2.wcm.

proceed as follows: 1. • edit the property dependencies and set cq.1 Client side To add a new synchronization action on the client side.msm. In CRX Explorer. Type = String. "lazyInit": false. two parts have to be configured: • the JavaScript client side • the custom synchronization action must be deployed on the server The following procedure shows you how to add a new synchronization action called "Mandatory Structure": the user selects a user-group that will be able to modify the Live Copy page content but will not be able to delete or move the page. Page 75 of 106 CQ 5.wcm.getMessage("Mandatory Structure for"). 4.edit as Value.Multi Site Manager for Developers 10.js 2.txt file with the following code and store it under /apps/myApp/widgets (for example with WebDAV): #base=source myMsmActions. Then: • edit the property categories and set cq.3.MSM.MandatoryStructureAction = { "xtype": "combo". 5. "stateful": false. "fieldLabel": CQ. "minChars":0. "typeAhead":true. Type = nt:folder. Create a new node under /apps/myApp/widgets: Name = source.I18n. Create a new node under /apps/myApp: Name = widgets. 10. Note To connect to the CRX repository using the WebDAV protocol. "name": "actionMandatoryStructure". To do so. "triggerAction":"all".2 WCM Copyright 1993-2009 Day Management AG . Name = myApp. Type = cq:ClientLibraryFolder. Create the myMsmActions.wcm.1.widgets as Value. "actionName":"msm:actionMandatoryStructure".js file with the following code and store it under /apps/myApp/ widgets/source (for example with WebDAV): CQ. "emptyText": "". • add a new property: Name = sling:resourceType. create a new node under the /apps node. "editable":true. "inputType":"text". Create the js.2. 3. Value = widgets/ clientlib.1. Type = sling:Folder. "hiddenName": "msm:actionMandatoryStructure/target".3 How to create an action You can create a new action. "displayField":"name".2. check the CRX documentation on WebDAV access. "queryParam": "filter".

wcm. "fields":["name".data.. "method":"GET" }).msm. '<div class="cq-msm-list-entry cq-msm-mandatory-listentry">{[values. "itemSelector" :"div.id: values. "store": new CQ.name]}</div>'.wcm.data. Select the Live Copy tab to view the newly created widget: Page 76 of 106 CQ 5.Ext.Ext.name==""? values. // Adds the new action to the CQ.push(CQ. click Page Properties."). "id":"id". '</tpl>'). "totalProperty":"results"."id"]}) }). In CQ5.I18n.msm. open a Live Copy page. In the Page tab of the sidekick. The project structure looks as follows in CRX Explorer: 7.cq-msm-mandatory-list".HttpProxy({ "url": "/bin/security/authorizables. "tpl" :new CQ.wcm. 6.json?limit=25&hideUsers=true". '</div>'. "reader": new CQ.Ext.MSM.2 WCM Copyright 1993-2009 Day Management AG .. "proxy": new CQ..MSM.data.Ext.ACTIONS array CQ. "defaultValue": "" }.Store({ "autoLoad":false.JsonReader({ "root":"authorizables".msm.Multi Site Manager for Developers "fieldDescription": CQ.MandatoryStructureAction).getMessage("Select the groups that will not be able to modify the Live Copy structure.">'. '<div class="cq-msm-list cq-msm-mandatory-list">'.MSM.XTemplate( '<tpl for=".ACTIONS.

select New.2.3. then click Next. In the dialog.2 Server side To implement the new action on the Server side. Check the Create a simple project box and the Use default Workspace locations box.day. In Eclipse.cq5. expand the Maven folder. 1. Click Finish.2 WCM Copyright 1993-2009 Day Management AG Page 77 of 106 . select Maven Project and click Next.mymsm • Artifact Id: core • Name: CQ5 MyMsm Core • Description: This is the CQ5 MyMsm Core 5. then Other..Multi Site Manager for Developers 10. 4. . 3. create the Core Maven project: 1.. CQ 5. 2. Define the Maven project: • Group Id: com. click File. In the Menu bar. proceed as follows: Note Refer to the section called “Installing Eclipse” for installing and setting up Eclipse with a Maven plugin.1.

cq5.version=${pom.0.0 http://maven.0.apache.class files compatibility • Source compatibility 3.felix</groupId> <artifactId>maven-scr-plugin</artifactId> <version>1.w3. 3.5</source> <target>1. Click OK.1-SNAPSHOT</version> <description>This is the CQ5 MyMsm Core</description> <packaging>bundle</packaging> <build> <plugins> <plugin> <groupId>org.3</version> <extensions>true</extensions> <configuration> <instructions> <Export-Package> com.mymsm.org/POM/4.xml with the following code: <project xmlns="http://maven.5</target> </configuration> </plugin> <plugin> <groupId>org.0</modelVersion> <groupId>com. 4. Right-click the core project.maven.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <version>1. select Properties.apache. Replace the code in the pom.org/2001/ XMLSchema-instance" xsi:schemaLocation="http://maven.org/ maven-v4_0_0.version} </Export-Package> </instructions> </configuration> </plugin> <plugin> <groupId>org. In the dialog window. 2.apache.apache.day.mymsm</groupId> <artifactId>core</artifactId> <name>CQ5 MyMsm Core</name> <version>0.0.apache.day.4.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.2 WCM Copyright 1993-2009 Day Management AG .*.org/POM/4. Select Java Compiler and set following properties to 1.5: 1.0" xmlns:xsi="http://www.cq5. click Yes.apache.8</version> <executions> <execution> <id>generate-scr-scrdescriptor</id> <goals> <goal>scr</goal> </goals> </execution> </executions> </plugin> </plugins> Page 78 of 106 CQ 5.xsd"> <modelVersion>4.5: • Compiler compliance level • Generated .0. Set the Java Compiler to version 1.Multi Site Manager for Developers 2.0.

0.osgi</groupId> <artifactId>osgi_R4_core</artifactId> <version>1.day.6</version> <scope>provided</scope> </dependency> <dependency> <groupId>com.sling</groupId> <artifactId>org.osgi</groupId> <artifactId>osgi_R4_compendium</artifactId> <version>1.2.cq.day.day.sling</groupId> <artifactId>org.2-incubator</version> <scope>provided</scope> </dependency> <dependency> <groupId>com.client</artifactId> <version>1.day.api</artifactId> <version>2.2.day.22</version> <scope>provided</scope> </dependency> <dependency> <groupId>com.sling.2</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.2.api</artifactId> <version>2.2 WCM Copyright 1993-2009 Day Management AG .wcm</groupId> <artifactId>cq-wcm-api</artifactId> <version>5.sling.sling.day.0.0</version> <scope>provided</scope> </dependency> </dependencies> <repositories> <repository> Page 79 of 106 CQ 5.22</version> <scope>provided</scope> </dependency> <dependency> <groupId>com.cq</groupId> <artifactId>cq-commons</artifactId> <version>5.crx.cq</groupId> <artifactId>cq-security</artifactId> <version>5.apache.20</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.4.cq</groupId> <artifactId>cq-security-api</artifactId> <version>5.3-incubator-R746167</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.0</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.apache.apache.apache.Multi Site Manager for Developers </build> <dependencies> <dependency> <groupId>com.jcr.sling</groupId> <artifactId>com.2.crx.

m2 directory: copy/paste the following code into the <servers></servers> tags: <server> <id>day-external-central</id> <username>cq5_training</username> <password>tr41n1ng</password> </server> 5.org/repo/m2-incubating-repository</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories> </project> 4. 2. right-click src/main/java.day.cq5. Create the package com.apache.com/archiva/repository/day-central</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> <pluginRepository> <id>apache-incubating-repository</id> <name>Apache Incubating Repository</name> <url>http://people.day. Under core.mymsm that will contain the Java classes under core/ src/main/java: 1. Name it com. CQ 5.mymsm and click Finish.com/archiva/repository/day-central</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> <repository> <id>apache-incubating-repository</id> <name>Apache Incubating Repository</name> <url>http://people.Multi Site Manager for Developers <id>day-external-central</id> <name>Day Central Repository</name> <url>http://repo.day.2 WCM Copyright 1993-2009 Day Management AG Page 80 of 106 .day.org/repo/m2-incubating-repository</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>day-external-central</id> <name>Day Central Repository</name> <url>http://repo. then Package. Add the credentials into the settings.apache.xml file of your <maven-install-dir>/.cq5. select New.

ActionConfig.Node.cq5.ComponentContext.wcm.component metatype="false" name="com.NameConstants.cq. com. import org.day. Denied ACL are: <ul> * <li>ActionSet.cq.day.CRXSession.api.wcm.description" * @scr.day.day.LiveRelationship.apache.wcm.cq. } Page 81 of 106 CQ 5. com.msm. /** * Set read-ony to group defined in the action config of the relationship (for pages only). under core/src/main/java.cq.api.cq. com.day.reference */ @SuppressWarnings("UnusedDeclaration") private ActionManager actionManager. com.mymsm.cq5.util.service. import import import import import import import import import import import com.wcm.security.ACTION_NAME_REMOVE</li> * <li>ActionSet.ACTION_PARAM_TARGET}.day.resource. } protected void deactivate(ComponentContext context) { actionManager.registerAcion(this).day.cq5.wcm.MandatoryStructureAction" immediate="true" * label="%mandatoryaction.day.resource.util.cq.crx.msm.mymsm. then Class.api.ACTION_NAME_SET_PROPERTY</li> * <li>ActionSet.day. com.day.WCMException.day.LiveAction.api.ActionSet. Create the Java class MandatoryStructureAction: 1.service interface="com.unregisterAcion(this).security.msm.java. import org.Resource. In Eclipse.Multi Site Manager for Developers 6. right-click the com.day. In MandatoryStructureAction. com. Eclipse creates and opens the file MandatoryStructureAction.api. /** * @scr.wcm. com. com.sling.ACTION_NAME_ACL_MODIFY</li> * </ul> * @scr.cq. //name of the request parameter used to get/post action properties private String[] properties = {MandatoryStructureAction.cq. 2.api. import javax.api.cq.api.mymsm package. public static final int ACTION_RANK = 602.ActionManager.day.apache.CRXPolicyManager.sling. import org. In the dialog window.PageManager.msm. select New.day. com.wcm.osgi.jcr.name" description="%mandatoryaction. //name of the request parameter used to get/post action properties public static final String ACTION_PARAM_NAME = "msm:actionMandatoryStructure".java replace the existing code with the following: package com.api.api.api. name the Java Class MandatoryStructureAction and click Finish.ResourceResolver.component.day. public static final String ACTION_PARAM_TARGET = "target".cq. 3.Page.wcm.msm. com.LiveAction" */ public class MandatoryStructureAction implements LiveAction { //name of the action in the repository public static final String ACTION_NAME = "mandatoryStructure".cq.2 WCM Copyright 1993-2009 Day Management AG . protected void activate(ComponentContext context) { actionManager.wcm.

action is executed only for a page.adaptTo(Node.enact(p.ACTION_NAME_SET_PROPERTY. } public void execute(ResourceResolver resolver.getPath(). Node slaveNode = r != null ? r. ActionConfig config.getResource(relation.getNode(resolver. relation.adaptTo(PageManager.create(new String[]{ ActionSet.class).getName()) && slaveNode.hasProperty(ACTION_PARAM_TARGET)) { String target = config.ACTION_NAME_ACL_MODIFY}) ).isCancelled() && config != null) { if (config.getSession()). // ActionSet. LiveRelationship relation.getProperty(ACTION_PARAM_TARGET).ACTION_NAME_REMOVE.isNodeType(NameConstants.NT_PAGE)) { //at this point.getParent().getContainingPage(resolver.getStatus(). boolean autoSave) throws WCMException { try { if (!relation.getTargetPath()). } public int getRank() { return ACTION_RANK. } public String[] getPropertiesNames() { return properties. } public String getParameterName() { return ACTION_PARAM_NAME. Save the changes. re). } } } 4.equals(slaveNode.class): null.getPath())). if (target != null && !target. // ActionSet. Page p = pm. PageManager pm = resolver.//Utils.2 WCM Copyright 1993-2009 Day Management AG . if (p != null) { CRXPolicyManager policyMgr = new CRXPolicyManager((CRXSession) slaveNode.getResource(slaveNode.NN_CONTENT.equals("")) { Resource r = resolver. Page 82 of 106 CQ 5. false.getTargetPath()). target. } } } } } } } catch (Exception re) { throw new WCMException("Error while executing " + getName() + " action". if (slaveNode != null) { //set mandatory only on pages if (NameConstants. ActionSet. Note The synchronization action parameter name must match the value returned by LiveAction#getParameterName. policyMgr.Multi Site Manager for Developers public String getName() { return ACTION_NAME.

select a group beside Mandatory Structure for. 2. In CRX Explorer.jar (containing the compiled class) is created under core/target. The bundle core-0. • which node types are part of the rollout process. the ranks are: • UpdateContentAction = CUDAction service: 301 • NotifyAction = NotifyAction service: 501 • MandatoryAction = MandatoryAction service: 601 • WorkflowAction = WorkflowAction service: 701 7. As you can see in the above code.day. 2.wcm. then Maven Install. In the Live Copy tab of the Page Properties.2.msm. select Run As. To do so: 1.Multi Site Manager for Developers A synchronization action is an OSGI service that must implement the interface com. 9. In Configuration. The actions are executed by following the order of the ranks. Log out of CQ5 and log in as a member of the selected group.cq.2 WCM Copyright 1993-2009 Day Management AG . In your browser. that is. For the default synchronization actions.0. 8. Copy the bundle core-0. Rollout the corresponding Blueprint page. Name = install. Click OK. Page 83 of 106 CQ 5. Open a Live Copy page. 2. open the Apache Felix Web Management Console Configuration (for example: http://localhost:4502/system/console/configMgr).0. a rank has been set to the action (the value of the field ACTION_RANK).api.jar and store it under /apps/myApp/install (for example with WebDAV). Right-click the core project. 3. Type = nt:folder. 4. Compile the Java class and create the bundle: 1. which synchronization actions are performed on the node. Refresh the Live Copy page: you can now edit the page but not delete it. 10.1-SNAPSHOT. In your browser.LiveAction and must register itself to the RolloutManager. select CQ WCM Rollout Manager.2 How to define the properties and the nodes that are copied to the Live Copy The MSM in CQ5 lets you define: • which properties are copied by the Update Content synchronization action. 10.1-SNAPSHOT. in CQ5: 1. create a new node under /apps/myApp.

Type = String. 3. the Chapters selection is not required in the Create Site wizard but only the Languages selection.2. Excluded Nodetypes java regexes that define the node types to exclude from rollout. 10. it will not be included by the rollout manager. Type = String. If the node type matches one regex. remove the node /etc/blueprints/geometrixx/jcr:content/ dialog/items/tabs/items/tab_chap. Navigate to /libs/wcm/msm/templates/blueprint/defaults/livecopy_tab/ items and create a new node.2 WCM Copyright 1993-2009 Day Management AG . it will not be copied. Value = hidden Page 84 of 106 CQ 5. In CRX Explorer. Value = msm:chapterPages • Name = value. To remove this step in the default Geometrixx blueprint: 1. Type = cq:Widget. Name = chapters.3 How to remove the "Chapters" step in the "Create Site" wizard In some cases. Add following properties to the new node: • Name = name. Type = String. Value = all • Name = xtype. If the property name matches one regex. Configure these two parameters: Excluded Properties java regexes that define the property names to not copy.Multi Site Manager for Developers 3. 2.

11 How to Create a Fully Featured Internet Website The tutorial "How to Create a Fully Featured Internet Website" enables you to create a fully featured website with CQ5. Page 85 of 106 CQ 5.2 WCM Copyright 1993-2009 Day Management AG .

PictHandler image/pict StandardImageHandler com.standard.day.handler.day.mp3.impl.impl. for example thumbnail generation or metadata extraction.1 Default Media Handlers The following media handlers are available within CQ5 DAM and handle the most common MIME types (click the handler name to access its Javadocs): Table 12. Specific tasks can be performed on assets by either extending/creating workflows.dam.TextHandler text/plain com.dam.standard.Mp3Handler audio/mpeg com.ZipHandler application/java-archive application/zip PictHandler com.cq. Page 86 of 106 CQ 5. Handler name TextHandler PdfHandler JpegHandler Service Name (in the System Console) Supported MIME types com.JpegHandler image/jpeg image/jpg Mp3Handler ZipHandler com.day. For example.core.cq. extending/creating media handlers or disabling/ enabling media handlers. Media handlers are services inside CQ5 DAM that perform specific actions on assets.day.dam.core.StandardImageHandler image/gif image/png application/photoshop image/jpeg image/tiff image/x-ms-bmp image/bmp GenericAssetHandler com.handler.day.standard.dam.handler.impl. then delegates the specific tasks to the media handlers.pict. • creating a thumbnail image out of the asset.12 DAM Media Handlers CQ5 DAM comes with a set of default workflows and media handlers to process assets. Media handlers are usually used in combination with workflows.zip.day.core.cq.PdfHandler application/pdf com.standard.core.cq.handler.dam. The workflow defines the general tasks to be executed on the assets.handler.cq.pdf. when an MP3 audio file is uploaded into CQ5. 12.handler. Most common MIME types are supported within CQ5.day.handler. a workflow triggers an MP3 handler that extracts the metadata and generates a thumbnail.handler.dam.dam.cq.day.2 WCM Copyright 1993-2009 Day Management AG .1.cq.dam.GenericAssetHandler handler was found to fallback in case no other extract data from an asset All the handlers perform the following tasks: • extracting all available metadata from the asset.cq.impl.

when a PDF document is uploaded into the /var/dam/geometrixx/documents folder. In your browser. Click the link com.2 WCM Copyright 1993-2009 Day Management AG Page 87 of 106 . By default. the pdf handler: • extracts the metadata CQ 5. navigate to http://<host>:<port>/system/console/components.2 Using Media Handlers in Workflows to perform tasks on Assets Media handlers are services that are usually used in combination with workflows.impl. It is possible to view the active media handlers: 1.dam.DAM Media Handlers Beside those tasks other MIME type specific tasks are available: refer to the Javadocs for detailed information. 2.AssetStoreImpl. A list with all the active media handlers is displayed.core.cq.day. For example: 12. the default DAM Asset Sync and Metadata Extractor process: • copies the document into the /content/dam/geometrixx/documents folder • asks the AssetStore for a handler that is able to process pdf Then. CQ5 has the following default workflows to process assets: • DAM Asset Sync and Metadata Extractor • DAM Delete Asset • DAM Delete Dam Asset under /content/dam • DAM Sub Asset Processor • DAM Update Asset Existing workflows can be extended and new ones can be created to process assets according to specific requirements. 3.store.

CQ 5.DoNothingProcess) that does not affect the asset and install it in CQ5.2 WCM Copyright 1993-2009 Day Management AG Page 88 of 106 .pdf. The workflow will look as follows: Proceed as follows: 1. the asset reaches the End step. Create a service (for example com.DAM Media Handlers • generates a thumbnail • creates sub-assets: each page of the document becomes a sub-asset The following example shows how to disable the sub-asset creation for PDF documents by extending the workflow: the Process Subassets step will be replaced by an OR-split that checks the asset filename: • if it ends with . the asset goes through a Process Subassets step that generates sub-assets.day. Tip You can refer to the section called “Example: create a specific Text Handler” to see how to create a service and install it in CQ5. This service will be used to bypass the sub-asset creation step.pdf.cq5.myprocess. • if it does not end with .

getPayloadType() == "JCR_PATH") { var path = workflowData. 3.dam.core.cq5. create a file under /etc/workflow/scripts and call it myPdfCheck. Copy-paste the following code into it: function check() { if (workflowData.CreateSubAssetsProcess • Process Arguments: /etc/workflow/models/dam/sub_asset_processor • Timeout: Off • Timeout Handler: • Title: Process Subassets 6. 4. 2.2 WCM Copyright 1993-2009 Day Management AG . Delete the Process Subassets step that comes after the end of the OR Split.ecma. Create an ecma-script function that is set to true if the filename ends with . In your browser. Click the configuration button of the right step of the OR Split and set the following properties in the right panel: • Type: select Process • Description: This process does not affect the asset and leads to the next step • Handler Advance: true • Implementation: type the name of the service here (the service created in step 1. 5. 8.cq. Select the Models tab and edit the DAM Asset Sync and Metadata Extractor workflow. Click the configuration button of the left step of the OR Split and set the following properties in the right panel: • Type: select Process • Description: This process creates subassets if handler is able to extract subassets • Handler Advance: true • Implementation: select com.DoNothingProcess) • Process Arguments: • Timeout: Off • Timeout Handler: • Title: Do Nothing 7. to false otherwise: 1. Drag and drop an OR Split between the Thumbnail Creation step and the Process Subassets step.html).myprocess.day. In CQDE. open the Workflow Console (for example: http://localhost:4502/ libs/workflow/content/console.toString(). Page 89 of 106 CQ 5.process.getPayload().pdf.day. for example: com.DAM Media Handlers 2.

its metadata are extracted and thumbnails are generated. 9. set the rule of the Process Subassets step of the OR Split: type /etc/ workflow/scripts/myPdfCheck. 2. From now on.handler. For example: com.day. whenever a pdf file is uploaded into the /var/dam/geometrixx/documents folder.getPath().standard.pdf") >= 0) { return true.getPayloadType() == "JCR_PATH") { var path = workflowData. Refresh the page: a Disabled icon is displayed beside the media handler.ecma as value of the Rule. } } else { return true.2 WCM Copyright 1993-2009 Day Management AG .ecma.cq.getItem(path). the file is copied into /content/dam/geometrixx/documents. Copy-paste the following code into it: function check() { if (workflowData. var node = jcrSession. 10. When the media handler is disabled.pdf") >= 0) { return false. Save the file. } else { return true.dam.DAM Media Handlers var node = jcrSession. 12.indexOf(". Create an ecma-script function that is set to true if the filename does not end with . Page 90 of 106 CQ 5. Click the Disable button right beside the name of the media handler. In your browser. click the Enable button beside the name of the media handler.mp3. To enable/disable a media handler: 1. Save the file. } } else { return false. navigate to http://<host>:<port>/system/console/components.ecma as value of the Rule. 12. if (node. its tasks are not performed on the assets.Mp3Handler. } } 3.getPayload().getItem(path).toString(). 2. In your browser. Subassets are not created anymore. } } 3. 4. Save the workflow. create a file under /etc/workflow/scripts and call it myNotPdfCheck. to false otherwise: 1. } else { return false.pdf. if (node. In CQDE.3 Disabling/Enabling a Media Handler The media handlers can be disabled or enabled through the Apache Felix Web Management Console.getPath(). To enable the media handler. 11. Set the rule of the Do Nothing step of the OR Split: type /etc/workflow/scripts/ myNotPdfCheck. 3.indexOf(".

Adding a new mime type requires to implement this interface.handler. Here is an example template: package my.1 Important Classes and Interfaces The best way to start an implementation is to inherit from a provided abstract implementation that takes care of most things and provides reasonable default behaviour: the com. for creating thumbnails and extracting metadata.AssetHandler Interface This interface describes the service which adds support for specific mime types.cq. For more information refer to the Javadocs.day. Note This class already provides an abstract service descriptor.cq. /** * @scr.core. So if you inherit from this class and use the maven-sling-plugin.AbstractSubAssetHandler Class: This class serves as basis for all other asset handler implementations and provides common used functionality plus common used functionality for subasset extraction For more information refer to the Javadocs.dam.service */ public class MyMediaHandler extends com.dam. it is necessary to create a new media handler.dam.AbstractAssetHandler Class. com.AbstractAssetHandler Class This class serves as basis for all other asset handler implementations and provides common used functionality.core. This section describes how to proceed.core.4 Creating a new Media Handler To support a new media type or to execute specific tasks on an asset.2 Example: create a specific Text Handler In this section. The following methods need to be implemented: • extractMetadata(): this method extracts all available metadata.2 WCM Copyright 1993-2009 Day Management AG Page 91 of 106 .day. 12. The interface contains methods for importing and exporting the specific documents. For more information refer to the Javadocs.cq. com. make sure that you set the inherit flag to true.AbstractAssetHandler { // implement the relevant parts } The interface and classes include: com.day.api.4.dam.day.dam. you will create a specific Text Handler that generates thumbnails with a watermark.cq.component inherit="true" * @scr.day. • getMimeTypes(): this method returns the asset mime type(s). 12. • getThumbnailImage(): this method creates a thumbnail image out of the passed asset.DAM Media Handlers 12.own.core.4.stuff.cq. Proceed as follows: CQ 5.

org/2001/ XMLSchema-instance" xsi:schemaLocation="http://maven. select Maven Project and click Next.day.w3. then Other.====================================================================== --> <!-. 4.14</version> <relativePath>.org/maven-v4_0_0..P R O J E C T D E S C R I P T I O N --> <!-. .myhandler • Artifact Id: myBundle • Name: My CQ5 bundle • Description: This is my CQ5 bundle 5.====================================================================== --> <parent> <groupId>com.0. 2. 3. Click OK. click Yes. Define the Maven project: • Group Id: com.day.0. 2.0" xmlns:xsi="http://www. Set the Java Compiler to version 1.day.dam</groupId> <artifactId>dam</artifactId> <version>5.apache. Right-click the myBundle project. In Eclipse. 2.. select Properties.. create the myBundle Maven project: 1.5: • Compiler compliance level • Generated .apache.DAM Media Handlers Note Refer to the section called “Installing Eclipse” for installing and setting up Eclipse with a Maven plugin and for setting up the dependencies that are needed for the Maven project.cq5.apache.0.0.5: 1.cq.xml file with the following code: <project xmlns="http://maven.0</modelVersion> <!-. select New. 1.2 WCM Copyright 1993-2009 Day Management AG .cq5.org/POM/4.1-SNAPSHOT</version> <description>This is my CQ5 bundle</description> Page 92 of 106 CQ 5. In the dialog. then click Next.====================================================================== --> <!-. 3. In the dialog window./parent</relativePath> </parent> <!-. Click Finish.0 http:// maven.xsd"> <modelVersion>4.2.myhandler</groupId> <artifactId>myBundle</artifactId> <name>My CQ5 bundle</name> <version>0. click File.class files compatibility • Source compatibility 3. 4. In the Menu bar. expand the Maven folder.====================================================================== --> <groupId>com. Check the Create a simple project box and the Use default Workspace locations box.P A R E N T P R O J E C T D E S C R I P T I O N --> <!-. Select Java Compiler and set following properties to 1. Replace the code in the pom.org/POM/4.

B U I L D D E F I N I T I O N --> <!-.apache.dam</groupId> <artifactId>cq-dam-core</artifactId> <version>5.felix</groupId> <artifactId>org.====================================================================== --> <build> <plugins> <plugin> <groupId>org.cq</groupId> <artifactId>cq-commons</artifactId> </dependency> <dependency> <groupId>javax.DAM Media Handlers <packaging>bundle</packaging> <!-.10</version> <scope>provided</scope> </dependency> <dependency> <groupId>com.dam</groupId> <artifactId>cq-dam-api</artifactId> <version>5.myhandler </Export-Package> </instructions> </configuration> </plugin> </plugins> </build> <!-.compendium</artifactId> </dependency> <dependency> <groupId>org.cq.2 WCM Copyright 1993-2009 Day Management AG .day.cq.slf4j</groupId> <artifactId>slf4j-api</artifactId> </dependency> <dependency> <groupId>commons-lang</groupId> <artifactId>commons-lang</artifactId> </dependency> <dependency> <groupId>commons-collections</groupId> Page 93 of 106 CQ 5.jcr</groupId> <artifactId>jcr</artifactId> </dependency> <dependency> <groupId>org.====================================================================== --> <!-.10</version> <scope>provided</scope> </dependency> <dependency> <groupId>com.2.cq5.day.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <extensions>true</extensions> <configuration> <instructions> <Bundle-Category>cq5</Bundle-Category> <Export-Package> com.sling</groupId> <artifactId>maven-sling-plugin</artifactId> <configuration> <slingUrlSuffix>/libs/dam/install/</slingUrlSuffix> </configuration> </plugin> <plugin> <groupId>org.apache.day.D E P E N D E N C I E S --> <!-.apache.2.apache.felix</groupId> <artifactId>maven-scr-plugin</artifactId> </plugin> <plugin> <groupId>org.====================================================================== --> <!-.====================================================================== --> <dependencies> <dependency> <groupId>com.osgi.day.

slf4j.workflow</groupId> <artifactId>cq-workflow-api</artifactId> </dependency> <dependency> <groupId>com. import org. com.day. then Class.jcr.commons</groupId> <artifactId>day-commons-text</artifactId> </dependency> <dependency> <groupId>com.slf4j.cq. import org.cq5.core. import org.cq.BufferedImage. java.awt. Under myBundle.java. 3. com.ImageHelper.api.commons</groupId> <artifactId>day-commons-gfx</artifactId> </dependency> <dependency> <groupId>com.day.image.day. name the Java Class MyHandler and click Finish.InputStream. right-click the com.Font.day.Layer.jcr.IOException. Page 94 of 106 .cq5.Session.day.foundation.RepositoryException.io. import import import import import import java. Name it com.dam.dam.awt.Rectangle.image. In MyHandler.metadata.day. Create the Java class MyHandler: 1.image.myhandler package. com.LoggerFactory. under myBundle/src/main/java. import javax. java. com.InputStreamReader. right-click src/main/java.ExtractedMetadata.cq.io.wcm.day. import javax. In the dialog window. import javax.myhandler.Node.2 WCM Copyright 1993-2009 Day Management AG com. java.apache. java.commons.Color. java.day.day.jcr.myhandler and click Finish.wcm</groupId> <artifactId>cq-wcm-foundation</artifactId> <version>5. Create the package com.cq5.2.day.day.day. then Package. select New.cq.cq.AbstractAssetHandler.Logger.IOUtils.22</version> </dependency> </dependencies> </project> 4.io. 5.java replace the existing code with the following: package com. In Eclipse.myhandler that will contain the Java classes under myBundle/src/main/java: 1. import import import import import /** CQ 5.awt. select New.cq5.day. Eclipse creates and opens the file MyHandler. 2.io. 2.DAM Media Handlers <artifactId>commons-collections</artifactId> </dependency> <dependency> <groupId>commons-io</groupId> <artifactId>commons-io</artifactId> </dependency> <dependency> <groupId>com.

getDisplayText(text. } public ExtractedMetadata extractMetadata(Node asset) { ExtractedMetadata extractedMetadata = new ExtractedMetadata().setProperty("text".dam.getProperty("text"). 12). final String text = (String) metadata.AssetHandler#getMimeTypes() */ public String[] getMimeTypes() { return new String[] {"text/plain"}. } // create watermark and merge with text layer Layer watermarkLayer. setMimetype(extractedMetadata.service */ public class MyHandler extends AbstractAssetHandler { /** * Logger instance for this class. Font font = new Font("Arial". extractedMetadata. layer.read(buffer) != -1) { text += new String(buffer).2 WCM Copyright 1993-2009 Day Management AG .api. font. /** * Music icon margin */ private static final int MARGIN = 10. } catch (Throwable t) { log.black). t). asset).drawText(10. 12).class). Page 95 of 106 CQ 5. Color. */ private static final Logger log = LoggerFactory. text).component inherit="true" immediate="true" metatype="false" * @scr. Font.getLogger(MyHandler.closeQuietly(data). try { final Session session = node.length() > 0) { // commons-gfx Font class would throw IllegalArgumentException on empty or null text layer. 0). String displayText = this.setPaint(Color. InputStream data = getInputStream(asset).wordCount(text). 0.setMetaDataProperty("Word Count".ALIGN_LEFT. 10. char[] buffer = new char[4096]. 600.DAM Media Handlers * The <code>MyHandler</code> can extract text files * * @scr. } finally { IOUtils.wordCount).close(). 600. if(displayText!=null && displayText. String text = "". while (reader.getSession(). } return extractedMetadata. // create text layer final Layer layer = new Layer(500. long wordCount = this. displayText. } reader. } // ----------------------< helpers >---------------------------------------protected BufferedImage getThumbnailImage(Node node) { ExtractedMetadata metadata = extractMetadata(node). 500. 600.cq.error("handling error: " + t. try { // read text data InputStreamReader reader = new InputStreamReader(data). extractedMetadata.day.toString().handler.WHITE). /** * @see com.

} catch (RepositoryException e) { // TODO Auto-generated catch block e. boolean currentWhiteSpace = true. * * @param text * text to check * @param height * text box height (px) * @param fontheight * font height (px) * @return the text which will fit into the box */ private String getDisplayText(String text. watermarkLayer. 600)).trim().png").. for (int i = 0. return layer. if (lines. } } /** * This method counts the number of words in a string * * @param text the String whose words would like to be counted * @return the number of words in the string */ private long wordCount(String text) { // We need to keep track of the last character. } layer. int numOfLines = height / fontheight. while (i < j) { c = text. int fontheight) { String trimmedText = text.setX(MARGIN).charAt(i++).getImage(). String lines[] = trimmedText. "/var/dam/geometrixx/icons/ certificate.length(). } return cuttetText.length <= numOfLines) { return trimmedText.printStackTrace().merge(watermarkLayer).split("\n"). } catch (IOException e) { // TODO Auto-generated catch block e.DAM Media Handlers watermarkLayer = ImageHelper. layer. watermarkLayer. } prevWhiteSpace = currentWhiteSpace. int i = 0. } Page 96 of 106 CQ 5. i++) { cuttetText += lines[i] + "\n". long numwords = 0.setY(MARGIN). int j = text.2 WCM Copyright 1993-2009 Day Management AG .printStackTrace(). if we have two white spaces in a row we dont want to double count // The starting of the document is always a whitespace boolean prevWhiteSpace = true. i < numOfLines. } else { String cuttetText = "".crop(new Rectangle(510. } currentWhiteSpace = Character. if (currentWhiteSpace && !prevWhiteSpace) { numwords++.isWhitespace(c). } // ---------------< private >----------------------------------------------/** * This method cuts lines if the text file is too long. char c. int height. if (c == 0) { break.createLayer(session.

Right-click the myBundle project.jar and store it under /apps/myApp/ install (for example with WebDAV).2 WCM Copyright 1993-2009 Day Management AG . The bundle myBundle-0.DAM Media Handlers // If we do not end with a white space then we need to add one extra word if (!currentWhiteSpace) { numwords++.dam. 2. create a new node under /apps/myApp.day. its metadata are extracted and two thumbnails with a watermark are generated. 6. } } 4.impl. In your browser. From now on. Save the changes. Page 97 of 106 CQ 5. open the Apache Felix Web Management Console and disable the default text handler com.0. 7.jar (containing the compiled class) is created under myBundle/target.0. Copy the bundle myBundle-0.handler. 9. then Maven Install.1-SNAPSHOT. whenever you upload a txt file into CQ5 under the /var/dam/documents folder. Type = nt:folder.TextHandler. In CRX Explorer. 8.1-SNAPSHOT. select Run As. Name = install.cq. Note The new text handler is now active in CQ5. Compile the Java class and create the bundle: 1. } return numwords. the file is copied into /content/dam/documents.core.

Structure Later. While in the relational world the software industry has a lot of experience on how to model data. I would like to start filling this void by expressing my personal opinions on how content should be modeled. My bottom-line: Structure is expensive and in many cases it is entirely unnecessary to explicitly declare structure to the underlying storage.1. we are still at the early stages for the content repository space. He also leads the development of JSR-170. sometimes controversial views.1 Data Modeling . which is not just "my opinion" but something that is more generally applicable. Important Disclaimer: These guidelines express my personal. 13.3.1 Source The following details are ideas and comments expressed by David Nuescheler.David Nuescheler's Model 13. Initially.3. My App will automatically know to read the modification date from that same property again. the technology standard for content management. 13. Let's say I store the modification date of a blog post in a lastModified property. I am looking forward to debate these guidelines and refine them. a leading provider of global content management and content infrastructure software. Maybe. Further updates can also be seen on http://wiki. Further data constraints like mandatory or type and value constraints should only be applied where required for data integrity reasons.2 WCM Copyright 1993-2009 Day Management AG Page 98 of 106 . 13. 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.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.org/jackrabbit/DavidsModel. There is an implicit contract about structure that your application inherently uses. the Java Content Repository (JCR) application programming interface (API).13 Data Modelling 13.apache.1.1. CQ 5.1. I think Stefano pretty much sums this one up. hoping that this could some day graduate into something more meaningful to the developers community.1. Learn to love nt:unstructured (& friends) in development.1 Explanation I recommend not to worry about a declared data structure in an ERD sense.3 Seven Simple Rules 13. David is co-founder and CTO of Day Software AG. So consider this my quickly evolving first stab at it.1 Rule #1: Data First.1. there is really no need to declare that explicitly.

Data Modelling

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

13.1.3.1.3 Discussion
http://www.nabble.com/DM-Rule-#1:-Data-First,-Structure-Later.-Maybe.-tf4039967.html

13.1.3.2 Rule #2: Drive the content hierarchy, don't let it happen.
13.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.

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

13.1.3.2.3 Discussion
http://www.nabble.com/DM-Rule-#2:-Drive-the-content-hierarchy,-don't-let-it-happen.tf4039994.html

13.1.3.3 Rule #3: Workspaces are for clone(), merge() and update().
13.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.
CQ 5.2 WCM Copyright 1993-2009 Day Management AG

Page 99 of 106

Data Modelling

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

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

13.1.3.3.3 Discussion
http://www.nabble.com/DM-Rule-#3:-Workspaces-are-for-corresponding-nodes.-tf4040010.html

13.1.3.4 Rule #4: Beware of Same Name Siblings.
13.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.

13.1.3.4.2 Example
Use
/content/myblog/posts/what_i_learned_today /content/myblog/posts/iphone_shipping

instead of
CQ 5.2 WCM Copyright 1993-2009 Day Management AG

Page 100 of 106

Data Modelling

/content/blog[1]/post[1] /content/blog[1]/post[2]

13.1.3.4.3 Discussion
http://www.nabble.com/DM-Rule-#4:-Beware-of-Same-Name-Siblings.-tf4040024.html

13.1.3.5 Rule #5: References considered harmful.
13.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.

13.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 this 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.

13.1.3.5.3 Discussion
http://www.nabble.com/DM-Rule-#5:-References-considered-harmful.-tf4040042.html

13.1.3.6 Rule #6: Files are Files are Files.
13.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.

13.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 101 of 106

CQ 5.2 WCM Copyright 1993-2009 Day Management AG

More importantly. Keep also in mind that items can be identified by path.blogId . and as much as "symlinks" make way more sense for most users than hardlinks in a unix filesystem. mix:referenceable provides such a mechanism built into the repository.postId .7 Rule #7: IDs are evil.1. Much fewer than you might think though.2 WCM Copyright 1993-2009 Day Management AG . a path makes a sense for most applications to refer to a target node.date [Attachment] .jpg instead of: [Blog] .text .title .1. /content/myblog/posts/iphone_shipping/attachments [nt:folder] /content/myblog/posts/iphone_shipping/attachments/front. so people tend to use them in content models as well.1.html 13. 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.3.1.3.-tf4040063. It is true that some nodes need a stable identification throughout their live cycle.3.blogId . 13.2 Example use: /content/myblog/posts/iphone_shipping/attachments/front.Data Modelling and maybe the initial gut reaction would be to add a binary property containing the picture.jpg/jcr:content [nt:resource] 13. 13.jpg [nt:file] /content/myblog/posts/iphone_shipping/attachments/front. 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.nabble.3 Discussion http://www. Mostly for the wrong reasons through. 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.1 Explanation In relational databases IDs are a necessary means to express relations.postId .filename Page 102 of 106 CQ 5.7.7.6.3. so there really is no need to come up with an additional means of identifying a node in a stable fashion.com/DM-Rule-#6:-Files-are-Files-are-Files. If your content model is full of properties that end in "Id" you probably are not leveraging the hierarchy properly.author [Post] .attachmentId .

Data Modelling + resource (nt:resource) 13.3.-tf4040076.7.2 WCM Copyright 1993-2009 Day Management AG .nabble.1.com/DM-Rule-#7:-IDs-are-evil.html Page 103 of 106 CQ 5.3 Discussion http://www.

Select item and trigger search.2 WCM Copyright 1993-2009 Day Management AG . Select multiple paragraphs. debugClientLibs=true set in the URL.2. Select multiple paragraphs. Content Finder . Delete selected paragraph(s).1. Note: The cut paragraph will not disappear until it has been pasted to the new location. Select item and trigger suggestions for the selected path. Force default (browser) context menu. Table A. instead of replacing the asset in the destination.Paragraphs Alt+drag Shift-Click Ctrl-Click Ctrl-C Ctrl-X Close suggestions layer. Delete selected paragraph(s). drop on destination Content Window (Edit Mode) . Keyboard Shortcuts Location Page with a teaser component.Search down-arrow box right-arrow (on a suggested path) left-arrow (on a suggested path) Enter (on a suggested path) Esc Drag assets. Paste as reference. Keyboard Shortcuts Table A. Needed when too few characters have been entered to trigger the list automatically (this happens when 2 or more characters have been entered). Copy selected paragraph(s). Shortcut Ctrl-Alt-c Description Shows the clickstream cloud: collection of page tags related to clicks that the user has made and used to focus the teaser. The drop action produces a new paragraph. Page 104 of 106 CQ 5. Extended Keyboard Shortcuts Location Page Shortcut Description Ctrl-Shift-U with ? To see timing statistics for page loading. Select item and trigger suggestions for its ancestors (as in siblings of parent). Ctrl-V Alt-Ctrl-V Del Backspace Alt-right-click Paste paragraphs from clipboard. Cut selected paragraph(s).Appendix A. Trigger a suggestions list.

This security vulnerability can be exploited by malicious web users to bypass access controls. Page 105 of 106 CQ 5. Warning CQ5 example code is not protected against such attacks.1 Use the user session. Security Checklist This section deals with various steps you should take to ensure that your CQ5 installation is secure. B.Appendix B. not the administrative session This means you should use: slingRequest.getResourceResolver().2 WCM Copyright 1993-2009 Day Management AG .2 Check for Cross-Site Scripting (XSS) Cross-site scripting (XSS) allows attackers to inject code into web pages viewed by other users.class).adaptTo(Session. B.

Press the right-mouse button (or the left-mouse button if your mouse has been configured for left-handed use)...Appendix C. then press the A key. Licenses and Disclaimers.Actions When you see this. http://www.com if (weather == sunny) smile.. Press Ctrl+A. Page 106 of 106 CQ 5.you type the actual value needed. Formatting Conventions . or commands.1 Formatting Conventions The following tables detail formatting conventions used within this guide: Table C. User Input <Variable User Input> [Optional Parameter] Computer Output ls *.xml ls <cq-installation-dir> ls [<option>] [<filename>] ls: cannot access error. Mouse buttons. Logging and error messages. that you type. Ctrl+A Right-click Drag It means do this. Example of text. C. then release the mouse button at the new location (or the right mouse button if your mouse has been configured for left-handed use). User interface items.2 WCM Copyright 1993-2009 Day Management AG . An optional parameter.1. Copyright. Hold down the Ctrl key.. Formatting Conventions . Example of variable text . Example See the Microsoft Manual of Style for Technical Publications. Example of programming code. Click Save.2. Secondary-mouse button (usually the right-mouse button).Text Style Cross-reference GUI Item Keyboard shortcut Mouse Button Description Cross-reference to external documents.day. Link Code Link to anchor-points within the current document and/or external sources. Licenses and Formatting Conventions For all copyright statements and license agreements see Copyright. Hold down the left mouse button while moving the item.log: Table C. Keyboard shortcuts.

Sign up to vote on this title
UsefulNot useful