Antony Hutchison: Content Systems Architect. London, UK

Entries in day (2)

Sunday

Jan152012

CQ5 best practices for component development

Sunday 15 January 2012 at 12:00

Following on from my advice for best practices for developing with Adobe Day CQ5, here are some suggestions centred around component development - you should tailor these to fit your needs. They should help if you are unsure where to start. There's lots of technical documentation on the product itself and the core open source frameworks; elements of these are useful for developers, but there's scant information on methodologies or strategies you can apply when starting out. Some of this may also apply to other systems albeit with different no-go areas and so on.

Avoid copying components

Firstly, avoid modifying anything under /libs. Also avoid copying anything from /libs to /apps. There are a few reasons for this:

If you upgrade you will hate yourself for doing this. Your boss and co-workers may hate you too.
Changing /libs implies that you are either not going to version control it, or that you are going to. Either way leads to madness, unless you like code to go missing and have servers which behave differently or if you want to add half of the core product to subversion.

Copies to /apps should be VERY limited for a few significant reasons:

when you upgrade, you need to upgrade this code too if you want it to work or at the very minimum have the new features.
there's no way of quickly identifying these 'overlays'.
if you overlay something that is key, things go sour very quickly post-upgrade.
having two components with the same name in the same group breaks design mode in CQ5.4 - for me at least

Override the bare minimum

All components for paragraph systems should have a 'sling:superResourceType ' of 'foundation/components/parbase'. Development of derived components should be done using 'sling:superResourceType' where possible. An example might be creating a paragraph system that behaves differently. Say you want to make one where component display is inverted, so that new components are inserted at the top - this is a parsys with a 'sling:superResourceType' of 'foundation/components/parsys' and a customised script. There's no need to copy the whole component.

Component Organisation

A recommended structure for component definition is

/apps/<site-id>/components/page/<component>
/apps/<site-id>/components/content/<component>
/apps/<site-id>/src
/apps/<site-id>/install
/apps/<site-id>/widgets
/apps/<site-id>/nodetypes
/apps/<site-id>/templates/<template>

Of course, all of these are optional. Page rendering components explicitly defined in the templates are split from paragraph and non-whole-page components such as navigational bars. This is purely for the benefit of developers; it means it's possible to see at a glance if the component is used to render a whole page or if it might appear as part of a page - a useful distinction. It has another benefit, for example it allows a 'sitemap' paragraph component which lists in HTML format to exist as well as a machine-readable sitemap.xml page type for SEO - two very different things with the same name.

Composition of Page Types

A process of decomposition into sub-scripts is applied to the page rendering code to create a solid foundation which will allow extension of the basic type into more specifc page components:

/apps/<site-id>/components/page/base
/apps/<site-id>/components/page/base/base.jsp
/apps/<site-id>/components/page/base/head.jsp
/apps/<site-id>/components/page/base/body.jsp
/apps/<site-id>/components/page/base/header.jsp
/apps/<site-id>/components/page/base/content.jsp
/apps/<site-id>/components/page/base/footer.jsp

The base component extends the foundation page, with a 'sling:superResourceType ' of 'foundation/components/page'. 'base.jsp' basically sets the page doctype, outputs the <html> tags and includes head and body. Subsequenty, body.jsp includes header.jsp, content.jsp, and footer.jsp.

Extensible Page Components

This is the minimum for a base component which is extensible. We can easily make this better by adding other override-able scripts, such as adding an analytics.jsp or a meta.jsp. From this start point we can create a new component with a 'sling:superResourceType ' of '<site-id>/components/page/base', and the only thing we need to create is content.jsp

/apps/<site-id>/components/page/twocolumn/content.jsp
/apps/<site-id>/components/page/twocolumn/left.jsp
/apps/<site-id>/components/page/twocolumn/right.jsp

This obviously a two column layout. In order to separate content from code we should create a new component with a 'sling:superResourceType ' of '<site-id>/components/page/twocolumn', which now needs no scripts at all. It will derive all configuration and code from the super type, leaving us free to change the super type if we want a different representation (so long as the paragraph systems have the same names). We can also override the two column layout if we so chose, by creating a script which does something then including the overridden script. For example, we could create a /apps/<site-id>/components/page/contentpage/right.jsp script which displays a title component then includes the /apps/<site-id>/components/page/twocolumn/right.jsp script. This gives a great level of flexibility.

Content has a type

Remember that when content is being created, the component path is 'stamped' into the content so that Sling knows what script to use to render it. Always plan components so that an appropriate resource type is associated with the content. In our page example, it is much better that it is a 'content page' than a 'two column page' or even a 'base page' as the intent is that is it content. The fact that it displays in two columns is incidental, especially if in six months time a third column is added. It's much more future proof to use a layer of inheritance, but only if it doesn't add unnecessary complexity.

Favour composition over inheritance

Components is CQ5 should also favour composition over inheritance. If you want a list-image component for example, don't take a list component, copy it, and hack it to have an image. A reasonable approach is to create a new component and add the necessary components to it. When you upgrade CQ to a new version, you'll have no changes to make - it'll automatically use the new version. If you did it by creating a new component by forking code, you could find it difficult to get it working if there have been major changes to the original component.

I hope this guide has been useful. It's based on real world development practices and is the basis of any recommendation I would give at this time.

Antony |

4 Comments |

tagged

ECM,

WCM,

WCMS,

adobe,

best practices,

cms,

communique,

cq5,

day in

CQ5,

Content Management,

Development,

Guides,

Web Development

Friday

Jan062012

Day CQ5 Development Best Practices

Friday 6 January 2012 at 19:00

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.

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.
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.
If not using loginAdministrative, don't logout. You shouldn't close sessions which you haven't explicitly created. Their lifecycle is managed by Sling.
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.
If you are implementing servlets, be careful with implementing OptingServlet & Filter interfaces - they can break the POST requests needed by CRXDE.
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.
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...

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.
Avoid inline styles unless you don't want to be able to reuse components. All styles should be kept in external stylesheet files.
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.
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.
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.
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...

Anything with a query string is never cached. Anything which isn't a GET request is never cached. Pages with authentication are not cached.
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.
You can cache everything else if you set the right rules in the dispatcher.
If you want to prevent caching by the dispatcher you can set a special header 'dispatcher: nocache'.
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
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.

Antony |