Becky Bertram's Blog
Perspectives from a SharePoint developer

This blog has moved. You can find the new blog on Savvy Technical Solution's Web site, at You will be redirected to the following page in 10 seconds:

Becky Bertram's Blog > Posts > Creating a Page Layout in SharePoint 2010 using Visual Studio 2010
December 08
Creating a Page Layout in SharePoint 2010 using Visual Studio 2010
Creating a custom Page Layout in SharePoint 2010 is not too different than creating a custom Page Layout in SharePoint 2007. However, the process of creating a SharePoint Solution Package has changed in Visual Studio 2010. This article will walk you through the steps.
First, open Visual Studio and create a new C# project, using the "Empty SharePoint Project" template, listed under the SharePoint 2010 project templates. For this example, we'll name our project "MyCustomPageLayout".
For this example, we'll be deploying our solution as a "Sandboxed solution".
Click "Finish" to wire up your solution to your particular SharePoint site.
As with SharePoint 2007, we'll need to provision our Page Layouts to our SharePoint Site Collection Master Page Gallery by using a "Module" element. To do this, right click on the Project and say you want to add a new item. Select "Module" from the list of SharePoint 2010 items.
We'll name the Module "masterpage". When you create the new module, you'll see something like this:
By default, the module contains a sample text file you, so you can see how the Module deploys a file to SharePoint. However, we don't need it, so we'll delete Sample.txt. Next, we need to wire up our module to point to the URL of the Master Page Gallery, so we'll add a "Url" attribute to the Module node. Our Elements.xml file should now contain this XML:
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="">
  <Module Name="masterpage" Url="_catalogs/masterpage">
Next, we're going to dop our new Page Layout file into the Module. To do thhis, we'll right-click on the "masterpage" module in the Visual Studio explorer and select "Add new item". We're once again presented with the "Add New Item" dialog. If we were to select "Application Page" from the SharePoint 2010 menu, we'd get a code-behind page in addition to our ASPX page, which we don't want. Since all we want to provision is markup (and not code), we're going to use a shortcut. Select the "General" node and select "Text File" from the list of items. However, name the file "MyCustomPageLayout.aspx".
Add your Page Layout markup into your MyCustomPageLayout.aspx page. You can do it how I do it, which is to create a new Page Layout in SharePoint designer, then copying the code to Visual Studio. However, DO NOT FORGET to remove the attributes in the Page Directive at the top of the page that SharePoint Designer adds, that look like this:
meta:webpartpageexpansion="full" meta:progid="SharePoint.WebPartPage.Document"
If you don't forget to remove those items from the Page directive, SharePoint will think your pages have been customized, even though they were deployed via a Feature.
Next, we'll need to update the Module's Elements.xml file to tell SharePoint what to do with the new Page Layout.
The first thing we'll need to do is to update the "Url" property of the File element, by removing the "masterpage/" prefix fromt the Url. (Since we already specified in the Module element that we're deploying the Page Layout to the "masterpages" library, if we left the "masterpages/" part of the Url on the file, SharePoint would try to provision our Page Layout into a library called "masterpages" inside the existing "masterpages" library! We don't want that!) Your new File element should look like this:
<File Path="masterpage\MyCustomPageLayout.aspx" Url="MyCustomPageLayout.aspx" />
Now we need to specify some properties for the Page Layout. These properties are identical to the kind of properties you would specify for a Page Layout in SharePoint 2007:
  • The Title of the file in SharePoint
    In our case, the file itself has a URL of MyCustomPageLayout.aspx, but we can also give the page a Title that will show up when the Page Layout is being selected by the content author, such as "My Custom Page Layout".
  • The Content Type
    All Page Layouts must inherit from the "Page Layout" content type (which we add using a Resource file value.)
  • A Publishing Preview Image
    The Publishing Preview Image is the image that shows up when a user picks that Page Layout from the Page Layout picker while they're creating a new page. In this example, we'll just point to the Article Page's preview image.
  • The Publishing Associated Content Type
    This is the Content Type that the Page Layout is representing, such as an "Article Page", "Welcome Page", etc. The value is a string representing a Lookup value that's a combination of the name of the Content Type and its unique identifier.

Our new File node will look like this:

<File Path="masterpage\MyCustomPageLayout.aspx" Url="MyCustomPageLayout.aspx" Type="GhostableInLibrary">
      <Property Name="Title" Value="My Custom Page Layout" />
      <Property Name="ContentType" Value="$Resources:cmscore,contenttype_pagelayout_name;" />
      <Property Name="PublishingPreviewImage" Value="~SiteCollection/_catalogs/masterpage/$Resources:core,Culture;/Preview Images/CustomPageLayout.png, ~SiteCollection/_catalogs/masterpage/$Resources:core,Culture;/Preview Images/CustomPageLayout.png" />
      <Property Name="PublishingAssociatedContentType" Value=";#$Resources:cmscore,contenttype_articlepage_name;;

Please note, there's no line break inside the PublishingAssociatedContentType value string; I needed to add a line break so you could see the whole value here.

That's it! We've built our Module.

Now, we're going to add a module for the Page Layout preview image. Right click on the project and add an additional Module element. Delete the "Sample.txt" file from it, and add your new preview image. (In our case, we'll call it CustomPageLayout.png".) Modify your module file so it looks like this:

<Module Name="Previews Images" Url="_catalogs/masterpage/$Resources:core,Culture;/Preview Images">
  <File Path="Preview Images\CustomPageLayout.png" Url="CustomPageLayout.png" Type="GhostableInLibrary">
      <Property Name="Title" Value="Custom Page Layout Preview Image" />

You might have noticed that a new Feature got created for you when you created a new Module. Let's rename the Feature itself MyCustomPageLayout in the project tree, like this:
We'll open up our MyCustomPageLayout feature, and give it a helpful name and description. Notice that you can graphically see that your Module is a part of this Feature, and you can even see which Module files will be provisioned when the Feature is activated.
The last thing we need to do is to make sure our Solution Package is getting configured correctly, to include our new Feature.
By default, the "Empty SharePoint Project" will create a DLL for you. If we just went ahead and deployed our Solution Package with the settings as-is, we would be deploying a DLL to the GAC. However, since our solution doesn't have any code in it, it would be a blank DLL. That's a bit messy, so let's avoid that. Click on the Project in your Solution Explorer, and look in the Properties Window. Change the "Include Assembly in Package" property to "False".
Important note: This value is in the Properties Window. I was originally looking for it in the Properties page of the Project (say that three times fast), and I couldn't find it there.
To deploy our new Solution Package to our Sandboxed Site, we'll go to the "Build" menu in Visual Studio, and select "Deploy MyCustomPageLayout".
This will assemble the Solution Package, deploy the Solution Package to the Sandbox, then activate the Sandboxed feature.
If we browse to our Master Page Library, we'll now see our new Page Layout. Note that, unlike SharePoint 2007, our Page Layout will appear checked out by default, if we haven't modified any of the approval or check-out settings of the out of the Master Page Gallery. We'll need to check it in and approve it for it to be available to us.
This article was edited on 3/1/2010 based on reader feedback. The Type="GhostableInLibrary" attribute was added to the File node of the Page Layout, and a section explaining how to add a preview image was added.



What would be cool is if you possibly built out project templates (SPI's) using the VS extensibility stuff for master pages & page layouts in a WCM site!
 on 12/8/2009 10:29 AM

Master Page walk-by?

Hello  This was a great and thorough article. I would like a lot, if you could write a similar article about using master page which I seem to have some trouble putting in a solution. Of course Andrew's suggestion would take care of this, but an article qwould be a bit easier to write, I think... ;)
 on 12/15/2009 9:02 AM


Just wondering if you have any suggestions how to package a new 'PublishingPreviewImage' along with the feature. I can see how it works and how the path to the article page image is resolved but not sure how to get an image included as part of the feature itself. Thanks!
 on 2/8/2010 9:18 AM

Deploying publishing preview images

Excellent article, thank you very much.  In order to publish the preview image you can create include another module within your feature using _catalogs/masterpage/$Resources:core,Culture;/Preview Images as the target url and follow the same procedure as described in the post.
 on 2/25/2010 7:24 AM

Sandbox Solution = false

For some reason this example does not work if I deploy it as a farm solution instead of a sandbox..  any idea why?
 on 3/4/2010 5:22 PM

What about application page with code behind ?

When you are adding an application page in a Module instead of the default Layout folder, it does not deploy page code behind in the GAC, I wish this was possible...
 on 3/11/2010 8:42 AM

App Page in a Module

Ben, it actually is possible to do, but you have to do a couple things: - Make sure the "Include Assembly in Project" property on your Visual Studio Project is set to true. - Sandboxed solutions can't deploy any code to the GAC, by definition. If you want your code to go in the GAC, you need to make your solution a farm solution, not a sandboxed one.
 on 3/11/2010 9:19 AM

as a Farm Solution - possible

First, Thanks for the article! I had no problem deploying as a Farm Solution, Bartek, I suggest you recheck everything and try again.
 on 3/19/2010 7:30 AM

Thank you. Can you help me

First of all thank you for the atricle. Unfortunatly it doesn't work for me. Still runnig release candidate vs2010 and the latest beta Sharepoint 2010  Ik keep having the message 'Error 141 Error occurred in deployment step 'Activate Features': Failed to instantiate file "x.aspx" from module "xModule": The specified list does not exstist  Any clue what I'm doing wrong? 
 on 4/20/2010 11:48 AM


Paul, I've seen this happen in two cases: if you haven't activated the Publishing feature for either the site collection or the web, so the folder you're deploying to isn't there (such as the Style Library); or if you've put the name of a list in incorrectly in the module Url property.
 on 4/20/2010 11:51 AM
1 - 10Next

Add Comment

Items on this list require content approval. Your submission will not appear in public views until approved by someone with proper rights. More information on content approval.

Comment Title *

Body *

Your Name

Your E-mail Address

Your Website

Type the Web address: (Click here to test)  

Type the description: 

Are you spamming my blog? *

This field is here in an attempt to stop spammers from entering comments. Enter a number, any number