An Introduction to CQ5 for Architects

This is all really elementary stuff, but as an introduction to CQ5 it may help to put in context by identifying the requirements to run CQ5, the basic terminology used, and how certain areas operate.

System requirements

I'm not going to go over the product specification here as it's really well covered on the Adobe website and in more detail than I would care to add here, but basically CQ5 runs on Java. It should ideally use a Java 1.6 JVM.

The author will need to use a supported browser - on CQ5.4 this means IE7, IE8, Firefox 3.6, or Safari.

CQ5 does not require a separate database; it stores it's data in a CRX repository. By default this uses a file based persistence manager.

Components are not templates

Some factoids about components which are significant in terms of designing solutions using CQ5:

• Components are scripts which do something, and dialogs which allow the author to edit properties.
• Component scripts are usually JSP.
• Pages are rendered with components.
• Components can inherit from other components. When this happens they can replace the script or dialog from the parent component, or they can add extra scripts.

Users can add content components to the page by dragging components onto the page, and can move them around according to rules set in the components and the page design. Users can edit the components they have added and those embedded into the page by double-clicking or right-clicking on the page - this is where the component dialog comes into play.

Templates are not components

Templates are different to components in two major ways:

• Templates are items that authors can pick when creating a new page. Components are added to a page which already exists
• When a page is created, it basically copies the template into the content tree. This allows the page to be prefilled with data, contents, default page settings, and so on. Once a page is created, the template is not referenced (except to display the template name to the author in the list of pages).

A paragraph system is a special component that allows the authors to add and remove components. It operates much like a list and can be reordered by the author.

Author & Publish instances, and page activation / deactivation

Running copies of CQ5 are often known as instances. The main differences between author and publish instances are replication agent settings, anonymous access, workflow launchers, and the presence of author accounts. This is all set up automatically during installation.

Replication agents send the content to the publisher when the author activates or deactivates the page. It sends notification to the dispatcher from the publisher when a page is modified. This all happens using standard HTTP requests.

Dispatcher Cache

The dispatcher is a web server (Apache, IIS, and others) that caches content on disk so that it doesn't need to be requested from CQ5 every time. This improves performance. Effectively, it works in a similar manner to a reverse proxy. The publisher notifies the dispatcher of changes.

Pages with query strings and form post requests can not be cached. Scripts can also mark pages as non-cacheable by the dispatcher.

Workflows

Workflows can be triggered automatically using workflows launcher triggers, or manually by the authors. Steps can be manually actioned by users or process steps that run code or scripts. These processes can be developed in Java and placed in OSGi bundles or written using EcmaScript, a close relative of JavaScript.

Some workflows are considered special, such as 'request for activation' - this runs when an author tried to activate a page when they do not have sufficient permissions.

Java Code

The rules for Java in CQ5 are fairly simple:

• Java code for business logic belongs in OSGi bundles, as does anything that's more complex than basic output.
• The code is packaged in standard java.jar files either complied in a special way or with extra files added to specify the OSGi services. These jar files are known as bundles.
• New services are identified by their Java interface name. It is possible to extend the core product using dependency injection by creating Java classes that implement specific interfaces.

CQ5 uses Apache Felix as the OSGi framework, and Apache Sling as the web framework. The content repository conforms to the Java Content Repository specification 2.0, aka JCR2.

Conclusion

This is a fairly broad overview of the requirements and technical features of CQ5.There's much more to it than this short article could possibly hope to cover, especially the CRX repository which is a topic in itself. There's plenty to read on the the Adobe website about CQ5, and on the Apache Sling to cover the framework.

Day CQ5 Development Best Practices

Here's a quick reference list on some best practices for developing with Apache Sling and Adobe Day CQ5. Whether you view these as helpful hints, golden rules, or as definitive best practice guidelines, these should be followed during development and will help you to achieve a professional result with CQ5.

1. Avoid using loginAdministrative. Do you really need to run some code as superuser or is it more appropriate to use the contextual user? Remember that 'admin' can do anything and see everything, so you lose any security control over the situation. You also lose any audit of changes, as they will be logged as 'admin'. In general, if you create a repository session, you are responsible for closing that session. If you didn't create it you can assume that it will be closed later by the framework.
2. If using login or loginAdministrative, use logout. You need to remember to end any sessions created with 'loginAdministrative', otherwise you have a session leak and will run out of resources.
3. If not using loginAdministrative, don't logout. You shouldn't close sessions which you haven't explicitly created. Their lifecycle is managed by Sling.
4. Every call to getService should have an ungetService call. Each get call increments a counter and if we don't decrement the reference count it will not be able to release the service, potentially wasting resources.
5. If you are implementing servlets, be careful with implementing OptingServlet & Filter interfaces - they can break the POST requests needed by CRXDE.  
6. Break down logic into services and move as much code out of the JSP as possible into OSGi bundles. It's much easier to test OSGi bundles and makes the JSPs far easier to read. It'll also allow you to reuse the services as development progresses.
7. Use resourceResolver.map on all links in javascript and linked resources such as images - the link rewriter only does .html links and skips script blocks. This is essential if you want to do any kind of remapping of content.

There are also some rules which affect the CQ5 author...

1. Don't set body css color attribute - it hides labels in the dialogues if you set it to white. You should have an id or a class on your body element in your page, or a div element to contain your content.
2. Avoid inline styles unless you don't want to be able to reuse components. All styles should be kept in external stylesheet files.
3. Be careful with float css, it upsets the ExtJS based author system. It can cause element to overlap. It can also make it hard to click on elements to edit them. You might need to add css clear styles to subsequent elements to make things work.
4. Exceptions behave differently in CQ5 author and CQ5 publish, so make sure to use try/catch, value checking, and good exception handling practices. Make all your components fail independently, and not fail the whole page.
5. It's possible to create components without editing them by dragging them from the sidekick to the page. This doesn't set any data so make sure your code assumes that null is a possible value.
6. Always add a css style sheet for the rich text editor which matches your site design; it will make it much easier for your authors.

And finally, CQ5 Dispatcher considerations...

1. Anything with a query string is never cached. Anything which isn't a GET request is never cached. Pages with authentication are not cached.
2. Headers sent by CQ5 are not sent if the page is retrieved from the dispatcher cache. Content expiry, caching rules, and so on should be managed by the dispatcher server. This includes cookies.
3. You can cache everything else if you set the right rules in the dispatcher.
4. If you want to prevent caching by the dispatcher you can set a special header 'dispatcher: nocache'.
5. If you have remapping rules in /etc/map you'll need to add rewriting to the dispatcher web server using mod_rewrite or URL rewriting in IIS
6. Once it's cached by dispatcher, it stays cached until the publisher makes an invalidation call. Don't cache content which can change without author intervention.

Hopefully these rules will help developers avoid simple mistakes when working with JCR repositories, Apache Sling, and Abode Day CQ5. They might also be useful if you are doing code reviews too, as they are simple things to look out for. Finally, if you consider these rules when designing your solution, you might just be able to make your caching just that little bit more efficient or avoid CSS that is problematic in the author environment.