Published on ONDotNet.com (http://www.ondotnet.com/)
 See this if you're having trouble printing code examples

Liberty on Whidbey

Master Pages in ASP.NET

by Jesse Liberty

On many web sites, it is important to achieve a consistent "look and feel" as the user moves from page to page. While this was possible with .NET 1.1, it was difficult and required both programmer and designer discipline. ASP.NET 2.0 makes this far easier with the creation of master pages.

A master page provides shared HTML, controls, and code that can be used as a template for all of the pages of a site. Thus, you might create a master page that has a logo (e.g., the O'Reilly tarsier) and an image (e.g., the O'Reilly header) and share these images on multiple pages, as shown in Figure 1:

Figure 1. Consistent look and feel

Here's how you do it. First, begin by creating a new Web Site (Call it "MasterPages"). Right-click on your project and choose Add New Item. From the Add New Item dialog, choose Master Page, and name your master page "TopMasterPage." as shown in Figure 2.

Figure 2. New master page object

Note: The names of your project, master pages, and other pages in this example can be anything you want.

You'll note that your new master page has been created with an asp:contentplaceholder control already in place. It is this placeholder that will be filled by the content of the pages that use this master page. Within the Master page, you may add anything you like surrounding the asp:contentplaceholder. For example, you might add the logos you captured earlier, as shown in Figure 3.

Figure 3. Editing the master page

For convenience, I've numbered three areas on Figure 3: the first image (1), the second image (2) and the ContentPlaceHolder object (3). Notice also that the ContentPlaceHolder tells you to click on it to add text. You may add text to the master page's ContentPlaceHolder, which will act as default text (typically replaced in the pages that use this master page).

Adding Content Pages

The pages you'll add that will use this master page will put all of their content into the ContentPlaceHolder you've added to the Master.

Note: You can put more than one ContentPlaceHolder object on a master page (each has its own ID), so this does not limit your flexibility.

To see how this works, create two new .aspx pages, named Welcome.aspx and SecondPage.aspx. Be sure to make these normal "Web Form" pages and be sure to check Select master page, as shown in Figure 4:

Figure 4. Creating a new Web Form to use with the master page

When you click the Add button, you will be brought to a dialog to select the master page you wish to use. Choose TopMasterPage.master and click OK. Your new Welcome.aspx page will be shown (in Design Mode) within the master page. The Content box will allow you to add any content you like, including controls, text, and so forth, as shown in Figure 5, but the contents of the master page will be disabled. This allows you to see how your new page will look when it is combined with the master page at run time.

Figure 5. Editing content inside of a master page

When you create SecondPage.aspx, you'll use the same master page, thus ensuring that the look and feel of the two pages is identical.

Using Sub-Master Pages

It is not unusual for you to want to have certain elements that are stable throughout the entire application, but other elements that are shared only within one part of your application. For example, you might have a company-wide header, but then have division-wide elements, as well. ASP.NET 2.0 lets you create sub-master pages. Any given .aspx page (web form) can be combined with a sub-master or with the original master, whichever makes more sense for that individual page.

To illustrate this, we'll create a sub-master page called OnDotNet.master. This sub-master page will have as its master page the TopMasterPage we created earlier, but it will add, within its Content control, an image and its own Content place holder (with its own default text). Unfortunately, you cannot use the designer (at least in its Beta form) to examine sub-master pages, but you can see the effect once you create an .aspx page that uses this sub-master. The code to create the sub-master is shown in Figure 6:

Figure 6. Hand-creating a sub-master page

The new sub-page has a Master directive, just like the topmost master page, but this sub-master adds one attribute: MasterPageFile (shown highlighted in Figure 6) which is not in the topmost master page. This indicates that the current master page (OnDotNet.master) is a sub-master to TopMasterPage.master.

To use the sub-master, let's create two additional .aspx pages (OnDotNetPage1.aspx and OnDotNetPage2.aspx). In the first, add an <asp:Content> block that adds text to the page. In the second, leave the block out entirely, thus using the default text provided by the OnDotNet.master page. The results are shown in Figure 7:

Figure 7. The sub-master page

Each of these pages is divided into three areas. The topmost area has the O'Reilly logos from TopMasterPage.master. The middle area has the OnDotNet.com logo from the sub-master page OnDotNet.master. Finally, each of the .aspx pages has content. In OnDotNetPage1.aspx, you see the custom content you added taking the place of the default text. Since OnDotNetPage1.aspx did not add content, it inherits the default content from OnDotNet.master.

You can have multiple sub-master pages that all share a common master page. For example, you might create a second sub-master named Liberty.Master, as shown in Figure 8:

Figure 8. Adding a second sub-master page

This new sub-master uses a different image, and adds text (shown circled in red). You could, of course, make significant differences in each of your sub-master pages (e.g., one might add a layer of menus, another might add a site map, and so forth).

To see your new sub-master at work, create three new pages: LibertyOnWhidbeyPage1.aspx, LibertyOnWhidbeyPage2.aspx, and LibertyOnWhidbeyPage3.aspx. All three of these new pages will share the top master page with the OnDotNet pages, but these new pages will have their own middle section created by the Liberty.master sub-page, as shown in Figure 9:

Figure 9. All of the master pages

Dynamically Editing the Master

You may decide that in response to certain events, you'd like to reach up into the master page (from an .aspx page) and change its presentation. This can be done by exposing a property in the master page and then using the master member of your .aspx page to access that property.

Note: You can also accomplish this task with late-binding using the FindControl() method, but that uses reflection and is considerably slower.

For example, you might add a property to your LibertyMaster.master page that gets and sets the URL for the libertyImage image file shown declared in Figure 8 (above). The actual code is written into the code behind page (Liberty.master.cs), and might look like this:

public partial class Liberty_master
   public Image LibertyImage
      get { return this.libertyImage; }
      set { this.libertyImage = value; }


Once you have that property declared in the master page, you can access it in the .aspx page, as follows:

public partial class LibertyOnWhidbeyPage3_aspx
  public void Page_Load( object sender, EventArgs e )
    this.Master.LibertyImage.ImageUrl = "~//dotnet/2004/09/27/graphics/Triangle.jpg";

The result is that when the page LibertyOnWhidbeyPage3.aspx loads, the image normally used in the Liberty.master is changed for this specific page, as shown in Figure 10:

Figure 10. Dynamically edited masters

As you can see, while LibertyOnWhidbeyPage1.aspx uses the image supplied by LibertyMaster.master, LibertyOnWhidbeyPage3.aspx actually changes that image in the master page, before displaying. This allows you to have your cake and eat it, too; that is you can modify your template when needed, but use the template as designed for most pages, to create a consistent user interface.


Jesse Liberty is a senior program manager for Microsoft Silverlight where he is responsible for the creation of tutorials, videos and other content to facilitate the learning and use of Silverlight. Jesse is well known in the industry in part because of his many bestselling books, including O'Reilly Media's Programming .NET 3.5, Programming C# 3.0, Learning ASP.NET with AJAX and the soon to be published Programming Silverlight.

Return to ONDotnet.com

Copyright © 2009 O'Reilly Media, Inc.