Controlling navigation options from the onet.xml

During past weeks I have been creating few customer POCs to demostrate the excellent WCM features of the MOSS 2007. Since the MOSS publishing features are deployed over the WSS using standard feature framework, we can configure the provisioning of the sites directly from the onet.xml. In this blog entry, I'll declare the concepts behind this possibility and the possible properties, which can be set.

 

Introduction

If you have played around the onet.xml files included as out-of-the-box in the MOSS (Publishing template etc.), you have most likely noticed the publishing navigation feature dependencies in the WebFeatures element as in xml block below.

<WebFeatures>
     ...
     <Feature ID="541F5F57-C847-4e16-B59A-B31E90E6F9EA">
          <Properties xmlns="https://schemas.microsoft.com/sharepoint/">
          <Property Key="InheritGlobalNavigation" Value="true"/>
          <Property Key="ShowSiblings" Value="true"/>
          <Property Key="IncludeSubSites" Value="true"/>
          </Properties>
     </Feature>
     ...
</WebFeatures>

So what does this really mean? Basically we are making a binding to publishing navigation feature and configuring it by using properties, which the handler is capable to handle. So the ID given in the onet.xml is a reference to NavigationProperties feature, which can be found from the following folder (by default):

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\NavigationProperties

And the feature.xml file from here contains following information:

<Feature Id="541F5F57-C847-4e16-B59A-B31E90E6F9EA"
               Title="Portal Navigation Properties"
               Description="Set per-site navigation properties."
               Version="12.0.0.0"
               Scope="Web"
               Hidden="TRUE"
               ReceiverAssembly="Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"
               ReceiverClass="Microsoft.SharePoint.Publishing.NavigationFeatureHandler"
               xmlns="https://schemas.microsoft.com/sharepoint/">
               <ElementManifests>
                    <ElementManifest Location="NavigationSiteSettings.xml"/>
               </ElementManifests>
</Feature>

As you can see, ReceiveAssebly and ReceiverClass attributes are set and there for when the actions are performed for the feature, "custom code" is executed. As declared already above, the custom code is aware of some parameters which can be set for the feature and based on these parameters, the receiver handler modifies the SPPublishingWeb object's properties.

 

Supported parameters

So what are the parameters supported by the NavigationFeatureHandler class and how do they affect compared to settings done from the user interface. I'll declare the supported parameters one-by-one and compare the settings to modifications done from the user interface (Site Actions -> Site Settings -> Navigation) .

 

IncludeInGlobalNavigation, IncludeInCurrentNavigation 

Controls the IncludeInGlobalNavigation and IncludeInCurrentNavigation properties of the SPPublishingWeb. In user interface this functionality is controlled by using following options.

 

InheritGlobalNavigation

This paremeters controls the global navigation options. If set the true, we will get the same outcome by selecting "Display the same navigation items as the parent site".

 

InheritCurrentNavigation

This controls the inheritance of the current navigation. If set the true, we would get the same results as by selecting the "Display the same navigation items as the parent site" from the user interface (the first option from the picture below)

 

 

ShowSiblings

If set the TRUE, the outcome is the same options as the “Display the current site, the navigation items below the current site, and the current site's siblings” option in the user interface (second option from the picture below). Note that the IncludeSubSites and IncludePages parameters also affects to outcome.

 

IncludeSubSites

This is same as the "Show subsites" option in the user interface . Note that if the current navigation has been set to show the same navigation items as the parent site, this option has no meaning.

 

IncludePages

This is same as the "Show subsites" option in the user interface . Note that if the current navigation has been set to show the same navigation items as the parent site, this option has no meaning.

 

OrderingMethod

This option affects to ordering of the navigation items. Note that the final outcome depends also from the AutomaticSortingMathod and the SortAscending properties.

Possible values

Automatic - Sort all node types automatically, and group pages after other types. 

Manual - Sort all types manually. 

ManualWithAutomaticPageSorting - Sort all types except pages manually. If pages are included, sort them automatically and group them after all other types. 

 

AutomaticSortingMathod and  SortAscending

These controls the sorting of the navigation items. Possible outcome depends on numerous other properties, since for example the AutomaticSortingMathod property has only meaning, if the OrderingMethod has been set to ManualWithAutomaticPageSorting.

Note. It's not a typo... it's really AutomaticSortingMathod...

Possible values for the AutomaticSortingMathod property

CreatedDate - Sort items by time of creation. 

LastModifiedDate - Sort items by time of last modification. 

Title - Sort items alphabetically by title. 

 

Final words

As you can see, you can configure all the same options directly from the onet.xml, as you can do from the user interface. Other thing to notice is the possibilities provided by the Feature Receiver concept, which gives flexible way to execute custom code during the site provisioning (or anytime the feature is otherwise activated).

More information concerning the functionalities declared here can be found from the SDK.

 

PS. I'll try to find some time to write similar article concerning the other possibilities of the WCM features (how to limit the page layouts, how to limit the web templates shown in UI, how to configure master page etc.). Stay tuned...

[Update] - The following post with information concerning the other publishing feature configurations has been released. Check the details from here.