This is the third article in a six-part series on ASP.NET Master Pages and SharePoint.

1. Introduction to Master Pages.
2. Examining the out of the box Master Pages in SharePoint.
3. Developing a custom Master Page for SharePoint.
4. Options to deploy a Master Page for a production ready system.
5. Customizing the Application.master Page.
6. Incorporating a Master Page into a SharePoint site definition

In the previous two articles of this series we discussed master pages and how SharePoint uses them to create it’s out of the box pages. Now that we have an understanding of how master pages work and how SharePoint uses them, we can start showing how to develop custom master pages.

There are two supported scenarios for customizing master pages in SharePoint:

1. Edit the master page in SharePoint Designer
2. Create a custom master page and upload it to the master page gallery

Please notice that modifying the existing master page file is not one of the supported options. Microsoft rarely supports changing files in SharePoint unless it is done from SharePoint Designer.

In this article we are going to concentrate on the “Edit the master page in SharePoint Designer” option. This will show us how to develop a custom master page. In the next article we will learn how to deploy this custom master page for a production ready system.

UnGhosting (Customizing)

When a new site in SharePoint is created it uses the default.master for its master page, which is located at %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\Global.

Note: This is true for WSS team sites and standard MOSS team sites (MOSS publishing sites might use a different master page to start with).

SharePoint keeps a reference to this one file no matter how many sites are created. This is a process called Ghosting, or Uncustomized. Thus, every site collection and/or site in SharePoint point to one file.

If a master page is customized in SharePoint Designer, SharePoint stores a modified version of the master page in the content database (this is a technique called “Unghosting” or “Customizing”). This process basically breaks the reference SharePoint keeps to the default.master file on the 12 hive. The reason for this is that changes will not affect the other content pages that refer to it.

SharePoint Designer can’t modify the default.master page in the 12 hive because it would modify a file that multiple site collections and/or sites use. Instead, it goes through the “UnGhosting”, or “Customizing”, process. This is the process of removing the link to the 12 hive and making a copy of the default.master in the content database.

SharePoint Designer

SharePoint Designer knows about the SharePoint architecture. Since the SharePoint architecture is a mixture of physical files (on the 12 hive) and content (from the database), a web design tool for SharePoint must know about this architecture. SharePoint Designer is the only tool currently available that knows about this architecture. SharePoint Designer knows how to render the structure of the SharePoint site and how to allow for changes using the UnGhosting, or Customizing, techniques.

To modify a master page in SharePoint Designer first open SharePoint Designer on your SharePoint box. Next open the SharePoint site by going to File – Open Site. In the Site Name field put the url to the home page of your SharePoint site, without the actual page in it (i.e.: don’t keep default.aspx in the string).

After you open a site in SharePoint Designer, Designer will create the folder structure for the SharePoint site:

Create a new master page

The master page gallery is located in the _catalogs folder. Within the master page gallery you will find the default.master page. You can modify this file directly, but it is good practice to make a copy of this file and modify the copied file. I am going to call this copied master page “customDefault.master”.

After you make a copy of the master page, the content pages will not know that this is the master page they should use. So, default.aspx is the content page. And if you open default.aspx in SharePoint Designer, you will notice this in the upper right corner:

Notice that it is still pointing to the default.master page. If you want it to point to the new customDefault.master page, then right click on customDefault.master (in the Folder List) and choose “Set as Default Master Page”. After doing this, open the default.aspx page again and notice that the master page referenced changed:

So, why does this reference pointer change, but the MasterPageFile still points to default.master (MasterPageFile=”~masterurl/default.master”). The reason is dynamic tokens. SharePoint replaces “masterurl/default.master” with the dynamic token value at run time. The reference pointer we are seeing is that dynamic token. So, when you click “Set as Default Master Page” in SharePoint Designer, you are changing the dynamic token for the SharePoint site. For more information on dynamic tokens, refer to the second article in this series – Examining SharePoint Master Pages.

Customize the customDefault.master

Open up the new customDefault.master page. If you are using MOSS, SharePoint Designer might ask you to check it out at this point. If you are in WSS, you shouldn’t have to check the file out.

SharePoint Designer has three different modes for customization:

1. Design – WYSIWYG editor
2. Code – html editor
3. Split – keeps the design and code modes open

I prefer to keep SharePoint Designer in split or code mode. The reason is that when you customize a SharePoint master page you have to be careful where you put customizations. If you place a customization in a ContentPlaceHolder, there is a chance the customization won’t show on the final page because the implementing content page might take care of filling in the particular ContentPlaceHolder. So, if you make changes in design mode, it is beneficial to see what is happening in the html.

So, let’s make some customizations so you can see some things that can be done.

Create a footer

1. Find the tag </Body> in your code view and put your cursor right before it.
2. Type the some footer text – ex: Copywrite RDA all rights reserved 2008.
3. Wrap the footer text in a div tag.
4. Set a class to the div tag. For example purposes we can use an out of the box css class from SharePoint

<div class=”ms-CommentFooter”>Copywrite RDA all rights reserved 2008</div>

5. Save the file.

Note: SharePoint Designer should give you a popup telling you that you are about to UnGhost, or Customize, your SharePoint master page. This is your warning that you are going to break that reference to the 12 hive and make a separate master page in the content database. Click Yes.



6. Optional: if you are in MOSS, you might have to check the file back in at this point. Right click on the customDefault.master in the Folder list and choose “Check In”.
7. Open your site in your web browser to see the change.

Create a new style

Our footer example uses the out of the box “ms-CommentFooter” for our css class. This example will show you how to change that to one of your own custom css classes.

1. Change “ms-CommentFooter” to “custom-footer” in the code view

<div class=”custom-footer “>Copywrite RDA all rights reserved 2008</div>

2. Select the “new style” link from the Apply Styles toolbar on the right



3. Set the properties of the style
   • Selector = .custom-footer
   • Font
     • Font-family = Verdana
     • Font-size = x-small
     • Font-style = italic
4. Click Ok on the style popup
5. Save the file
6. Optional: if you are in MOSS, you might have to check the file back in at this point. Right click on the customDefault.master in the Folder list and choose “Check In”.
7. Open your site in a web browser to see the changes

Modify a SharePoint Control

1. Find the top menu in the code view

<SharePoint:AspMenu
ID=”TopNavigationMenu”sdgds
…

2. Change the Orientation to Vertical

Orientation=”Vertical”

3. Save the file
4. Optional: if you are in MOSS, you might have to check the file back in at this point. Right click on the customDefault.master in the Folder list and choose “Check In”.
5. Open your site in a web browser to see the changes. Your menu control should be vertical now.

(Please not the intent of the above change is to show that the out of the box SharePoint controls can be changed. I understand that the actual change we made is not user friendly).

Modify out of the box css classes

1. Find the text “ms-globalbreadcrumb” in the code.
2. Right click on it.
3. Click “Follow Code Hyperlink”
   • a. It will take you to one of the sections for this css class
   • b. The section right above it contains the code for the background color.
   • c. Change the background color to #000000

.ms-globalbreadcrumb{
font-size:8pt;
text-align:right;
background-color:#000000;
padding:2px 10px 2px 5px;
}

4. Save the css file

Note: SharePoint Designer should give you a popup telling you that you are about to UnGhost, or Customize, your css file. This is your warning that you are going to break that reference to the 12 hive and make a separate css file in the content database. Click Yes.



5. Open your site in a web browser to see the changes. The top bar should be black now.

(Please not the intent of the above change is to show that the out of the box SharePoint controls can be changed. I understand that the actual change we made is not user friendly).

Be careful with your power

These are just a few examples of some customizations that can be done to the master page through SharePoint Designer. The customizations you can do are endless. However, you must be careful that you do not customize something that is required for SharePoint to work.

Some examples of controls you don’t want to remove are:

• Site Actions
• Search (if you want search capabilities)
• Navigation menus (unless you want to replace them with your own navigation)
• Etc…

Also, be careful where you make your changes. In the previous articles we talked about how making changes to content within ContentPlaceHolders might get overridden by the implementing content page. Thus, if you make a change to a ContentPlaceHolder, you might not see it on your page. My recommendation is to put SharePoint Designer into Split mode or Code mode so you can edit the html directly and you can be sure that you are not editing html within ContentPlaceHolders.

And remember; don’t remove any of the ContentPlaceHolders. The content pages in SharePoint already have references to these place holders. If you remove them the content pages might break.

Undo your Customizations

After making the change notice the default.master in the folder list on the left side. It now has a symbol next to it. If you mouse over that symbol it will tell you that the page has been customized. This is telling you that you have UnGhost, or Customized, this page at one point.

If you decide that you made a mistake by UnGhosting, or Customizing, your file – then you can undo your changes by “re-Ghosting” the file. To do this, right-click on the default.master file and choose “Reset to Site Definition”.

SharePoint Designer Pros

Easy – SharePoint designer provides an easy experience to customize SharePoint master pages. Any user with html experience should be able to use SharePoint designer to make changes to a master page. As the steps above show – you can just open your master page up, make your changes and then save your changes in SharePoint Designer.

UI experience – SharePoint designer gives you a WYSIWYG (what you see is what you get) UI experience. This means you can make changes to the website through an interface that looks like the website. The other techniques we are going to mention do not allow for this.

SharePoint Designer Cons

Unghosting/Customizing – the Unghosting, or Customizing, technique keeps all changes scoped to the respective site collection. There is no real way to point the master page to another site collection. This can hurt maintainability if you are creating multiple site collections on one SharePoint box and want to keep a consistent master page.

Not Deployable – SharePoint Designer forces you to make changes directly against a SharePoint site collection. This makes it hard to move from a development, to QA, to production environment. This also makes it so the customized master page cannot be used against multiple site collections.

Conclusion

SharePoint Designer provides us a quick way to customize master pages in SharePoint. This is a great tool to design master pages and/or customize an existing SharePoint site. However, SharePoint Designer does not provide a clear deployment path for projects using a development lifecycle. The next article in this series will show how to create custom master pages that can be uploaded to any SharePoint site for easy deployments.

It never fails to happen.  Your company invests in SharePoint, takes time to define business processes and automate them using workflow (with a dash of InfoPath, perhaps), tests the solution to within an inch of its life and finally launches in production.  Two days later, it comes to a screeching halt because the user community isn’t completing system-assigned tasks.  Business processes don’t run to completion, KPIs are flashing amber and red.  Someone has just got around to blaming the problem on global warming …

Of course, failing to complete tasks won’t normally cause that much trouble.  It’s just plain inefficient, even in a simple scenario where a department manager manually creates tasks in a WSS task list.  The manager shouldn’t have to remember to look at an “incomplete tasks view” to find out which department members have overdue tasks.

Users always have plenty of excuses:

• “I can’t find the task.”
• “I didn’t know I was assigned a task.”
• “The dog ate my task.”

This a common business problem and we can solve it.

Companies often turn to some kind of automated reminder system to prod End Users into marking their tasks complete, thereby allowing those beautifuly orchestrated business processes to proceed as designed.  This article describes how “Power” End Users and Developers alike can use SharePoint Designer to create an automated task reminder system based on SharePoint’s core workflow capability.  This solution applies equally well to Windows SharePoint Services 3.0 (WSS) and Microsoft Office SharePoint Server (MOSS).  The article starts off with a little theory and then moves into a painstakingly detailed and lovingly created walk-through describing exactly how to create this workflow solution.   After the walk-through, it describes some important limitations, some technical implications and finally, suggests some useful extensions.

First, the business requirement:

• A task has been assigned to a user.
• The system should send an email to the user every 24 hours until the user has completed the task.

It doesn’t get much more straight-forward than that.

We will use SharePoint Designer to create a workflow solution that meets that requirement.  The solution leverages several SharePoint features:

• Windows Workflow Foundation.
• SharePoint Designer (of course).
• SharePoint workflow’s remorseless nature.

“Remorseless nature” means that a functioning SharePoint environment continues running a given workflow forever unless one of two things happens:

1. The task is deleted.
2. The workflow decides on its own to quit.

Before we fire up SharePoint Designer, we need to consider the workflow’s design:

This looping workflow has one choice to make among three options each time iterates:

1. Is the task complete? If yes, quit. Yeah, we’re done!
2. Is this the first time I’m sending a reminder? If yes, send a reminder and pause one day. Set a flag to indicate that the first reminder has been sent.
3. Is the second or more time I’m sending a reminder? If yes, send it and pause one day. Increment a counter to indicate how many reminders have been sent.

(Developer readers here may be thinking to themselves that these seem a lot like states and/or state transitions.  You’d be correct to think that.)

Pre-Configuration

To support a design like this, we need to add two columns to our task:

1. FirstEmailReminderSent
2. EmailReminderCount

The workflow uses these fields to maintain some information about the task (e.g. was an email reminder sent) as well as to trigger the workflow to run again for subsequent reminders.

These two columns, added via the task list’s settings, look like this:

It’s important to set the default value of FirstEmailReminderSent to “No”.

EmailReminderCount is simply an number with default value of zero.

Walk-through

With this configuration work complete, let’s see all of this in action by creating a workflow.  Firing up SharePoint Designer, we create the workflow in the normal way (i.e. open up the site with the task list, create new SharePoint content, create a workflow).  It looks like this:

The workflow has been named “Daily Reminder,” it’s associated with a list called “Tasks” (i.e. the task list) and here is the key: It’s set to run both when the task is created and when it’s changed.  The “whenever an item is changed” bit is very important, as we’ll see later.  This setting enable us to leverage SharePoint’s remorseless nature to our benefit.

The first step of the workflow is easy: Stop running if the task has been completed:

The second step is more interesting.  This step, labeled “Send Initial Email,” obviously sends the first email.  However, it also sets up the subsequent reminder.  Let’s see how that works:

Note that this task only runs if our task column, “FirstEmailReminderSent” is equal to No.  Since we were careful to specify “no” as this column’s default value, we know this step will run (provided that we got past the first step above).

First, we send the reminder email.

Then, we set FirstEmailReminderSent to Yes.  This ensures that this particular step never runs again.

Next, we pause for one day.

Once our pause completes, we want to start looping.  We do this by “poking” the task by changing any field of the current item.  When we do this, from SharePoint workflow’s  perspective, the item has been changed.  Since we checked “Automatically start this workflow when an item is changed,” it starts the workflow all over again.   We could pick any field but since we need to “poke” the current item, we may as well derive some business value at the same time.  We’ll use the EmailReminderCount field.  This way, we can poke it and know how many times the reminder has been sent, killing two birds with one stone.  The next series of screen shots show how to increment that counter.

First, we create a workflow variable as shown:

Copy the current value of EmailReminderCount to our TemporaryCounter variable using the “Set Workflow Variable” action:

Use the “Do Calculation” action to increment this by one.

Finally, update the Task’s EmailReminderCount using the “Update Field in Current Item” action.

The third and final step looks very similar to the previous:

This step only runs if the task was not marked as completed and if the first email reminder has already been sent.

Workflow pauses for a day and then increments the EmailReminderCount by one.  Performing this update causes the workflow to start over again.  Assuming the user never marked the task as complete, SharePoint workflow skips the first steps (since task is not completed) and the second step (since FirstEmailReminderSent is still Yes), landing back here on the third step.  It sends the email and pauses 24 hours, pokes itself and keeps looping like this, forever, until the task is completed or it’s deleted.

The following series of screenshots capture a test environment where the pause has been set to a short time interval:

In the above screen shot, the system has sent three reminders and is still waiting for the workflow to be completed.

Here is the initial workflow history:

Here is how the task is marked complete:

Here is the final workflow history:

Limitations

SharePoint Designer workflow is … limited.  There are several important limitations, but one of the most important for most users to understand is that these workflow solutions cannot be easily ported from one environment to another.  In fact, they cannot be easily ported anywhere, period.  There are clever workarounds to this problem, but that’s for a future article. (Hint -edit the XOML file directly, replacing task, list and other GUIDs manually).

Second, the workflow history is a bit garbled.  Conceptually, this is just one happy workflow.  However, at a machine/SharePoint level, we really have multiple instances of the same workflow.  This isn’t a problem for SharePoint, but it does sew confusion in a reporting sense.  As the final workflow history screen shows, even though we humans think just one workflow actually ran for this task (the Daily Reminder workflow), SharePoint shows five separate histories.  In our reminder scenario, this really isn’t a problem.  Each workflow history represents one email reminder.  However, if we had extensive logging and other complicated activities taking place, it would be hard to decipher the history and required a lot of clicking.  There is a clever solution to this problem as well, again for a future article.  (Hint – create entries in a custom list using a common key field to group them together).

Finally, it is important to realize that WSS and MOSS service pack 1 introduced a security feature that prevents a system administration account from starting any workflow automatically (though this was recently amended with the 07/15/08 infrastructure update).  If you’re testing this out in your environment and nothing seems to be happening, log in to the system as a non-admin account:

State Machines in SharePoint Designer?  Looping?  Preposterous!

As hinted at early on, this solution actually defines a state machine.  It uses the task itself as a persistent store for state data.  This workflow defines the following states:

• Starting state: Sending a first reminder.
• Reminder state: Sending a subsequent reminder.
• End state: Marking the task as complete.

It’s not hard to imagine creating other kinds of state machines using this approach.

There is a real risk of pushing beyond reasonable business scenarios for which SharePoint Designer was designed (and some might argue that we already have).  Keep that in mind.  A complicated state machine workflow should be developed using visual studio with its close-to-the-metal workflow building tool set.

Extending the Solution

Several common sense extensions come to mind:

• Weekends: Incorporate some logic to determine whether the current date is a non-business day. If it is, simply pause for 24 hours before running again.
• KPIs: Integrate this solution with a KPI. If the user requires many reminders, turn amber and eventually red to indicate a seriously overdue task.
• Escalation: if a given task requires too many reminders, fire off an email to a manager.
• Due Date Aware: Don’t send an email reminder for task unless it has passed its due date.

Conclusion

This article describes a fully functional email reminder system.  The solution leverages core WSS workflow technology and uses a relatively friendly tool, SharePoint Designer, to do it.  This means it does not require MOSS but works in MOSS (since MOSS extends WSS).

Although the business example focuses on tasks, it should be clear that the pattern described here can fit into many different business scenarios that require repetitive (looping) actions over a period of time.  Simply define how the loop should end, what it should do in the first iteration and what it should do for subsequent iterations.

Too often, we hear that SharePoint Designer workflow can’t loop, can’t create state machines, is terribly limited and crippled, etc.  With a little imagination, we can prove the critics wrong and build simple yet powerful workflow solutions using this tool.