Overriding the default damadmin or siteadmin pages in CQ5

Overriding foundation content in CQ5 was made fairly easy by our friends on the Adobe CQ team. In the vast majority of cases, we can just replicate the path of the original code under libs to our apps folder. In the case of siteadmin and damadmin, this would mean we need to copy the root node from the original path: /libs/wcm/core/content/damadmin or /libs/wcm/core/content/siteadmin to /apps/wcm/core/content/damadmin. However, since these particular nodes are accessed through a vanityURL (/damadmin and /siteadmin respectively) instead of their path in the repository, there is a slightly different approach to overriding them. Although it is still best practice to override in the same folder structure as the libs node (so you can default back to them for any un-overridden piece), there is an extra step to getting your content to actually appear when using vanity urls.

This little gem of a property is called: vanityOrder
On both the damadmin and siteadmin nodes there is a property called vanityOrder. Typically, this property is not necessary as any vanityPaths set in custom content will be unique. In this case, however, since the original content is under libs, we need to set a vanity order to establish what content the vanity url maps to.

Let's do a little example:
We're going to add a button to the "Tools" dropdown in the damadmin. The first step is to copy the damadmin node to your apps folder, as seen below (Note: Folders must be of type sling:folder):

[[{"type":"media","view_mode":"media_large","fid":"73","attributes":{"alt":"","class":"media-image","height":"398","typeof":"foaf:Image","width":"440"}}]]

Now that you have a copy in your apps folder, delete any child nodes that you will not be overriding (we want to revert back to the libs version in case of future updates). As we're adding a "Tools" item, it is safe to remove the grid, treeRoot, search, tabs, and tags nodes. After removing these items, it will look as follows:

[[{"type":"media","view_mode":"media_large","fid":"74","attributes":{"alt":"","class":"media-image","height":"257","typeof":"foaf:Image","width":"409"}}]]

Now that we have just the portion we want to override copied over, lets create some changes (so we can prove that we're overriding the default). I'll start with something extremely simple, we'll copy an existing item and change the text. In the example below, I copied "References..." and set the text to "Export Item":

[[{"type":"media","view_mode":"media_large","fid":"75","attributes":{"alt":"","class":"media-image","height":"314","typeof":"foaf:Image","width":"440"}}]]

So now we have an updated damadmin console! Lets go to our browser and see the changes (http://localhost:4502/damadmin):

[[{"type":"media","view_mode":"media_large","fid":"76","attributes":{"alt":"","class":"media-image","height":"180","typeof":"foaf:Image","width":"480"}}]]

Interestingly, it doesn't seem to have picked up our changes! A new item was supposed to be under "Download" in the tools dropdown. This is where we need to modify the "vanityOrder". You see, since we're using a vanity path, we need to specifically tell CQ which item will take priority. This is also where the different CQ versions will act differently (unfortunately). You can see on the copied damadmin node, the vanityOrder is set to 290 (seen in the first screenshot under properties). In CQ5 (without any SP), we need to set our overridden version to have a higher number. Let's see what happens when we set it to 291:

[[{"type":"media","view_mode":"media_large","fid":"77","attributes":{"alt":"","class":"media-image","height":"331","typeof":"foaf:Image","width":"454"}}]]

Now lets see if our changes have been picked up:
[[{"type":"media","view_mode":"media_large","fid":"78","attributes":{"alt":"","class":"media-image","height":"159","typeof":"foaf:Image","width":"463"}}]]

Huzzah! It worked. Now that we know how to make changes, you can actually modify the default buttons and interactions of this console.