Mr Sharepoint: Metadata navigation on publishing sites using the Oslo masterpage

Friday, December 18, 2015

Metadata navigation on publishing sites using the Oslo masterpage

You might be familiar with metadata navigation in SharePoint – a handy feature that allows users to more easily find items in large lists/libraries using configurable filters. We activated/configured metadata navigation and were able to use this feature using both of the out-of-the-box masterpages (Seattle and Oslo) and for a while all were happy in SharePoint-land.

(For more info on how to configure metadata navigation I kindly direct you to the office support page)

FinalScreen01 FinalScreen02 Picture 1: Metadata navigation on the out-of-the-box Seattle (left) and Oslo (right) masterpages

Until one faithful day we decided to copy the Oslo masterpage we were using at that point and customize it. After our changes we found that the metadata navigation pane was missing. After some investigation it turned out that even if we edited the default Oslo masterpage the filters would still be gone. The Seattle masterpage did not suffer from this problem: no matter if we copied it or modified the original version the filters would still be on the page.

FinalScreen03 Picture 2: Metadata navigation on customized Seattle (left) and Oslo (right) masterpages

To explain why this happens I’ll have to take a small step back and briefly talk about the SharePoint publishing features with regards to masterpages:

(for more info about the publishing features I again kindly direct you to the office support page)

Normal, non-publishing, sites only have a single file per masterpage, which has the .master extension (e.g. Seattle.master, Oslo.master, …). This file can be edited directly using SharePoint Designer or any other editor.
Publishing sites have two files per masterpage, one .master file and one .html file (e.g. Seattle.master and Seattle.html). The .master file can no longer be edited directly but will be generated by SharePoint whenever the .html version is updated.

Turns out Oslo.html does not contain the snippet for the “TreeViewNavigationManager”, the control responsible for adding the filters to the page. The Oslo.master file however does contain this snippet. This is why the filters were there when we first activated the Oslo masterpage but stopped showing up as soon as we copied it or made any customizations: SharePoint would parse the .html file and ‘translate’ it into a new version of the .master file, this time without the “TreeViewNavigationManager”.

FinalScreen04_05 Picture 3: TreeViewNavigationManager in the Seattle (left) and Oslo (right) masterpage files

Once we found out what the problem was we were able to easily fix it by adding this snippet to our copy of the Oslo.html file (I advise against editing the out-of-the-box masterpages and prefer to work with copies), just below the “sideNavBox” tag.

<!--SPM:<SharePoint:SPNavigationManager id="TreeViewNavigationManagerV4" runat="server" ContainedControl="TreeView" CssClass="ms-tv-box">-->        <!--SPM:<SharePoint:SPLinkButton runat="server" NavigateUrl="~site/_layouts/15/viewlsts.aspx" id="idNavLinkSiteHierarchyV4" Text="<%$Resources:wss,treeview_header%>" accesskey="<%$Resources:wss,quiklnch_allcontent_AK%>" CssClass="ms-tv-header"/>-->        <!--SPM:<SharePoint:DelegateControl runat="server" ControlId="TreeViewAndDataSource">-->
                <!--SPM:<Template_Controls>-->
                        <!--SPM:<SharePoint:SPHierarchyDataSourceControl runat="server" id="TreeViewDataSourceV4" RootContextObject="Web" IncludeDiscussionFolders="true"/>-->
                        <!--SPM:<SharePoint:SPRememberScroll runat="server" id="TreeViewRememberScrollV4" onscroll="javascript:_spRecordScrollPositions(this);" style="overflow: auto;">-->
                                <!--SPM:<SharePoint:SPTreeView id="WebTreeViewV4" runat="server" ShowLines="false" DataSourceId="TreeViewDataSourceV4" ExpandDepth="0" SelectedNodeStyle-CssClass="ms-tv-selected" NodeStyle-CssClass="ms-tv-item" SkipLinkText="" NodeIndent="12" ExpandImageUrl="/_layouts/15/images/tvclosed.png?rev=41" ExpandImageUrlRtl="/_layouts/15/images/tvclosedrtl.png?rev=41" CollapseImageUrl="/_layouts/15/images/tvopen.png?rev=41" CollapseImageUrlRtl="/_layouts/15/images/tvopenrtl.png?rev=41" NoExpandImageUrl="/_layouts/15/images/tvblank.gif?rev=41">--><!--SPM:</SharePoint:SPTreeView>-->
                        <!--SPM:</SharePoint:SPRememberScroll>-->
                <!--SPM:</Template_Controls>-->
        <!--SPM:</SharePoint:DelegateControl>-->
<!--SPM:</SharePoint:SPNavigationManager>-->

FinalScreen06 Picture 4: TreeViewNavigationManager: copied into the oslo_copy.html file