I recently had the great hon­our of being part of the team review­ing the entries to the Adobe CQ Pack­age Share con­test. For those who missed it, Adobe was giv­ing away a 15-inch Retina Mac­Book Pro for the best five pack­ages sub­mit­ted, based on the fol­low­ing judg­ing areas: 40% cre­ativ­ity, 40% over­all qual­ity, and 20% reusabil­ity. We appre­ci­ated all who par­tic­i­pated and sub­mit­ted – thank you!

A pack­age is just a zip file of con­tent in a spe­cial for­mat, and by upload­ing pack­ages in Pack­age Share you can make your cus­tom code – such as tem­plates, libraries, or even con­tent – avail­able to every­one using Adobe CQ in your com­pany, or any­one else using CQ world­wide. It’s also a great way to dis­cover new func­tion­al­ity, and to quickly and eas­ily down­load and install new CQ fea­ture packs. For more back­ground on pack­ages and Pack­age Share, check out my recent video.

Before I go fur­ther, I’m pleased to acknowl­edge the five win­ners of the con­test, all of whom had strong sub­mis­sions. I’ve included the names of their pack­ages, and want to high­light that each will be avail­able in Pack­age Share soon. They are:

·         David from Katonah, NY — YouTube

·         Maciej from Lon­don, UK – CQ YouTube Integration

·         Mark from San Fran­cisco, CA – Recap

·         Ruben from Brus­sels, BE – Tem­plate Manager

·         Tomasz from Lon­don, UK – SecureCQ

I thought it would be use­ful to share some of the cri­te­ria we applied when review­ing the entries. The cri­te­ria encap­su­late best prac­tice, and should help oth­ers build great pack­ages to. We had 6 broad cri­te­ria that we applied:

  • Does the pack­age work?
  • Does it offer some sort of cool fea­ture or functionality?
  • Is the pack­age nice looking?
  • How well was it packaged?
  • Is the pack­age reusable?
  • How good is the code quality?

Let’s look at them in more detail.

Does the pack­age work?

The pack­age might work for you, but what about for oth­ers? If you’re expect­ing it to be shared, take the extra time to test your pack­age on a vanilla install of CQ. Ide­ally, try it on sev­eral dif­fer­ent ver­sions – includ­ing our very lat­est and also includ­ing CQ 5.4 and 5.5. Remem­ber, there’s a meta­data field for the ver­sions of CQ you have tested against, so make sure it’s filled out.

Another aspect of check­ing the pack­age works is know­ing where to begin. There are so many pos­si­ble places to check – is it a com­po­nent (try enabling it in Design view)? Is it a sep­a­rate site (look for it under site admin)? Is it a tool (look for it under Tools)? You should make it obvi­ous to any­one down­load­ing the pack­age – for exam­ple by pro­vid­ing a link to your package’s entry point in the descrip­tion. Remem­ber the pack­age is usu­ally down­loaded onto the server it will be installed on, so you can use rel­a­tive links to ensure it always works, no mat­ter what host or port CQ is run­ning on.

Fea­tures and functionality

We had some very diverse entries, includ­ing enhance­ments to con­fig­ur­ing and man­ag­ing core CQ func­tion­al­ity; tools to query the under­ly­ing CRX repos­i­tory; and com­po­nents for man­ag­ing con­tent from third-party sites and ser­vices. The best pack­ages offered func­tion­al­ity not avail­able any­where else. Cool is rel­a­tive – one of the highest-scoring con­tri­bu­tions made a tool-powered virtue out of  a site manager’s dull copy-editing neces­sity. The les­son here is to think about how peo­ple use CQ, and what makes life eas­ier for them. If you’ve solved a prob­lem for your team locally, chances are your solu­tion could help a much wider CQ user community.

Is the pack­age nice look­ing, and how well was it packaged??

Beauty is in the eye of the beholder, but if your pack­age included icons, screen­shots, great design and a friendly user expe­ri­ence, then you prob­a­bly did well. CQ gives you lots of oppor­tu­ni­ties to pro­duce nice-looking pack­ages. For exam­ple, you can include HTML tags in your descrip­tion meta­data, so take the time to make sure it is read­able and high­lights the key information.

Good pack­ag­ing includes a wide range of cri­te­ria. Does the pack­age store every­thing in a sen­si­ble place (for exam­ple in /apps)? Does the pack­age make use of fil­ters to include (or exclude) every­thing it should? Does the pack­age dupli­cate exist­ing files (which would be bad)? Does the pack­age include suit­able metadata?

Meta­data is par­tic­u­larly impor­tant when you are shar­ing your pack­ages, as it greatly aids dis­cov­er­abil­ity. If peo­ple don’t know what your pack­age does or what is in it, they won’t be down­load­ing it. Give it a mean­ing­ful name: ‘mypack­age’ is not much use, but ‘svg­com­po­nent’ imme­di­ately gives users a clue as to what it does.

Make use of the ver­sion num­ber, so peo­ple can tell when they need to update. List sup­ported plat­forms, bug fixes, and pro­vide exter­nal links wher­ever rel­e­vant. In fact, go through all of the tabs in the the Pack­age Man­ager “Edit Pack­age” dia­log, and if you have left a field empty, I hope you have a very good reason!

Is the pack­age reusable?

Some­times, no mat­ter how use­ful your package’s func­tion­al­ity is to your organ­i­sa­tion, it just doesn’t make sense to share it more widely. You can still use Pack­age Share, but in this instance you’re bet­ter off restrict­ing shar­ing to just your company.

All the entries we received were great exam­ples of fea­tures or func­tion­al­ity that would be essen­tial add-ons to any­one using CQ, but keep in mind that globally-shared pack­ages should be generic enough for other com­pa­nies to use. Feel free to upload Gener­ic­Config­urable­Back­Of­fice­Con­nec­tor, but avoid upload­ing CopyDataFromBobsLaptop!

Your pack­age may be very generic, but some­times it still needs some local con­fig­u­ra­tion before it will work. In this case, con­sider the nicest way that you can han­dle this for your users. Could the infor­ma­tion be entered via a dia­log? Could the con­fig­u­ra­tion be stored and retrieved from a prop­erty? If con­fig­u­ra­tion is required, con­sider adding a UI for the pack­age under CQ Tools.

How good is the code quality?

There’s lots of met­rics out there for judg­ing code qual­ity. Nobody expects per­fect code, but try to keep it clean, read­able and exten­si­ble. Keep an eye on best prac­tices: http://​dev​.day​.com/​d​o​c​s​/​e​n​/​c​q​/​c​u​r​r​e​n​t​/​d​e​v​e​l​o​p​i​n​g​/​d​e​v​e​l​o​p​i​n​g​_​g​u​i​d​e​l​i​n​e​s​_​b​e​s​t​p​r​a​c​t​i​c​e​s​.​h​tml.

When you write your code, respect the con­ven­tions of CQ – not just in for­mat­ting, but also in terms of func­tion­al­ity and lay­out. For exam­ple, if you’re pro­vid­ing a com­po­nent, make sure it shows up in an appro­pri­ate group in the Side­kick. If you’re mod­i­fy­ing exist­ing foun­da­tion com­po­nents, make sure you only change a copy in /apps rather than over­writ­ing /libs (in fact, don’t over­write CQ func­tion­al­ity at all!) Make sure you keep con­tent under /content and sep­a­rate from pre­sen­ta­tion where pos­si­ble. Make sure you break down func­tion­al­ity where appro­pri­ate – for exam­ple in sep­a­rate head and body JSPs. If you’re using third-party javascript or CSS libraries, pro­vide them as part of your pack­age rather than load­ing them remotely.

Finally, con­sider putting your pack­age on github: it’s a great oppor­tu­nity for oth­ers to col­lab­o­rate and help you improve and to learn. You could also ask for help on the forums – the CQ com­mu­nity are a friendly bunch, and some con­struc­tive crit­i­cism might make your pack­age bet­ter for you, as well as for every­one else!