Overview

The siteurls.config has not changed drastically throughout the past couple of years.  Regardless, it still remains a somewhat daunting file to understand.  The step in this understanding it to realize that siteurls.config contains the data used for URL rewriting.  The next step is to break down the basic structure of each of the elements in the siteurls.config and understand its purpose.

Understanding SiteUrls.config File Structure

A siteurls.config has the following basic structure:

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

    <locations>
        <location>
            <url />
        </location>
    </locations>

     <transformers>
         <add />
     </transformers>

     <navigation>
         <link />
     </navigation>

</SiteUrls>

As you can see there are locations which ultimately contain a collection of urls for each specific location.  Next there is a collection of transformers.  Finally, there is a collection of navigation links, these are used for the sitewide navigation menu.  For the purposes of this overview, only the locations and transformers will be explained.

A look at transformers

Transformers are used throughout the url nodes and are a common way to represent a path or even a common regex.  When used in a url node a transformer is replaced with its common representation.  For example, there is a transformer for userName, this is used in pattern matching in the urls.  When used in a url node you can find this pattern="conversations/##userName##.aspx" that ultimately becomes pattern="conversations/([a-zA-Z0-9\-\._]*?).aspx" when transformed and used for pattern matching.  There are also transformers that represent a path to a specific folder, like the main blog theme directory.  Ultimately, you should understand that a transformer simply represents a common regex or path on your site.  They can be used in a url node, and will get replaced with the transformer value.

The locations node

<locations type ="CommunityServer.Components.CSLocation, CommunityServer.Components">

Above is the standard locations node in the siteurls.config.  You will most likely not need to change this in any way.  You would want to change this if you had a different object to use for representing the CSLocation, otherwise there is no need to alter it.  Also, you should note that the source code for CSLocation is available in the SDK download.

The location node

<location name="forums" path="/forums/" themeDir="forums" applicationType="forum">

Above is an example of the forums location node.  Here are the available properties you can set on a location node:

• exclude - Whether the path is excluded from URL rewriting.  The root themes folder is not rewritten to anything else, for example.
• path - The URL path that represents where the urls are rewritten from.
• name - A unique name for the location.
• themeDir - Where in the theme folder are the pages for these urls contained?
• applicationType - If this represents a specific application, which application is it?

The url node

<url name="post"  path = "thread/{0}.aspx" pattern = "thread/(\d+).aspx" 
vanity="{2}?PostID=$1^UrlName=post" page="ForumUrlHandler.ashx" />

Above is an example of the post url entry for forums.  Here are all of the available properties you can set on a url node:

• Name - A unique identifier for the url
• path - The URL path that represents the requested path in the url
• pattern - The regex pattern to match to determine if the requested url is the current url node
• indexable - If not indexable then a search robots will be told not to index the page, this is a boolean
• vanity - If you would like to alter the resulting rewritten url then this is a good value to do it with.  You can add querystring values from requested url path.  In the above example the PostID is set with the digit used in the {0} part of the thread/{0}.aspx requested URL.
• physicalPath - You can override a the path in the parent location node with a physical path to the folder containing the page to load
• redirect - This is a boolean that indicates whether to do a 301 redirect to the new url
• page - The page file that is rewritten to
• applicationType - The type of application the page url belongs to, blog, forum...

It is important to realize that not all of the above properties are required on each of the url nodes.  You can look at the SiteUrls.config file itself for several examples of url nodes that contain only a few of these properties.

Adding a page example

Assume that you want to add an about page to the forums.  The about page will be named about.aspx and will be placed in the /themes/[themename]/forums/ folder.  It will display specific information about each forum, more than a simple description currently does.  You want your users to be able to request a URL like this in order to see information about forum number 3: http://yoursite.com/forums/3/about.aspx.  You also want the forumId to be passed on the querystring to your about.aspx page so that it knows what forum to display information about.  Here is one way that you could add a url entry to the forum location node to achieve this:

<url name="forumAbout" path="{0}/about.aspx" pattern="(\d+)/about.aspx"
physicalPath="##themeDir##" vanity="{2}?ForumID=$1" page="about.aspx"  /> 

Questions?