WebTemplate training materials - Lab 2 - Creation of custom navigation control and master pages

This post is lab 2 from series of training materials for WebTemplate creation and maintenance. Please check the following posts for details and other exercises. Notice that you can download full package with all required lab material from link available in introduction post. This package contains all supplementary materials and labs in word format.

This particular post will concentrate on following functionalities.

  • Creating custom navigation control
  • Adding custom master page for WebTemplate to Visual Studio solution
  • Adding custom navigation control to master page with required configurations
  • Adding required css and other UI related files to Visual Studio solution

Lab 02 – User interface customizations – Adding master page and custom navigation for WebTemplate

The project files for this lab are in the ‘C:\Student\Labs\02_UI’folder

Lab Objective

Lab Overview: In this exercise we create custom main navigation control to be used in master page. We also include previously created style sheets and master pages to the solution structure, so that we can deploy all our customizations from one solution package.

Additional Resources

This lab includes the following additional resources:

Starter Files


Files that can be used to help complete the labs.

Source Code


Completed lab source code in C#

Solution structure


Solution structure started in previous exercise

Getting Started

Notice that all code and xml elements which are meant to be copied are available as text in the Word documents. This means that if you need to copy any of those elements, it’s better to use Word document formats of these labs.

This Hands-On Lab contains a number of additional resources in fixed locations. By default, it is assumed that the base HOL directory is C:\Student and that the labs and additional resources are located under this directory.

The default working folder for this lab is C:\Student\Labs\02_UI .

Please notice that this exercise is assuming that you have environment with url http://intranet.contoso.com in your usage. If you use some alternative url, you’ll have to update scripts and use correct entries in exercises to make exercise to work properly.

Lab Setup Instructions

In the lab setup you will execute a PowerShell script that will create a new SharePoint site collection.

1. Start the Virtual Machine in Hyper-V.

2. Log on to the Virtual Machine as the local administrator with a user name of Contoso\Administrator and a password of pass@word1.

3. Open Windows Explorer and browse to the location C:\Student\Labs\Contoso.Intranet, in the folder double click Contoso.Intranet.sln to start the previously created solution structure.

  • This step assumes that you have already created lab 1 based on the lab 1 guidance, so that we can continue building up the customization package.
  • Notice also that package contains full source code status after lab 1 in folder C:\StudentWebTemplate\Labs\01_FeaturesAndVS2010\Solution\Contoso.Intranet - Lab 1 which you can copy as your starting point if you want to skip lab 1 completely.


Exercise 1 – Developing custom navigation control

In this exercise we’ll create custom navigation control, which will be used in the custom master page added in the following exercise.

clip_image001Why custom control? – why not utilize out of the box things?

Whenever appropriate, it’s recommended to use out of the box navigation controls. In this case the user interface designer has however created CSS styling in such a way that we’ll need to create custom control to be used.

Task 1 – Creating custom navigation control

1. Right click Contoso.Intranet project and choose Add – New Folder

2. Rename folder as UI

3. Right click UI folder and choose Add – New Folder

4. Rename folder as WebControls

5. Right click WebControls folder and choose Add – New Item

6. Under the Web node, choose ASP.NET Server Control


7. Name control as TopNavigation.cs

8. Click Add

9. Right click Contoso.Intranet project and choose References…

10. From the .NET tab, add reference to System.Configuration

11. Move back to TopNavigation.cs

12. Add following using statements to code class


13. Remove the example code generated during class creation until the content looks like in the following code snipped:


14. Add following properties to the web control (inside of the class, after the class {-sign), so that we can manage the styling of the navigation more efficiently.


15. Add following below the properties to manage the data source attached to the control


16. Following step is to add the actual rendering logic, add following override for RenderContents method after the just added private property

  • This method will be responsible of rendering the navigation nodes as navigation


17. Following step is to add the actual rendering logic, add following RenderSubNavigation method after the just added private property

  • This method will render the child notes of the root node


18. As a final step for the navigation rendering, we’ll still need to have following methods included. These will render the individual links and spacer elements between the navigation nodes.


19. Save your changes

20. Right click the Contoso.Intranet project and choose Build to verify that code is fully available

Exercise 2 – Adding master page to solution

Master page has been previously created and we’ll add that one and supplementary files to our Visual Studio solution. We’ll also add the just created web control to master page, which will be responsible of the main navigation rendering.

Task 1 – Adding required resources to the solution

1. Right click SPIs folder in the project structure and choose New Folder

2. Name folder as Modules

3. Right click Modules folder and choose New Item…

4. Choose Module SharePoint element and name that as ContosoMasterPage


5. Right click ContosoMasterPage module and choose Add – Existing Item…


6. Browse to folder c:\Student\Labs\02_UI\StarterFiles and select Contoso.Intranet.Default.master

7. Delete the unnecessary Sample.txt under the ContosoMasterPage module

8. Modify the elements.xml file content as follows for the master page module. Notice the different settings we define to ensure that master page is deployed properly to master page gallery, so that master page is available for sites in the particular site collection.


9. Since Visual Studio automatically added this module to our previously created features, we’ll need to refactor and ensure the associations. Double click WebPublishingBinding feature under the Features node

10. Use Arrows to remove the ContosoMasterPage module from the particular feature if it’s present

11. Double click SiteMainResources and use arrows to associate module to this feature

Task 2 – Adding style sheets and other relevant files for master page

In this task we add images and style sheets, which are required for the master page.

1. Right click Contoso.Intranet project and choose AddSharePoint “Layouts” Mapped Folder

2. Notice how Visual Studio Created automatically sub folder named as the project to avoid naming issues


3. Right click the Contoso.Intranet folder located under the Layouts and choose AddNew Folder

4. Rename folder as CSS

5. Right click just created CSS folder and choose Add – Existing Item…

6. Browse to folder c:\Student\Labs\02_UI\StarterFiles\CSS, select all CSS files using ctrl and click Add

a. These CSS files contains the style sheet definitions for the custom master page

7. Double click Contoso.Intranet.Default.master to open that on the working window

8. Locate place in head tags marked with following: <!-- Style sheet registration -->

9. Add following html references to master page to link up CSS style sheets to it


10. Save changes

clip_image001[1]Location for CSS files

Out of the box SharePoint structures deploy css files to Style Library, since files saved there can be modified using SharePoint Designer in the actual deployment. In this case objective is not to provide this customization option in production, so css files are deployed to _layouts folder. It’s always technical decision where to put these kind of files, depending on the business requirements and usage models.

Task 2 – Adding custom navigation control to master page

In this task we add the previously implemented custom navigation page to master page.

1. We’ll need to add that to our custom top navigation user control. Open the master pageand place following registration element on top of the user control just below the Master statement.


2. We’ll still need to replace the fullyqualifiedname inside of the Assembly attribute. We can solve the fully qualified assembly name for example by using gacutil command line tool. Start Visual Studio Command Prompt from Start | All programs | Visual Studio 2010 | Visual Studio Tools

3. Run following command in command prompt – gacutil –l contoso.intranet


4. Copy the fully qualified assembly name to Assembly attribute. In your case the public key token is little bit different, but in the case of this exercise, values is as such:


5. Now that our assembly is registered on the master page, we can add our custom navigation to proper place

6. Locate place in master page marked with following: <!-- Contoso Top Navigation -->

a. You can use find functionality to do this

7. Place following just below the commented marker - Notice that we link this control to ContosoSiteMap portal site map data source, which is located just below the control


8. Save changes · Since we are using custom control in our deployment, we’ll need to add required safe control entry also to web.config as part of the customizations. There are numerous different ways to achieve this automatically from solution package, but let’s now associate entry to module responsible of the master page deployment.

9. Activate ContosoMasterPage module and click […] from Safe Control Entries row in property window


10. Add entry as following to ensure that custom top navigation control added to solution package before will work properly

  • Namespace – Contoso.Intranet.UI.WebControls


11. Click OK and save changes


Task 3 – Testing master page in the site

In this task we ensure that master page is fully functional on the site and also test for the application pages.

1. Right click Contoso.Intranet and choose Deploy

2. Ensure from the Output window that deployment was successful


3. Move to Internet explorer and browse to address http://intranet.contoso.com

4. Choose Site Settings from the Site Actions menu

5. Click Master Pages and page layouts under the Galleries

6. Verify that Contoso.Intranet.Default.master is listed in the gallery


7. Move back to Site Settings page

8. Click Master Page under the Look and Feel

9. Choose Contoso.Intranet.Default.master from the Site Master Page selection


10. Click OK

11. Click the Contoso logo located in the top left corner to move to front page of the site


12. Move back to Site Settings page

13. Click Master Page under the Look and Feel

14. Choose Contoso.Intranet.default.master also to be used as system master page


15. Click OK

16. Notice how the application pages are also using Contoso branded master page



clip_image018Example master page

This Contoso master page has minor rendering issues here and there, but it can be used for demonstrational purposes. Feel free to update or change it anyway you like, if you want to fix rendering issues.


If you find any issues on the lab, please add comments below, so that we are able to fix them as fast as possible. You can also suggest any enhancements for the lab, but due other on-going projects, I can’t promise to have time to include them. Thanks for your comments and feedback advance.

- Vesku