Feb 22, 2013

Adobe CQ Package Share Contest: Announcing the Winners and Looking Closely at Criteria and Best Practices

Posted by Andrew Savory

I recently had the great honour of being part of the team reviewing the entries to the Adobe CQ Package Share contest. For those who missed it, Adobe was giving away a 15-inch Retina MacBook Pro for the best five packages submitted, based on the following judging areas: 40% creativity, 40% overall quality, and 20% reusability. We appreciated all who participated and submitted – thank you!

A package is just a zip file of content in a special format, and by uploading packages in Package Share you can make your custom code – such as templates, libraries, or even content – available to everyone using Adobe CQ in your company, or anyone else using CQ worldwide. It's also a great way to discover new functionality, and to quickly and easily download and install new CQ feature packs. For more background on packages and Package Share, check out my recent video.

Before I go further, I’m pleased to acknowledge the five winners of the contest, all of whom had strong submissions. I’ve included the names of their packages, and want to highlight that each will be available in Package Share soon. They are:

·         David from Katonah, NY - YouTube

·         Maciej from London, UK – CQ YouTube Integration

·         Mark from San Francisco, CA – Recap

·         Ruben from Brussels, BE – Template Manager

·         Tomasz from London, UK – SecureCQ

I thought it would be useful to share some of the criteria we applied when reviewing the entries. The criteria encapsulate best practice, and should help others build great packages to. We had 6 broad criteria that we applied:

  • Does the package work?
  • Does it offer some sort of cool feature or functionality?
  • Is the package nice looking?
  • How well was it packaged?
  • Is the package reusable?
  • How good is the code quality?

Let's look at them in more detail.

Does the package work?

The package might work for you, but what about for others? If you're expecting it to be shared, take the extra time to test your package on a vanilla install of CQ. Ideally, try it on several different versions – including our very latest and also including CQ 5.4 and 5.5. Remember, there's a metadata field for the versions of CQ you have tested against, so make sure it's filled out.

Another aspect of checking the package works is knowing where to begin. There are so many possible places to check – is it a component (try enabling it in Design view)? Is it a separate site (look for it under site admin)? Is it a tool (look for it under Tools)? You should make it obvious to anyone downloading the package – for example by providing a link to your package's entry point in the description. Remember the package is usually downloaded onto the server it will be installed on, so you can use relative links to ensure it always works, no matter what host or port CQ is running on.

Features and functionality

We had some very diverse entries, including enhancements to configuring and managing core CQ functionality; tools to query the underlying CRX repository; and components for managing content from third-party sites and services. The best packages offered functionality not available anywhere else. Cool is relative – one of the highest-scoring contributions made a tool-powered virtue out of  a site manager's dull copy-editing necessity. The lesson here is to think about how people use CQ, and what makes life easier for them. If you've solved a problem for your team locally, chances are your solution could help a much wider CQ user community.

Is the package nice looking, and how well was it packaged??

Beauty is in the eye of the beholder, but if your package included icons, screenshots, great design and a friendly user experience, then you probably did well. CQ gives you lots of opportunities to produce nice-looking packages. For example, you can include HTML tags in your description metadata, so take the time to make sure it is readable and highlights the key information.

Good packaging includes a wide range of criteria. Does the package store everything in a sensible place (for example in /apps)? Does the package make use of filters to include (or exclude) everything it should? Does the package duplicate existing files (which would be bad)? Does the package include suitable metadata?

Metadata is particularly important when you are sharing your packages, as it greatly aids discoverability. If people don't know what your package does or what is in it, they won't be downloading it. Give it a meaningful name: 'mypackage' is not much use, but 'svgcomponent' immediately gives users a clue as to what it does.

Make use of the version number, so people can tell when they need to update. List supported platforms, bug fixes, and provide external links wherever relevant. In fact, go through all of the tabs in the the Package Manager "Edit Package" dialog, and if you have left a field empty, I hope you have a very good reason! 

Is the package reusable?

Sometimes, no matter how useful your package's functionality is to your organisation, it just doesn't make sense to share it more widely. You can still use Package Share, but in this instance you're better off restricting sharing to just your company.

All the entries we received were great examples of features or functionality that would be essential add-ons to anyone using CQ, but keep in mind that globally-shared packages should be generic enough for other companies to use. Feel free to upload GenericConfigurableBackOfficeConnector, but avoid uploading CopyDataFromBobsLaptop! 

Your package may be very generic, but sometimes it still needs some local configuration before it will work. In this case, consider the nicest way that you can handle this for your users. Could the information be entered via a dialog? Could the configuration be stored and retrieved from a property? If configuration is required, consider adding a UI for the package under CQ Tools.

How good is the code quality?

There's lots of metrics out there for judging code quality. Nobody expects perfect code, but try to keep it clean, readable and extensible. Keep an eye on best practices:

When you write your code, respect the conventions of CQ – not just in formatting, but also in terms of functionality and layout. For example, if you're providing a component, make sure it shows up in an appropriate group in the Sidekick. If you're modifying existing foundation components, make sure you only change a copy in /apps rather than overwriting /libs (in fact, don't overwrite CQ functionality at all!) Make sure you keep content under /content and separate from presentation where possible. Make sure you break down functionality where appropriate – for example in separate head and body JSPs. If you're using third-party javascript or CSS libraries, provide them as part of your package rather than loading them remotely.

Finally, consider putting your package on github: it's a great opportunity for others to collaborate and help you improve and to learn. You could also ask for help on the forums – the CQ community are a friendly bunch, and some constructive criticism might make your package better for you, as well as for everyone else!