My Portal Project

When you want consistency in your Domino site design, you use ViewTemplates and SubForms. In .NET you would use Master Pages, which is the topic of this installment in the .NET for Domino Developers series.

We have all done it, creating lots of ViewTemplates for our Domino views, or creating them so they can use the querystring to determine which view to show, and/or using sub-forms in our forms to show re-usable headers and page navigation, all of this to create a browser application with a consistent look, feel, and behavior. In my opinion this is one place where Microsoft has really used the talent they hired from IBM, because the Master Page concept works well for me.

Microsoft designers have created the Master Page concept from a completely different design perspective than the ViewTemplates/Subforms idea. With .NET you create your wrapper, and drop your presentation/logic components into the wrapper. Not the other way around where Domino has you creating your wrapper in pieces and dropping them into your presentation/logic layer.

Let’s take a look at an example:

In Visual Web Developer, let’s create a new Page by right clicking on the project name in the Solution Explorer (upper right pane), and selecting “Add New Item”.

Then selecting “Master Page” from the new item list.

One of the first things to notice is that the Master Page has its own HTML form, which means that whatever content you create with this Master Page cannot use its own form. This may seem like a drawback since many of us have used multiple forms on a page to seperate things like a global search, a login, and or a workflow form. But you need to remember two things: one is that HTML sends the name/value pair of a button in its POST string which can be used to determine where the user clicked, and second is that .NET captures that information for you. So even if you have three seperate places on a page where you would think you needed a seperate HTML form, you do not have to think that way since the code you write for each button’s click event will determine which fields to pull from the form.

The second thing to notice on the Master Page, is this new control:

This is the meat of the Master Page design concept in .NET; create your wrapper with content space reserved for the eventual content. When we create a new content page with this Master Page, we will only be able to edit content within these placeholders. So let’s create a few placeholders on this page to map out a location for a header, another for left-hand navigation, and a third for the actual page content. Let’s start with just creating an HTML table within the Master Page form tags.

So we have our basic three pane browser application layout with placeholders for the appropriate content, but before we create a page with this Master Page, let’s cover another good reason to like Master Pages. In the previous installment I had profiled a very DB/Directory agnostic method to authenticate users to an application by using the Session object and some home-grown tables. In that installment, I had shown code that you could place in each page to be secured, which would be a real pain if you had dozens of pages to secure. With Master Pages, you place this type of code in one place. So in the “myMaster.master.vb” file, we can create a Page_Load method where we place that credential checking code. Then, every page we create with that Master Page will share that security envelope. The same applies for CSS, and Javascript includes; one place to maintain code references instead of dozens.

So from the Master Page developers can create content with a consistent presentation and security wrapper. Developers can also create dynamic pages where the various content that replaces the placeholders is determined on the fly. So a single Master Page can power an unlimited number of content pages where the logic fills in the gaps. In addition to that, you can also programmatically change the Master Page during the rendering process. That is a somewhat more advanced topic for a future installmnet since there are some serious considerations with respect to event ordering, but it can be done.

In my example, I will change the Master Page code so there is only two editable sections which will be the left navigation pane, and the main area in the middle of the page. I’ll just use a basic image as the header for the Master Page. I’ll then create the content page using two methods; the first will be the easy way which is to create one from scratch. The second will be migrating an existing page into a Master Page. So let’s save our Master Page, and create a new Web Form. This time we will check the “Select Master Page” option.

Now that we have our new page built from our Master, did you notice how different the code for this new page is from any other web form? Just a command line to specify the Master Page to inherit, and references to the content placeholders.

So for the sake of simplicity, I am going to place some screen-shots of other pages into the placeholders so you can see how things will look when you test the page. Here is what the code looks like with my images embedded:

This is what the page looks like when I test it in a browser.

It is that simple. All of your CSS, Javascript, and security can reside in a minimal number of Master Pages to be used without any additional effort. Even the code you write for each page is combined. So you can place code in your Master Page loading event, and in the content page’s loading event, or in any event for any object on either the Master or content pages. Now let’s cover migrating an existing page into a new page using a Master template. In a nutshell it is a simple copy and paste.

First create a new master page the same way we did the first time. Then, leaving that new page in an open tab, open the page you wish to migrate and switch it over to the “Source” view. Then from the source view of the page you want to migrate, copy everything in between the “Form” tags using CTRL-C.

Then paste (CTRL-V) this code between the ContentPlaceHolder tags in the new page that uses the Master Page. At this point, switching over to the “Design” view will show you your content within the Master Page template, but you will also need to migrate all of your VB code from the page to be migrated to the VB page of the new page that uses the Master Page. This is where it can get sticky if you have any functions with the same name in the two code streams. For the most part, if you actually name your design objects, you should not have too much of a problem as the default naming convention for subs and functions uses the design objects name.

In the next installment I’ll talk about custom controls in .NET which, in some ways, resemble sub-forms, but are a topic on their own because of the execution order for a .NET page that uses controls. As usual, any questions or corrections, you know where to find me.

This entry was posted on Monday, February 27th, 2006 at 6:49 pm and is filed under .NET for Domino Devs. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.