Understanding the SiteUrls.config File

The siteurls.config file contains the data used for URL rewriting. 

File Structure

The following example shows the basic structure of a siteurls.config file:

<?xml version="1.0" encoding="utf-8" ?> <SiteUrls> <locations> <location> <url /> </location> </locations> <transformers> <add /> </transformers> <navigation> <link /> </navigation> </SiteUrls>

The example shows that a number of locations contain a collection of URLs for each specific location. It also shows a collection of transformers and navigation links, which are used for the site-wide navigation menu. 

Transformers

Transformers, which are used throughout the url nodes, 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, the transformer for userName is used in pattern matching in the URLs.  When used in a url node you can find this:

pattern="conversations/##userName##.aspx"

which ultimately becomes:

pattern="conversations/([a-zA-Z0-9\-\._]*?).aspx"

when transformed and used for pattern matching. Some transformers represent a path to a specific folder, like the main blog theme directory. 

Standard Locations Node

The siteurls.config file contains the following standard locations node:

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

You should not have to change this in any way only if you had a different object to use for representing the CSLocation. The source code for CSLocation is available in the SDK download.

Forums Location Node

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

The properties you can set on a location node include the following:

• exclude – Specifies whether or not the path is excluded from URL rewriting. The root themes folder is not rewritten to anything else, for example.
• path – Specifies the URL path from which the URLs are rewritten.
• name - Unique name for the location.
• themeDir – Specifies the theme folder that contains the pages for the URLs.
• applicationType - Represents a specific application.

URL Node

The following example shows the post URL entry for a forum:

<url name="post" path = "thread/{0}.aspx" pattern = "thread/(\d+).aspx"

vanity="{2}?PostID=$1^UrlName=post" page="ForumUrlHandler.ashx" />

The properties you can set on a URL node include the following:

• name - Unique identifier for the URL.
• path - URL path that represents the requested path in the URL.
• pattern - Regex pattern to match to determine if the requested URL is the current URL node.
• indexable - If not indexable, then this is a boolean; a search robots will be told not to index the page.
• vanity – Value allowing you to alter the resulting rewritten URL. You can add querystring values from requested url path. In the example above, the PostID is set with the digit used in the {0} part of the thread/{0}.aspx requested URL.
• physicalPath – Allows you to override the path in the parent location node with a physical path to the folder containing the page to load.
• redirect - Boolean that indicates whether or not to do a 301 redirect to the new URL.
• page – Page to which the file rewritten.
• applicationType - Type of application to which the page URL belongs.

Not all of these properties are required on each URL node. You can look at the SiteUrls.config file for several examples of URL nodes that contain only a few of these properties.

Adding a page

The following example describes how you can add a page.

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" />