CS Tidbits #26 -- Harness The Power Of Config File Overrides

Now that Community Server 2007 has been released, it's time to fire up the CS Tidbits category again and see what I can come up with. Coming tidbits will still be geared towards site admins (making your site easier to use, simple tweaks and additions, etc), but I'll also go into some details about Chameleon, CS's long awaited skinning engine overhaul.

Today's tidbit is one of the most commonly requested scenarios (I've covered it before): "I want to add a new menu tab/add a second blog/etc to my CS installation, how do I do that?" Fundamentally the concept is the same as in previous versions of CS...you need to modify your SiteUrls.config file which is where all the magic of URL rewriting is laid out. CS 2007 introduces the notion of override.config files, which in their simplest of forms take on the name of *_override.config where * is the name of the config file you wish to modify (of course you cannot apply any overrides to the web.config file seeing as it's a special file for the asp.net runtime), and you then use XPath notation to manipulate (or add) tags to your config files. I am by no means an XPath expert, if you are curious about the syntax and rules there are numerous resources on the web at your disposal, plus an entire army of experts over on CS.org who are happy to help out.

The scenario I ran into was the following: I needed my CS site to remain unchanged at the root (http://jaysonknight.com shows the aggregate page), needed /blog to point towards my main blog, and have /feeds map to my external news section without having the application key in the URL. Note: this post assumes you've already configured both blogs in Control Panel before doing anything else.

The first thing we need to do (which remains unchanged from previous versions of CS) is add the physical menu tab which links to the second blog. You must specify this value in the actual SiteUrls.config file, it cannot be specified in an override file. All override files are actually processed first by the CS runtime, so if you specify a new menu tab location in an override you have no control over the order it will appear in the menu, meaning it will show up first. In my case I needed it to be 3rd, so just add it after the first 2 <link> elements. Here's the line to add to the <navigation> element in SiteUrls.config:


<link name="feeds" resourceUrl="feedshome" text="External News"
roles="Everyone" applicationType = "Weblog" />

Now we need to do the actual URL manipulation, so create a blank file called SiteUrls_override.config and add the following:


<?xml version="1.0" encoding="utf-8" ?>

<Override xpath = "/SiteUrls/locations/location[@name='weblogs']" mode = "change"
name = "path" value = "/" />
<Override xpath = "/SiteUrls/locations/location[@name='weblogs']" mode = "new"
name = "physicalPath" value = "/blogs/" />

<Override xpath = "/SiteUrls/locations/location[@name='weblogs']/url[@name='webloghome']"
mode = "update">
<url name = "webloghome" path="blog" pattern="default.aspx"
physicalPath="/themes/default/common/" vanity="{2}" page="home.aspx" />
<url name = "feedshome" path="feeds" pattern="default.aspx"
physicalPath="/themes/default/common/" vanity="{2}" page="home.aspx" />

All we're doing is resetting the URL of the weblogs link element to '/' (root), then mapping all requests to be routed to the physical /blogs/ directory in your CS installation (where all the dummy .aspx pages are located to pass the request off to the asp.net runtime), however you will still need to create a directory for each of the <url> elements named with the value in the path attribute, and put a blank default.aspx page in them. You'll notice the mode attribute specified a couple of times above...the accepted values should be fairly self explanatory...it's this value that tells the override parser what to actually do with the XPath statements, how to apply them to the existing config files. Lastly we do the actual URL rewriting in the mode=update block of XPath by mapping the url names to the links specified in the <location> element, and then telling CS what to display, in this case generating a url in the root/applicationKey format (since the path was reset to /, we specify the new path as /blog or /feed, etc). In our case we want home.aspx to display rather than postlist.aspx (the default). Following this pattern you can add as many blogs to your site as you are licensed for.

As should be fairly obvious, the power of config files means simplicity, reusability, and portability of your config file customizations without having to actually edit the config files themselves. A bit of trial and error might be necessary for the uninitiated, but the benefits of having a system like this in place should be obvious.

Filed under:


# Dave Burke said:

blog bits Keyvan Nayyeri with an CS Dev Guide-worthy post on separating comment and trackback lists with

Tuesday, April 24, 2007 6:11 PM
# Dave Burke's Community Server Bits said:

Whenever Jayson Knight writes a CS Tidbit I like to say "HE'S BACK!" and this is a "HE'S BACK" quality

Tuesday, April 24, 2007 7:03 PM
# Ezequiel Espíndola said:

Hi Jayson!

Your CS Tidbits series is great! Do you know by any chance how to redirect the old URLs from version 2.0 that got an underscore on the post name to the new URLs that get a dash instead?

Thank you very much!

Sunday, May 13, 2007 11:36 PM
# David said:

I came across the problem with position new menu items. Another alternative is the remove all of the entries using siteurls_override.config then re add them in the correct order. This avoids having to edit your siteurls.config file

Tuesday, May 22, 2007 2:43 AM