(untagged)

Inside Master Pages

Mohamed Sharaf

0.00/5 (No votes)

18 Aug 2005

Every thing you need on master pages. This article takes your from the first step to the depth.

Download source (VB and C#) - 11.8 Kb

Introduction

Master pages are templates for ASP.NET pages. It helps you to create consistence in appearance for your web site with minimum code effort. The great thing about master pages is that they are live templates, you can change them from within the content pages. They are not only for visual consistency but can also act as a global function library. Any function declared in the master page is viewable in the content pages.

Create master page

Creating master page is very simple. From Visual Studio Solution Explorer:

Right click on project name and choose �Add New Item�.
From the templates window, choose �Master Page�.
Choose the language and whether or not it has a code behind page.

Adding controls to a Master page

Master pages are much like normal aspx pages but they don�t have the @Page directive. Instead they contain this directive:

<%@ Master Language="C#" AutoEventWireup="true" 
       CodeFile="myMasterPage.master.cs" Inherits="myMasterPage" %>

Also the extension of the master pages is �.Master� and make sure that you don�t change this extension because this prevents the pages from being browsed by browsers directly. I�ll explain this later in this article.

Now you are free to add any controls or code to your master page. You can add navigation controls such as TreeView or SiteMapPath, you can add a header and footer or any part that you think will be consistent along with your site.

You should note that by default when you create a master page it contains only one control. It�s the ContentPlaceHolder. It�s used by master pages to determine the places where you can add content through content pages. You can have one or more ContentPlaceHolder. The declaration of it should be something like this:

<asp:contentplaceholder id="ContentPlaceHolder1" 
               runat="server">
</asp:contentplaceholder>

Note:

All code snippets in this article are in C#. For full VB.NET code, please refer to the attached source code.

Creating Content pages

To create a Content page from Visual Studio, in the Solution Explorer:

Right click on the project name then choose �Add New Item�.
From the template window, choose WebForm and check the checkbox �Select Master Page�. This will give you the option to select which master page you want to choose.

When you open the web from in the Visual Studio designer, you notice that the controls of the master page appear but you can�t edit them. When you view the source of the content page, it looks like this.

<%@ Page Language="C#" MasterPageFile="~/MasterPages/myMasterPage.master" 
       AutoEventWireup="true" CodeFile="Default.aspx.cs" Inherits="_Default" %>
<asp:Content ID="Content1" ContentPlaceHolderID="ContentPlaceHolder1" Runat="Server">

</asp:Content>

The link between the content page and master page is in the attribute MasterPageFile. The content page doesn�t have any <html>, <body> or <form> tags because they are already present in the master page. Content page can only have Content controls associated with the ContentPlaceHolder control. And any controls/literals should be placed only in this ContentPlaceHolder control.

Now try to add anything to the content page and browse it. You will see the contents of two pages together.

Note

Can I browse master pages directly? No, you can�t because the .master extension is associated with System.Web.HttpForbiddenHandler. So it always gives you the error: �This type of page is not served�. That is why you shouldn�t change the extension of the master file.

Master-Content relation is not inheritance

After having a quick overview about master pages, it�s time to dig through it internally. It might seem that the relation between a Master and a Content page is �Inheritance� like what happens in Windows Forms visual inheritance. But in fact it�s far from the truth.

Master pages are actually user controls. When you see the code file of your master page, you will find that it inherits the class MasterPage which in turn inherits UserControl.

The complete family tree is shown in the image below:

What actually happens when the user requests a web form in ASP.NET 2.0 is:

The ASP.NET runtime checks to see whether the page has a master page.
If the page is associated with a master page, the runtime first initializes the master page.
The runtime merges the content of the master page with the content of the Content page. That happens in the init event of the web form, see performPreInit() method of the System.Web.UI.Page class.

private void PerformPreInit()
{
  this.OnPreInit(EventArgs.Empty);
  this.InitializeThemes();
  this.ApplyMasterPage();
  this._preInitWorkComplete = true;
}

Runtime sends the output of merged pages to the client.

How controls are arranged in the output

The master page is working as a container for the controls inside it. If you examine the trace output of this page, you will find something like:

Ctl00 is the ID of the master page and all the controls inside the master page begin with ctl00$<control name>. One of the implications for this is if you try to get any control in the master page from the content page using code like this:

TreeView tv=(TreeView) this.FindControl(�TreeView1�);

it will not succeed.

How to interact with master page controls from content page

The next question is �How to change something in the master page from the content page?�. To do that, the product team changed the Page class to add a new property in it called Master. This is its signature:

public MasterPage Master
{
  get{}
}

It returns an instance of the MasterPage class. To access controls inside the master page, there are two methods:

Using public properties/methods
If you noticed, the content page doesn�t have <header> and <title> tags. So if we want to change the title of the content page �and this is mandatory- we need to access the <title> tag. First we need to change the title tag so it is accessible from the code page. Simple, we need to add id and runat attributes as follows:
```
<title id="pageTitle" runat="server"></title>
```
Then, in the master page, add this property:
```
public string mainTitle
{
  set
  {
    pageTitle.Text = value;
  }
}
```
And finally on the content page, we add this snippet on the Load event.
```
myMasterPage myMaster = (myMasterPage)this.Master;
myMaster.mainTitle = "Playing with master pages :)";
```
Using the FindControl method
Let�s say that I have a ListBox control on the master page called listBox1. And I want to access it. We don�t need to add any code in the master page. Just in the content page, add:
```
myMasterPage myMaster = (myMasterPage)this.Master;
ListBox masterListBox = myMaster.FindControl("ListBox1") as ListBox;

if (masterListBox != null)
  masterListBox.Items.Add("accessed from content page");
```
Note:

Because the Master property returns a reference of type MasterPage, we need to cast it to myMasterPage type. We can avoid this by adding the @MasterType directive in the content page as follows:
```
<%@ MasterType TypeName="myMasterPage" %>
```
Then we can change the line of getting a reference to the master page to be:
```
myMasterPage myMaster =this.Master;
```

Calling functions from the master page

We can use the master pages not only as visual templates but we can also use them as function libraries where we can add the most common, UI-related functions.

But take care to not add a lot of code because it will be loaded with each and every page in your web site.

Let�s say that we have a function called masterFunction as follows:

public string MasterFunction()
{
  return "this is returned from master page";
}

We can simply call it with this code snippet.

//make sure that you added the MasterType directive.

myMasterPage myMaster =this.Master; 
lblTest.Text = myMaster.MasterFunction();

When is my code executed?

That�s a very important question to ask, when you put code in the master and content pages� Load event, which one will be executed first? Well, it�s in this order:

Master � initialize.
Content- initialize.
Content- load.
Master � load.
Content- render.
Master- render.

I did a nice code sample that demonstrates the event order. Take a look at the code attached with this article.

Master pages don�t support themes

Master page don�t support themes simply because the System.Web.UI.Page.PerformPreInit() method initializes the theme for any web form and then apply the master page. That�s why master pages throw an exception if you try to apply themes on them. See code below:

void PerformPreInit()
{
  this.OnPreInit(EventArgs.Empty);
  this.InitializeThemes();
  this.ApplyMasterPage();
  this._preInitWorkComplete = true;
}

But if the content page has a theme, it will be applied on the whole output later after merging the master and content pages.

Take care of URLs

If we have an image control on the master page (or any control that references URLs), and we have a relative URL (something like images/myImage.gif) which is relative to the place of the master page in the web site, but when the master page is merged in the content of the content page, what will be the situation? Don�t worry about that, the ASP.NET runtime will take care of converting any URLs to the appropriate ones.

But take care of non-server-control tags like the <img> tag. ASP.NET runtime has no control over HTML tags so you need to avoid relative URLs with any HTML tags in master pages. For example, you can add a URL to an image using http://mysite.com/myfolder/image.gif.

Adding a Master page to the whole site at once

If you have a single master page that you wish to add to all your web forms without specifying the MasterPageFile attribute on every page, you can add this on the web.config.

<pages masterPageFile="mySite.master" />

Nested Master Page

Master pages can be nested. You can use this feature to distribute your master pages design among more than one master page. The only defect using this strategy is that Visual Studio doesn�t support nested master pages. So you have to work without Visual Studio designer.

Note:

Any master page that has another master page should be treated like the content page so it can not have anything outside the Content control. So the only page that will have <head> and <body> tags is the topmost master page.

Let�s say that you have a page called nestedMasters.aspx which has a master page called childMaster.master and this master page has another master page called topMaster.master. The code of the topMaster.master would be like this:

<%@ Master Language="C#" AutoEventWireup="true" 
  CodeFile="topMaster.master.cs" Inherits="topMaster" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
       "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
 <head runat="server">
  <title id=pageTitle runat="server">Untitled Page</title>
 </head>
<body>
 <form id="form1" runat="server">
  <div>
   <table width="100%">
    <tr width=100%>
     <td width=100% bgcolor="#99ff99">This is the parent master page<br />
      <asp:Label ID="label1" runat="server" Text="Label" Width="351px"></asp:Label>
     </td>
    </tr>
    <tr width=100%>
     <td width=100%><asp:contentplaceholder id="ContentPlaceHolder1" runat="server">
       </asp:contentplaceholder></td>
    </tr>
   </table>
  </div>
 </form>
</body>
</html>

And the childMaster.master code is:

<%@ Master Language="C#" AutoEventWireup="true" CodeFile="childMaster.master.cs" 
  Inherits="childMaster" MasterPageFile="~/MasterPages/topMaster.master" %>
<asp:Content ID=content1 runat="server" ContentPlaceHolderID=ContentPlaceHolder1>
<table width=100%>
<tr width=100%>
<td width=100% bgcolor="#00ccff"> This is child master page<br />
<asp:Label ID=label1 runat="server" Text=Label />
</td>
</tr>
<tr width=100%>
<td width=100%><asp:ContentPlaceHolder ID=contentPlaceHoder1 
     runat="server" EnableViewState=true></asp:ContentPlaceHolder></td>
</tr>
</table>
</asp:Content>

And the nestedMasters.aspx should be like this:

<%@ Page Language="C#" MasterPageFile="~/MasterPages/childMaster.master" 
    AutoEventWireup="true" CodeFile="nestedMasters.aspx.cs" 
    Inherits="nestedMasters" 
Title="Untitled Page" %>
<asp:Content ID="Content1" ContentPlaceHolderID="contentPlaceHoder1" 
        Runat="Server">This is content page
</asp:Content>

Creating nested master pages is very simple. But when it comes to interaction between content page and master page, it needs us to pay attention to some issues.

Arrangement of controls in the output page is very important to know if you want to deal with nested master pages. Take a look at this image of page tracing:

Note that the content page is the container for the childMaster and the childMaster is a container for topMaster, and all the controls declared in childMaster and topMaster are inside the topMaster. To differentiate between the controls that are in childMaster and topMaster, all childMaster controls are found in the ContentPlaceHolder1 control in topMaster.

This will lead us to another question, What about the interaction between the content page and the master pages?

The only visible class to the content page is the direct master page. The content page can�t create a reference of the type of any master page other than its direct master page. So you can�t use them directly from the content page. To overcome this, I found two ways to do this.

Using Properties/Methods

You can use properties or methods only in the childMaster page (the direct master page to the content page). And the properties or methods in the childMaster change the controls in the topMaster.

Let�s say I want to change two controls:

Label on the childMaster master page.
The HTMLTitle on the topMaster master page.

In the childMaster, add these two methods:

public void changeLocalControl(string controlName, string newValue)

{
  if (controlName == "label1")
  {
    label1.Text = newValue;
  }
}

public void changeMasterControl(string controlName, string newValue)
{
  topMaster myMaster = (topMaster)this.Master;
  if (controlName == "pageTitle")
  {
    HtmlTitle title = myMaster.FindControl("pageTitle") as HtmlTitle;
    if(title !=null)
      title.Text=newValue;
  }
}

In the changeLocaControl method, you simply change a control that is in the same page you are in. Just reference the control by its ID as usual.

In the changeMasterControl method, you declare a reference to the topMaster class and assign to it the result of the Master property of the childMaster class. Then using FindControl method, get a reference to the HTMLTitle object in the topMaster class and then change it.

Using FindControl from the content page directly

If you are in a hurry and you don�t want to bother yourself with writing properties or methods in the childMaster page, you can directly access any control in the topMaster page by the following method.

According to the trace output earlier, all controls on childMaster and topMaster reside in the topMaster page.

To get a control in the topMaster page, use the Master property of the childMaster to get a reference of the topMaster class, then use FindControl to get the control, see the code snippet below:

Label lbl = myChildMaster.Master.FindControl("label1") as Label;
lbl.Text = "testing";

To get a control in the childMaster page, it�s a bit tricky but keep in mind two things:

All controls are in the topmost master page.
Controls that belong to child master pages are in the appropriate ContentPlaceHolder control in the topmost master page.

Now take a look at the trace output and check this code snippet below:

Button btn = 
  myChildMaster.Master.FindControl("ContentPlaceHolder1").FindControl("button1") 
  as Button;
btn.Text = "by the content page";

In this code, I get a reference to the topMaster page using the Master property of the childMaster page, then I dig through the controls hierarchy to reach button1 through the ContentPlaceHolder1 control.

I hope I could shed light on Master Pages and I�m waiting for your feedback :)

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here