Inside ASP.NET Master pages

Inside ASP.NET Master Pages

Introduction

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

Create master page

Creating master page is very simple. From Visual Studio solution explorer:

Adding controls to Master page.

Master pages are much like normal aspx pages but it doesn’t have the @Page directive. Instead it contains this directive

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 controls, you can add a header and footer or any parts that you think that it will be consistent along with your site.

You should note that by default when you create 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.

Note:
All code snippet in this article in C#, For full VB.NET code, please refer to the attached source code.

Creating Content pages

To create Content page from Visual Studio, in the solution explorer

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

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

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

Master-Content relation is not inheritance.

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

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

How controls arranged in the output

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

Ctl00 is the id of the master page and all controls inside the master page begin with ctl00$
One of the implications for this is if you tried 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 master page from content page?”
To do that, the product team changed the Page class to add new property in it called Master. This is the signature of it.

public MasterPage Master{get{}}

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

1) Using public Properties/Methods
If you noticed, the content page doesn’t have

and

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 :)";

2) Using 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 class. We can avoid this by adding the @MasterType directive in the content page as following
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 a visual template but we can also use it as function library 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 following

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 my code is executed?

That’s 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 doesn’t support themes simply because the System.Web.UI.Page.PerformPreInit() method initialize the theme for any web form then apply the master page. That’s why master pages throw exception if you tried 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 page.

Take care of URLs

If we have image control on the master page (or any control that reference URLs). And we have a relative URL (something like images/myImage.gif). It’s 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, ASP.NET runtime will take care of converting any URLs to the appropriate ones.

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

Adding Master page to the whole site at once

If you have a sing;le 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

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 and 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

This is the parent master page

And the childMaster.master code is:

This is child master page

And the nestedMasters.aspx should be like this:

This is content page

Creating nested master pages is very simple. But when it comes to interaction between content page and master page, it needs us to pay attentions 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 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

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 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 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 then change it.

Using FindControl from 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.

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.
1) All controls are in the topmost master page
2) Controls that belongs to children 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 the button1 through the ContentPlaceHolder1 control.

I hope I could shed a light on Master Pages and I’m waiting your feedback :)

You can also find more articles in my blog