Master Page, Page Layout and Content Types

One of the MOSS 2007 buzzwords is master pages. But what all does that entail? How does the master page work with the content in the site and how do we do things like add web part zones and field controls? To aid and benefit SharePoint designers and those of us assigned to user interface customization, here is a breakdown of the relationships between master pages, page layouts, controls and content types. This is not a technical breakdown with sample code, this is just to explain the relationships between these core concepts in MOSS 2007.

Master Pages

Master pages are not a new concept or feature unique to SharePoint. Master pages were introduced with ASP.NET 2.0 as a way to centrally house and control the layout and design of a web site or application. A single master page file can control the look and feel of countless pages within a site/application. It is basically a next generation approach of how to include common content in lieu of frames or server side includes files.

There is a lot of documentation already out there about master pages, and much of the knowledge can easily be utilized for developing and implementing master page files for SharePoint.

Content Pages

Content pages is the other half of master pages. Master pages store the layout and design, while content pages define the content. The content page is bound to a master page. Together the two create the presentation layer of content for a site/application.

In SharePoint content pages are called Page Layouts. But they work similar to content pages. The master page file is combined with the page layout to create the presentation layer of content for the SharePoint site.

Master Page and Page Layout combine to create the rendered page

Master Page/Content Page Resources

• ASP.NET Master Pages Overview
• Introducing ASP.NET 2.0 Master Pages

The Components of a SharePoint Master Page File

The master page will contain all of the user interface layout code for the site. This includes CSS, JavaScript and HTML. Examples of what you would put in the master page:

• Header code including company logo and branding images
• Navigation
• Footer code including copyright statements and links
• CSS (cascading style sheet) styles
• Body background colors, images or styles
• Common JavaScript functions

The other core component that is used in a master page file are the Content Placeholders. A Content Placeholder is just that, a location flagged as where content will be inserted. The content is stored in the page layouts. The content placeholders designate where the content from the page layout will be inserted in the master page. So for example, a simple master page could flow like this:

1. Registry tags, opening HTML/Body tags
2. CSS Styles
3. JavaScript Functions
4. HTML code for the header
5. Content Placeholder for the main content of the page
6. HTML code for the footer
7. Closing Body/HTML tags

A Content Placeholder looks like this:
<asp:ContentPlaceHolder id="MyPlaceholder" runat="server" />

Content Placeholders can be wrapped in HTML code, for example DIV, SPAN or TABLE tags. A good way to think about it is everywhere you would place content that you would like to have customized for each page, insert a Content Placeholder.

There are a set of required Content Placeholders for SharePoint. Without these placeholders, the site will not work. If you don't want to display all of the placeholders on your site, you can hide the placeholders by grouping them in a hidden ASP:Panel control, or individually set each placeholder with a visibility of false (visible="false").

Nesting and components of a Master Page File

For a full list of the content placeholders used in SharePoint, refer to the SDK (list to be included on this site in the future). For the base code including the bare minimum needed for a SharePoint master page, refer to this article:

·  How to: Create a Minimal Master Page

The Components of a Page Layout File

The page layout contains all of the Content Controls that match the content placeholders from the master page file. For example, the matching content control from our sample master page content placeholder from above would look like this:

<asp:Content ContentPlaceholderID="MyPlaceholder" runat="server">
        Insert field controls, web part zones or HTML code here
  </asp:Content>

Page layout content should be content that will change from page to page, for example:

• Title, Author, Byline
• Body Text

With the exception of the Registry tags, nothing can be outside of a content control in the page layout file! If you try to wrap HTML or add extra code outside of the content control, it will break the page.

SharePoint content is added to the content controls in a page layout in one of two ways, Field Controls or Web Part Zones.

Field Controls are content areas that map to columns in the Content Type. Field control placement is controlled in the page layout file and can't be moved by the content editor through the web interface. They are ideal for situations where excerpts of content need to remain in a fixed location on a site. A field control looks similar to this:

<SharePointWebControls:TextField FieldName="ArticleByLine" runat="server"/>

Web Part Zones on the other hand allow content editors to add and move content around on the page. They work very similar to how they did in SharePoint 2003. The web part zone is specified in the page layout, and then the content editor can choose to add, remove or rearrange web parts within the specified zones. A web part zone looks similar to this:

<WebPartPages:WebPartZone runat="server" AllowPersonalization="false" FrameType="TitleBarOnly" ID="MiddleRightZone" Title="Middle Right Zone" Orientation="Vertical"><ZoneTemplate></ZoneTemplate></WebPartPages:WebPartZone>

Nesting and components of a Page Layout File

Content Types

Content Types are a new feature/concept of SharePoint 2007. They definitely warrant learning about and gaining an understanding of. A content type is a collection of settings that is applied to a particular category of content that can be reused multiple times. Through content types you can manage metadata and the behavior of a document or item type in a central, reusable way. Please refer to the following additional resources for a more in depth explanation of content types:

• Introduction to Content Types
• Plan content types [Office SharePoint Server]
• What Are Content Types, Anyway?

Columns from a content type are referenced through the field controls in the page layout. One content type can be reference by multiple page layouts, but a page layout can only reference one content type. This allows you to easily change the page layout of a page in a site without compromising the content since the content is controlled in the content type. The only restriction is to change the page layout to another page layout that is based on the same content type as the original.

Relationship between Content Types and Page Layouts, shown here wrapped with Master Pages. Click for a larger view.

A Few More Core Concepts and We Are Done…

Master Page Inheritance

Master page files can be applied on a site level, but not on a page level. So a sub site can have a different master page specified than the parent, or it can inherit the master page file settings from the parent.

Master page inheritance among sites and sub sites.

The Pages Library

When you create a page on a site, the page is stored in a Pages document library in the content database. A physical file is not created on the web server. The Page settings specify a page layout that can be changed to another page layout (that uses the same content type). Pages can be moved between Page libraries in a site collection. Each site has its own Pages library. Because the Pages are stored in a library, they can have version history; check in-check out, publishing and workflow capabilities.

Pages library relationships with sites.

The Silo Approach United

All of the components that contribute to the rendered SharePoint page is stored in silos... master page, page layout, page, content type and all the bits in between that link them together. To connect it all:

• A Page is stored in a Pages library within a site.
• The Page references a Content Type that helps populate the page with data. Content types are stored within a site.
• A Page Layout is applied to the Page to control what content appears and where through the use of Field Controls and Web Part Zones. This is specified within the Content Controls in the Page Layout.
• A Master Page is applied to the site to wrap on the look and feel and control content placement from the Page Layout through the use of Content Placeholders.

A snapshot of the silos layered together to create the rendered page...

Event Handlers in SharePoint

Overview:

What is a custom event handler? A custom event handler is a .Net assembly that contains the additional business logic you need to run when the event occurs in SharePoint.

Event handlers allow you to add [SOMETHING] your business needs into the functionality of SharePoint. [SOMETHING] examples:

1.       Retrieve information from a database such as filling in the remaining fields of a list based on a CustomerID (assuming you don't have an enterprise license for BDC)

2.        Call a web service

3.        Start a workflow

4.        Perform list data validation

5.       Convert document to PDF and store in alternative list.

6.       Access data in another list

Event Types:

a.       Microsoft.SharePoint.SPWebEventReceiver : "Site Level"

SiteDeleted	Occurs after a site collection has been deleted.
SiteDeleting	Occurs when a site collection is being deleted.
WebDeleted	Asynchronous Afterevent that occurs after an existing Web site is completely deleted.
WebDeleting	Synchronous before event that occurs before an existing Web site is completely deleted.
WebMoved	Asynchronous after event that occurs after an existing Web site has been moved.
WebMoving	Synchronous before event that occurs before an existing Web site has been renamed or moved to a different parent object.

b.      Microsoft.SharePoint.SPListEventReceiver : "List Level"

FieldAdded	Occurs after a field link is added.
FieldAdding	Occurs when a field link is being added to a content type.
FieldDeleted	Occurs after a field has been removed from the list.
FieldDeleting	Occurs when a field is in the process of being removed from the list.
FieldUpdated	Occurs after a field link has been updated
FieldUpdating	Occurs when a field link is being updated

c.        Microsoft.SharePoint.SPItemEventReceiver : "List Item Level"

ItemAdded	Asynchronous After event that occurs after a new item has been added to its containing object.
ItemAdding	Synchronous before event that occurs when a new item is added to its containing object.
ItemAttachmentAdded	Asynchronous after event that occurs after a user adds an attachment to an item.
ItemAttachmentAdding	Synchronous before event that occurs when a user adds an attachment to an item.
ItemAttachmentDeleted	Asynchronous after event that occurs when after a user removes an attachment from an item.
ItemAttachmentDeleting	Synchronous before event that occurs when a user removes an attachment from an item.
ItemCheckedIn	Asynchronous after event that occurs after an item is checked in.
ItemCheckedOut	Asynchronous after event that occurs after an item is checked out.
ItemCheckingIn	Synchronous before event that occurs as a file is being checked in.
ItemCheckingOut	Synchronous before event that occurs after an item is checked out.
ItemDeleted	Asynchronous after event that occurs after an existing item is completely deleted.
ItemDeleting	Synchronous before event that occurs before an existing item is completely deleted.
ItemFileConverted
ItemFileMoved	Occurs after a file is moved.
ItemFileMoving	Occurs when a file is being moved.
ItemUncheckedOut	Synchronous before event that occurs when an item is being unchecked out.
ItemUncheckingOut	Synchronous before event that occurs when an item is being unchecked out.
ItemUpdated	Asynchronous after event that occurs after an existing item is changed, for example, when the user changes data in one or more fields.
ItemUpdating	Synchronous before event that occurs when an existing item is changed, for example, when the user changes data in one or more fields.

Asynchronous vs Synchronous Events: The "ing" and the "ed"

As you might have noticed above, there are two events raised for each type of event. The "...ing" event occurs before the action starts and the "...ed" occurs after the actions ends. "...ing" events occur synchronously while the "...ed" events occur asynchronously. What does this mean?

Synchronous events:

·         Occur before the event.

·         Block the flow of code execution until your event handler completes.

·         Provide you with the ability to cancel the events resulting in no after event (“...ed") being fired.

Asynchronous events:

·         Occur after the event.

·         Do not block the flow of code execution in SharePoint.

When building custom event handlers, keep the following points in mind:

1. Security:

The assembly you deploy to the Global Assembly Cache(GAC) is running with full trust. Watch out for the following:

 Denial of Service attack: If a user uploads 10000 items to a list, what is the effect it will have to the systems your assembly uses.

SQL Injection attack: If a user attempts to insert SQL statements into a column of a list that your assembly uses to update a database, what mechanisms are you using to make sure the input is valid.

Cross Site scripting attack: What is the effect of adding script to a column that your assembly uses to update another area in SharePoint?

2. Performance:

Watch out for the following:

Load: What burden are you placing on your web front end servers to run the assembly each time an event occurs? Use performance counters to determine this.

Long Running Operations: Consider creating a custom SharePoint timer job. Kick off/ Schedule the Timer Job from the event rather than running all the logic inside the event. This will allow you to use the features of SharePoint to view whether the Timer Job ran successfully.

Sync vs Async Events: Synchronous events have to wait until your code completes before returning the page, whereas Asynchronous events show the page immediately.

3. Error Handling:

When using synchronous events and you decide to cancel an event, let the user know why the event was cancelled. For example, update a Task List with a message why it failed.

Log your errors so that you can determine what issue is occurring when your system is in production environment.

4. Connections: Cater for external systems being down when you are trying to connect to them. Don’t let your code / solution go belly up because you cannot connect to a database.

5. Bulk Operations:

The MSDN documentation mentions that event handlers will not fire when bulk operation is occurring. For example, when a new list is created, the FieldAdding event will not fire. 

Limitations of Event Handler in SharePoint

Strangely there is no “SiteAdding”, “SiteAdded” event. However, if you really need this event you could create a “feature” to accomplish this. Features in SharePoint have a “FeatureActivated” event, where you could perform an action on creation of a site.

Building Event Handlers for SharePoint

Steps:

Use the following steps if you want to create your solution from scratch otherwise download the starter kit and continue from Step 7.

1)   Open Visual Studio 2005.

2)   Create a new class library project.

3)   Reference the Microsoft.SharePoint assembly.

4)   Rename the default class to the name you want to give your event handler class. E.g. ItemHandler

5)   Add your “using” statement: “using Microsoft.SharePoint;”

6)   Inherit from the following SharePoint base classes depending on what type of event handler your want to create:

a.   Site                      : SPWebEventReceiver

b.   List Columns    : SPListEventReceiver

c.   List Items           : SPItemEventReceiver

d.   Email                   : SPEmailEventReciever

7)   In your class, type “override” and let IntelliSense provide you with a list of events to override.

8)   Implement the logic in the overridden method(s).

9)   Compile, fix errors, recompile until build succeeds.

10)       Strongly name your assembly ( sign your assembly )

a.   Right Click your Class Library Project

b.   Select Signing Tab

c.   Choose a strong name key file:

                                         i.    <browse> = select a previously created key file.

                                        ii.    <new> = create a new key file.

Overview

So you have deployed the assembly to the farm, now what? How do I register an event in your assembly for a Site, List, or Content Type?

I will describe three ways to deploy your assembly’s events.

1) Manage EventReceivers via Code

2) Deploy event handlers using the Feature framework of MOSS 2007

3) A cool custom Site Settings Application I built to manage (view, add, edit and delete) event handlers.

Managing EventReceivers via Code

The site (SPWeb) object, the list (SPList) object and the Content Type (SPContentType) object expose a collection called EventReceivers based on the SPEventReceiverDefinitionCollection class.

This collection maintains a set of SPEventReceiverDefinition objects (events) attached to a site, list or content type.

Adding Event Handlers (SPEventReceiverDefinition)

This class provides an “Add” method to attach a new SPEventReceiverDefinition (We created and deployed these to MOSS in Post 1 and 2.) The Add method asks for three bits of information:

SPEventReceiverType: This tells SharePoint the type of event receiver we are adding to the EventReceiver collection.

Assembly name: The name of the assembly. E.g. “Litwarehandlers, Version 1.0.0.0, Culture=neutral, PublicKeyToken=a6ab42c509981682”

Class name: The name of the class. E.g. “Litwarehandlers.SiteHandlerClass”

Once attached, the site, list or content type will now start picking up these events and executing your assemblies code.

Modifying Sequence Numbers

Another important property you may want to set for each event you attach is the Sequence Number. The sequence number determines the order your event assemblies’ fire. This is especially important when you have created multiple assemblies that are all attached to the same Site, List or Content Type event. 

To modify the Sequence Number, you need to retrieve the SPEventReceiverDefinition object from the EventReceivers collection.

Site: site.EventReceivers

List: list.EventReceivers

Content Type: site.ContentTypes[content type name].EventReceivers

A suggested best practice (and only my opinion), do not use sequence numbers below 10000 as SharePoint uses event handlers extensively to run SharePoint Workflows, etc. These event handlers use Sequence Numbers, starting at 1000.

Deleting Event Handlers (SPEventReceiverDefinitions)

When removing definitions, here is what you have to do:

Site:

Attach to the site (SPWeb)

Lookup the SPEventReceiverDefinition object in the site.EventReceivers collection.

Use the delete method of the SPEventReceiverDefinition object to remove it from the collection.

Call the site.Update() method.

List:

Attach to the site (SPWeb)

Retrieve the list : (site.Lists[GUID or listname])

Lookup the SPEventReceiverDefinition object in the list.EventReceivers collection.

Use the delete method of the SPEventReceiverDefinition object to remove it from the collection.

Call the list.Update() method.

Content Types:

Attach to the site (SPWeb)

Retrieve the SPContentType (site.ContentTypes[SPContentTypeId])

Retrieve the SPEventReceiverDefinition object : (SPContentType.EventReceivers[GUID])

Use the delete method of the SPEventReceiverDefinition object to remove it from the collection.

Call the SPContentType.Update() method.

Managing assemblies using Features

It is possible to create a feature that deploys your event handler to the assembly.

MSDN has an example on how to achieve this: http://msdn2.microsoft.com/en-us/library/ms453149.aspx

See screenshot of the xml you need to write to deploy an event via the features framework:

Limitations:

·         It is difficult to see what event handlers are installed and the sequence they are firing for a site, list or content type. To modify, requires rebuilding the feature with the correct settings.

·         Using a feature, “hardcodes” the event handler to an individual list or Content Type. Each time you want to use the SAME event handler, you are forced to write another feature to register it.