Skip to content

Defining Sitemap Nodes in XML

NightOwl888 edited this page Mar 12, 2014 · 11 revisions

The following is a simple sitemap XML file that can be used with the MvcSiteMapProvider:

<?xml version="1.0" encoding="utf-8" ?> 
<mvcSiteMap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns="http://mvcsitemap.codeplex.com/schemas/MvcSiteMap-File-4.0"
            xsi:schemaLocation="http://mvcsitemap.codeplex.com/schemas/MvcSiteMap-File-4.0 MvcSiteMapSchema.xsd">

  <mvcSiteMapNode title="Home" controller="Home" action="Index" changeFrequency="Always" updatePriority="Normal"> 
    <mvcSiteMapNode title="Browse Store" controller="Store" action="Index" /> 
    <mvcSiteMapNode title="Checkout" controller="Checkout" /> 
  </mvcSiteMapNode> 
</mvcSiteMap>

Note: There must be exactly 1 root mvcSiteMapNode in the configuration file and the rest of the mvcSiteMapNode elements should be defined below the root node.

The following attributes can be given on an XML node element:

Display Attributes

Attribute Required? Default
title
Yes (empty)
The title of the node. Localizable.
description
No (value of title attribute)
Description of the node. Localizable. This value will be put into the HTML title attribute of the link. Default can be changed to empty string by setting the configuration/appSettings value "MvcSiteMapProvider_UseTitleIfDescriptionNotProvided" in the root web.config file to "false".
clickable
No true
Is the node clickable or just a grouping node?
visibilityProvider
No (empty); returns true
Class that will be used to determine visibility for a sitemap node. Default setting can be overridden by the configuration/appSettings value "MvcSiteMapProvider_DefaultSiteMapNodeVisibiltyProvider" in the root web.config file.
visibility
No (empty)
Optional extra data that can be passed to a visibility provider to make convention-based visibility. Example from demo: visibility="SiteMapPathHelper,!*"
order
No 0
The sort order the node will be displayed in the Menu and SiteMap HTML helpers relative to its sibling nodes.
imageUrl
No (empty)
Optional image to be shown by supported HtmlHelpers. Localizable. The value may be an absolute URL (to the current site or to an external site), root relative URL (starting with '/' ), or virtual application relative URL (starting with '~/' ).
imageUrlProtocol
Cond. (empty); protocol of current request if imageUrlHostName attribute supplied
The protocol that will be used to generate the imageUrl, such as http, https, or ftp. Defaults to the protocol of the current request if imageUrlHostName attribute is supplied.
imageUrlHostName
Cond. (empty); current request host name if imageUrlProtocol attribute supplied
The host name that will be used to generate the imageUrl, such as www.somewhere.com. Defaults to the host name of the current request if imageUrlProtocol attribute is supplied.
targetFrame
No (empty)
Optional target frame for the node link.

URL/Routing Attributes

Attribute Required? Default
area
No (empty)
The MVC area for the sitemap node. If not specified, it will be inherited from a node higher in the hierarchy.
controller
Yes (empty)
The MVC controller for the sitemap node. Case-sensitive! Must not end in the suffix "Controller". If not specified, it will be inherited from a node higher in the hierarchy.
action
Cond. (empty)
The MVC action method for the sitemap node. Required if URL is not specified.
route
No (empty)
Can be specified to bind the node URL generation to a specific route.
inheritedRouteParameters
No (empty)
Route parameters that should be inherited from the parent sitemap node in the XML hierarchy.
preservedRouteParameters
No (empty)
Preserved route parameter names (= values that will be used from the current request route).
urlResolver
No Sitemap provider's SiteMapNodeUrlResolver instance
Class that will be used to generate URLs for sitemap nodes.
cacheResolvedUrl
No true
Should the resolved URL be cached (true) or resolved on each request (false)? If the preservedRouteParameters attribute is used, this setting will be ignored.
url
Cond. (autogenerated based on routes)
The URL represented by the node. Required if Controller and Action are not provided. The value may be an absolute URL (to the current site or to an external site), root relative URL (starting with '/' ), or virtual application relative URL (starting with '~/' ).
protocol
Cond. (empty); http if hostName attribute supplied
The protocol that will be used to generate the URL, such as http, https, or ftp. Defaults to "http" if hostName attribute is supplied. Set to "*" to use the protocol of the current request.
hostName
Cond. (empty); current request host name if protocol attribute supplied
The host name that will be used to generate the URL, such as www.somewhere.com. Defaults to the host name of the current request if protocol attribute is supplied.
includeAmbientValuesInUrl
Cond. false
Whether or not to include non-configured route values and/or query string values from the current user's request when resolving the URL. This setting affects route/action URLs only, if you set the url attribute explicitly, this setting has no effect.

SEO Attributes

Attribute Required? Default
canonicalKey
No (empty)
The key value for the node that contains the primary copy of the content for the current node, if it is largely similar. Cannot be used in conjunction with canonicalUrl.
canonicalUrl
No (empty)
The primary URL for what is completely or mostly duplicated content on the current node. The value may be an absolute URL (to the current site or to an external site), root relative URL (starting with '/' ), or virtual application relative URL (starting with '~/' ). Cannot be used in conjunction with canonicalKey.
canonicalUrlProtocol
Cond. (empty); http if canonicalUrlHostName attribute supplied
The protocol that will be used to generate the URL, such as http, https, or ftp. Defaults to "http" if canonicalUrlHostName attribute is supplied. Set to "*" to use the protocol of the current request.
canonicalUrlHostName
Cond. (empty); current request host name if canonicalUrlProtocol attribute supplied
The host name that will be used to generate the URL, such as www.somewhere.com. Defaults to the host name of the current request if canonicalUrlProtocol attribute is supplied.
metaRobotsValues
No (empty)
A space-delimited list of values to apply to the robots meta tag. These will apply to all robots that crawl the site. Allowed values: index, noindex, follow, nofollow, none, noarchive, nocache, nosnippet, nopreview, noodp, noydir.
lastModifiedDate
No (empty)
Last modified date for the node. Will be output to sitemaps XML for search engines.
changeFrequency
No Undefined
Change frequency for the node. Will be output to sitemaps XML for search engines.
updatePriority
No Undefined
Update priority for the node. Will be output to sitemaps XML for search engines.

Other Attributes

Attribute Required? Default
key
No (autogenerated)
The unique identifier for the node.
dynamicNodeProvider
No (empty)
A class name implementing MvcSiteMapProvider.IDynamicNodeProvider and providing dynamic nodes for the site map. These nodes are cached, not per-request.
httpMethod
No GET
The HTTP method that will be used to check node accessibility. This value is used to select correct controller action if a controller has multiple action accepting different HTTP verbs. Set to * or Request to use HTTP method of current request.
roles
No (empty)
Comma-separated list of roles allowed to access the node and its child nodes. This attribute is for interoperability with non-MVC pages that are secured using ASP.NET forms authentication. For MVC, use the AuthorizeAttribute to provide security.
resourceKey
No (empty)
Implicit resource key for use during localization of the node.
(custom name)
No (empty)
Any attributes not defined in this list will automatically be parsed and added to the ISiteMapNode.Attributes dictionary and ISiteMapNode.RouteValues dictionary. To exclude the attribute from being added to the RouteValues dictionary (and thus the URL), add the attribute name to the configuration/appSettings value "MvcSiteMapProvider_AttributesToIgnore" in the root web.config file as a comma delimited list. Localizable (if string data type).

XML Inheritance

Default Behavior

By default, "area" and "controller" (route values only) are automatically inherited from the parent node if they are not explicitly specified. This allows you to use fewer attributes when configuring nodes to make the XML less verbose.

The following two XML declarations will produce exactly the same results, however as you can see the second one requires less markup because it is taking advantage of the default inheritance behavior.

<?xml version="1.0" encoding="utf-8" ?>
<mvcSiteMap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns="http://mvcsitemap.codeplex.com/schemas/MvcSiteMap-File-4.0"
            xsi:schemaLocation="http://mvcsitemap.codeplex.com/schemas/MvcSiteMap-File-4.0 MvcSiteMapSchema.xsd">

    <mvcSiteMapNode title="Home" controller="Home" action="Index">
        <mvcSiteMapNode title="About" controller="Home" action="About"/>
        <mvcSiteMapNode title="Contact" controller="Home" action="Contact"/>
        <mvcSiteMapNode title="Products" controller="Products" action="Index">
            <mvcSiteMapNode title="Flashlight" controller="Products" action="Details" id="1"/>
            <mvcSiteMapNode title="AA Battery" controller="Products" action="Details" id="2"/>
        </mvcSiteMapNode>
        <mvcSiteMapNode title="Administration" area="Admin" controller="Home" action="Index">
            <mvcSiteMapNode title="Manage Products" area="Admin" controller="Products" action="Manage"/>
        </mvcSiteMapNode>
    </mvcSiteMapNode>

</mvcSiteMap>
<?xml version="1.0" encoding="utf-8" ?>
<mvcSiteMap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns="http://mvcsitemap.codeplex.com/schemas/MvcSiteMap-File-4.0"
            xsi:schemaLocation="http://mvcsitemap.codeplex.com/schemas/MvcSiteMap-File-4.0 MvcSiteMapSchema.xsd">

    <mvcSiteMapNode title="Home" controller="Home" action="Index">
        <mvcSiteMapNode title="About" action="About"/>
        <mvcSiteMapNode title="Contact" action="Contact"/>
        <mvcSiteMapNode title="Products" controller="Products" action="Index">
            <mvcSiteMapNode title="Flashlight" action="Details" id="1"/>
            <mvcSiteMapNode title="AA Battery" action="Details" id="2"/>
        </mvcSiteMapNode>
        <mvcSiteMapNode title="Administration" area="Admin" controller="Home" action="Index">
            <mvcSiteMapNode title="Manage Products" controller="Products" action="Manage"/>
        </mvcSiteMapNode>
    </mvcSiteMapNode>

</mvcSiteMap>

inheritedRouteParameters

You can also specify additional route values to inherit, including custom attributes, by adding the name of the value to the inheritedRouteParameters. Multiple values should be separated by a comma.

The following 2 XML declarations will have exactly the same result.

<?xml version="1.0" encoding="utf-8" ?>
<mvcSiteMap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns="http://mvcsitemap.codeplex.com/schemas/MvcSiteMap-File-4.0"
            xsi:schemaLocation="http://mvcsitemap.codeplex.com/schemas/MvcSiteMap-File-4.0 MvcSiteMapSchema.xsd">

    <mvcSiteMapNode title="Home" controller="Home" action="Index">
        <mvcSiteMapNode title="Products" controller="Products" action="Index" type="accessory">
            <mvcSiteMapNode title="Flashlight" action="Details" id="1" type="product"/>
            <mvcSiteMapNode title="AA Battery" action="Details" id="2" type="accessory"/>
        </mvcSiteMapNode>
    </mvcSiteMapNode>

</mvcSiteMap>
<?xml version="1.0" encoding="utf-8" ?>
<mvcSiteMap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns="http://mvcsitemap.codeplex.com/schemas/MvcSiteMap-File-4.0"
            xsi:schemaLocation="http://mvcsitemap.codeplex.com/schemas/MvcSiteMap-File-4.0 MvcSiteMapSchema.xsd">

    <mvcSiteMapNode title="Home" controller="Home" action="Index">
        <mvcSiteMapNode title="Products" controller="Products" action="Index" type="accessory">
            <mvcSiteMapNode title="Flashlight" action="Details" id="1" type="product"/>
            <mvcSiteMapNode title="AA Battery" action="Details" id="2" inheritedRouteParameters="type"/>
        </mvcSiteMapNode>
    </mvcSiteMapNode>

</mvcSiteMap>

Want to contribute? See our Contributing to MvcSiteMapProvider guide.



Version 3.x Documentation


Unofficial Documentation and Resources

Other places around the web have some documentation that is helpful for getting started and finding answers that are not found here.

Tutorials and Demos

Version 4.x
Version 3.x

Forums and Q & A Sites

Other Blog Posts

Clone this wiki locally
You can’t perform that action at this time.