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.

A method for writing content

 After some reading I started to realise that I need to have a method for writing articles and creating content, just like producing software or baking a cake. I’d seen it written that content is like a conversation with the reader, so where should I start? I should begin with a topic. Write something in the subject or headline box. Make it a bit questiony. Or answery. Or something.

Right, now I know what I’m writing. What next? Doing some research might help, with a bit of Googling, Binging, and Yahooing. I recommend that when I use my Mac, I should use Devon Agent for it’s natty search aggregation and ranking. I can put a search term in and it goes and finds information from all over the web. But sometimes I use a PC. Ok, it’s been a while since I checked it out, but last time I looked there was a tool called Copernicus that was rather useful and did something similar.

As for writing tools, I quite like MacJournal, and MarsEdit is good too. On Windows, I like Live Writer. I could use a web browser to want to blog. Outlook, Mail.app, or Thunderbird email work quite well. Anything with an autosave. On Linux I have no idea what you could use. (please send suggestions for tools in the form of links to Flickr, photos of names of applications written on napkins. best one gets a gold star).

Well of course I have a writing tool. Pen and paper. In fact it’s a rather lovely imitation Moleskine type notebook with coloured pages and a classic fountain pen (I ditched the pen quickly in favour of something less leaky...blotchy white work shirts isn't a good look). I prefer this to the real thing at the moment for three reasons. Firstly, it’s slightly cheaper. Secondly the coloured pages are ace for sectioning it up. Finally, it’s about twice as thick as a Moleskine so it’ll last longer and so it’ll get replaced less frequently. I think I got it from Rymans on the Strand but I'm not sure. Anyhow, now that I have a title and done some research, what now? First up, put down the traditional equipment, it’s not going to work for what I have in mind. Consider the English Language lessons you had in school, particularly the bit about stories having a start, middle, and end.

But I’m not writing fiction! It doesn’t matter. Everything is fiction unless it’s supported by evidence, and even then it’s open to interpretation and errors of omission. What is true to me might not be true at all. What matters is that you are writing and not just presenting tables of data, so you need to use structure and narrative, therefore it’s fiction. But rather than go down the rather boring start-middle-end style which will lead you into having something like “put water in kettle, boil kettle, pour into mug with teabag, remove bag, add milk; that’s how you make tea” where you have to read to the end to find out what it was all about, you should do it backwards. This also implies that it's a magical kettle that heats the water itself... it's too easy to miss details and forget vital steps.

If I try a end-middle-start approach, I’ll get a “Here’s how you make a perfect cup of tea...” type of linear guide which is great if that’s what I intended, but once a reader skips to the end I have lost them. I doubt that they will ever go back to the start unless they are desperate for a brew. Besides, what is a perfect cup of tea? Perfect by what standard? Anyhow, I’ll have saved them the embarrassment of reading something to the end then realising it wasn’t what they wanted. We all know everyone reads everything to the end.

Ok, I’ve done a whole bunch of words and arranged them into sentences, put the sentences into groups called paragraphs and shuffled these into reverse order. So that’s why a notebook isn’t going to work. Ok, it could if I’d used some scissors. Now all that is left is to merge the one or two sentence paragraphs into the larger blocks, read and edit it make it all make sense again, fix the spelling and grammar and fire in some hyperlinks preferably with a shotgun. Links are awesome. I can add embellishments too which may or may not be true just to make it a bit more excited, never mind the supporting evidence.

Optionally add a nice image from Flickr, and don’t forget to attribute it. Of course this will make for a fairly gibberish article. There are much better ways of writing for the web, and if this article inspired you then you should continue and read more on the subject.

And on that note, I need to have the start of the article here - the TL;DR version. So, this is an article about a method of writing. Would you like to know how to write an article? Read this one to find out.

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. 

How to fix Rosetta Stone error 1142 on Windows 7

A lot of people have complained or asked online how to get rid of the Error 1142 message when using Rosetta Stone on Windows. When Rosetta is starting up, it will quit with this message. The help and answers to these questions are not very helpful, ranging from the advice given in the official help which is to check the clock settings and firewall permissions, through to reinstalling Adobe Air and even the whole of Rosetta.

I found that the 'RosettaStoneDaemon' Windows service had been disabled on my PC. To fix this, open up the control panel, and go to administrative tools. You should see 'services' - right click on this and run as administrator (if you just open it you might not be able to make changes). Find the 'RosettaStoneDaemon', open it and set startup type to 'Automatic (delayed start)'. You can either reboot or start the service yourself, then close all these windows and go and have some fun in Rosetta - it should work just fine now.

Disclaimer: these are internals of the operating system, and changing setting in here can enable or disable features. Be careful, and if you're not sure what you are doing go find someone who does. If you break your computer, it's your own fault. 

Using IntenseDebate with Magnolia

Having comments on a website is kinda cool, but it’s way better if it’s a social comment system with a single shared identity across lots of websites. It’s really easy to set up in Magnolia as it’s built in. There’s basically three steps…

One. Get the ID from your intenseDebate account and put it in the configuration… under ‘templating kit’, site configuration, templates, prototype, mainArea, comments you will find a blank property for it.

Two, Create an article page, and hit ‘enable comments’ at the bottom of the page.

There is no step three. It really is that simple. If you don’t do step one, it tells you what to do (albeit with the wrong path). So long as you have an account with intenseDebate it’s very trivial. I tend to activate configuration changes from the author to the publish to keep them in sync as I find this easier, so if there was a step three it’d be ‘do this on the author and the publish copy of Magnolia’.

Enjoy adding comments to your pages. You can remove them too, which is really clever design as most sites don’t tend to have this option.

[applies to Magnolia CE 4.4.5]