Master pages/page layouts deployed as Feature not updating

Since Deploying master pages and page layouts as a Feature has been the most heavily commented article on this blog, and several of the posters seem to have run into the same problem, I wanted to write a quick post with some more information from my experiences on this.

So this is something of a non-standard post, feel free to tune out if it doesn't affect you ;-)

Anyway, I decided to do some more testing to see if either I'd got something wrong or if perhaps I was doing something differently to the people having problems. My test was basically to knock up a publishing site with a master page and page layout (associated with a custom content type as it often would be), then go through the update process. This is what I found:

• making updates to the files (outside of the 12 folder) and then XCOPYing these to overwrite the files in the 12\TEMPLATE\features\MyFeature\ directory successfully updated the site. No need to deactivate/activate the Feature.
• using a Solution package to deploy the files (when using Features this is generally what I do since I'm in a farm environment) - again this updated the site correctly when I upgrade the Solution (stsadm -o upgradesolution). This is to be expected since underneath the exact same thing is happening as in the previous test. (However, I also noticed occasionally the directory would complete disappear even after the solution upgrade had completed, or was there but still locked by another process, meaning the files could not be accessed even in Windows Explorer - this is slightly irritating but running the Solution upgrade again always succeeded.)
• after causing the file to be customized (e.g. modifying or even just checking out with SPD), any subsequent updates to the files via the Feature/Solution did not appear on the site (though further updates in SPD are fine).

In short, this is all what I expected. Assuming the file has not been customized, anything which updates the copy on the filesystem will cause an update to the site. If it has been customized, updates on the filesystem will not (since the file has now been added to the content database, and the filesystem version is no longer used). If you've not come across this before, Considerations when using Features to deploy SharePoint files - ghosting/unghosting may help.

So, I'm guessing that if your master pages etc. are not updating when you overwrite the Feature files, it's because the files have become customized somehow. Unfortunately it's not so easy to tell for publishing files - for other files, SharePoint Designer provides a handy blue dot next to the file in it's Explorer view if the file is customized, but alas this doesn't happen for master pages/page layouts. The blue dot can be seen next to the AllItems.aspx file below (click to enlarge):

Unfortunately this also means reverting to the file on the filesystem is not straightforward either (we can't right-click the file in SPD and select 'Reset to site definition' as we can with other SharePoint files). So this can be a pain if you do want to keep your page layouts referenced from the filesystem (e.g. because performance is critical), but you've ended up in this state. It is possible to revert the files using the API though. I've not needed to do this myself, but the property to check is SPFile.CustomizedPageStatus and if this returns SPCustomizedPageStatus.Customized, then the SPFile.RevertContentStream() method can be used - this should cause SharePoint to henceforth use the version on the filesystem (though note you may lose some updates which had been made after the file was unghosted (customized) - you will need to re-apply these to the filesystem file after the reversion. And remember, don't use SPD for this or you'll be back where you started!)

So far, so (reasonably) straightforward.

However, one poster (deelpunt) had an interesting question about updating page layouts with web parts. As far as I can see, updating all page instances to have web parts in web part zones by updating the layouts will not be possible. This is because if web part zones are used, the web part is associated with the page instance rather than the page layout. Indeed, this can be the power of the architecture. It is possible to either:

• have default web parts added to a zone when a page instance is created from a page layout. This can be done by deploying the page layout using a Feature, and using the AllUsersWebPart tag. This would not affect pages already created however.
• add web parts to all the pages by adding them directly to the page markup in SPD, rather than in a zone. Of course, this then means the settings for the web part can only be modified by the page designer in SPD, rather than site users.
• use the API to iterate through all pages in the site to add/modify webparts using SPFile.GetLimitedWebPartManager(). Needless to say, this is the kind of operation which requires a lot of care and planning in production!

As I've mentioned before, because of these issues the web part zone architecture is often not the best choice for scenarios such as WCM site development, since here we want our changes to apply across all pages which use the layout.

Hopefully this has been of some use. As always, leave a comment if you've had different experiences to those detailed here, I'd definitely be interested to hear.

[I also wanted to say sincere apologies to the commenters on the original post (and any others I've been slow in replying to) that it took a couple of weeks for me to come back. Something to do with my project going live and moving house at the same time, hopefully normal service now resumed ;-) ]

Blending publishing/collaboration functionality in SharePoint

Most often when creating SharePoint solutions, the requirements often map fairly well to one of the out-of-the-box site definitions which can be used to create new sites. If we're creating heavily-branded internet/intranet sites (WCM sites), we'll probably start with the 'publishing site' template. If we are deploying SharePoint in a document management/collaboration scenario, we'll probably start with the 'team site' template, and so on. Where it gets interesting it when the project requirements effectively have a mix of this functionality. Characteristics of such a site might include:

• site has completely bespoke look and feel/navigation
• users will work with files stored in document libraries
• site templates or definitions are used to create several sites with the same content/functionality
• custom workflow is used to support a business process (other than standard content publishing), perhaps with InfoPath forms

Such requirements present a few challenges, and a current project of mine fits into this category. At a high level, one consideration is that site users will also use 'system' pages provided by SharePoint in many scenarios (e.g. working with document libraries/lists, workflow etc.) and this doesn't happen in most WCM sites. This can lead to situations where there is a disparity between the look and feel of the 'published view' of the website and the 'system' areas. I don't intend to provide answers to all the issues here, but I do want to discuss a few as some food for thought. I'll probably revisit this post at the end of the project and provide a better insight into the issues and solutions, but for now let's cover some high-level decisions:

 

Approach for master page development

Options for starting development here include:

• Using a 'minimal master page' from MSDN or Heather Solomon
• Modifying a copy of default.master (good starting point for customized team sites)
• Modifying a copy of blueband.master (good starting point for WCM sites)

Partly this decision depends on where you are heading. Since the aim in my project is for formatting to be controlled by CSS rather than layout tables, starting with a minimal master page makes more sense (the shipped page layouts use tables). This is an interesting area since there's a lot of rework to be done to eliminate tables in a mixed publishing/collab site (and in fact it often won't be possible to eliminate them completely), and for me the benefit is debatable. Certainly all the 'system' pages which site users will be exposed to use layout tables, so I'm not sure how much is gained by only having some pages using CSS for layout.

Other things to consider here are the usual questions of how to factor responsibility of content items between the master page and page layouts, how to define content types etc., but these are standard decisions in WCM site development so I won't cover them here.

 

Use of Content Editor web parts vs publishing RichHtmlField controls

Most folks in WCM development know there is an overlap in functionality provided by the Content Editor web part and the RichHtmlField control in the Microsoft.SharePoint.Publishing.WebControls namespace, i.e. they can both be used to enter page content such as text/images. However it's important to consider the differences - the RichHtmlField control stores it's content in a column of the list item for the page, whereas the CEWP is a web part and thus stores content in the web part storage architecture. This is important, since if deployment to a different environment is in your project plan or ongoing architecture, things will likely be simpler if you use the field control, since this content will then travel with the page properly.

Additionally, there are some URL fix-up issues with using the CEWP across different environments, as documented in the HawaiianAir.com write up.

In summary, I'd recommend considering the CEWP as a means of entering content in non-publishing SharePoint sites only. 

 

Use of collaboration web parts - in layouts or in WebPartZones?

In a similar vein, since we are mixing the collaboration features into our site we are likely to need to use certain web parts which we wouldn't in a straight WCM site. In our situation the ListViewWebPart is fairly key to some areas, and is used as a means of allowing users to work with different lists from one page. The first decision here is whether the page layouts should include web parts directly (by adding them in SharePoint Designer), or just web part zones to which the individual parts would be added later through the browser. In most WCM scenarios I prefer to add web parts directly to page layouts since they will not be customized/personalized by end users (the main usage scenario for web part zones), and when web part zones are used, again the web part config is not stored in the page which can make deployment more complex. Using the other approach of adding directly from SPD, config is stored in the actual HTML markup of the page and so travels with the page layout itself.

However! The ListViewWebPart has some quirks which means it isn't always possible to use directly from the page layout. Specifically, it is only possible to configure the part to consume a list from the current web, and in the case of a publishing page layout, this means the root web since this is where the master page gallery is stored. Since our lists are stored in a child web, this is problematic - the other solution of using a DataView also had issues. Additionally, the ListViewWebPart configuration stores values specific to it's location, meaning the config XML is not very portable (i.e. export web part definition, modify, use). I'd like to think it would be possible with time to work out exactly which IDs do need to be changed, but alas we don't have time on this project.

As a result, using the ListViewWebPart in a web part zone is actually the best solution in these circumstances as far as I can see. We'll have an extra few steps at deployment, but this will take less time than the alternatives it appears.

 

Look and feel of system pages

As mentioned earlier, for a mixed WCM/collaboration site there can be a disparity of the look and feel of the main pages of the site and the 'system' pages users will see, i.e. pages from the '_layouts' directory. Note this happens even if both the site and system master page is set to point at your custom master page, since these pages are set to use 'application.master' (also on the filesystem in '_layouts') which neither of these properties affect. Sure it would be possible to simply replace 'application.master' with your own version, but that's not an elegant solution and would probably be unsupported. Unfortunately it seems that the architecture doesn't provide an easy way to change the master page used by '_layouts' pages - you have to go a level deeper to explore ways of doing this. Many .Net 2.0 developers will know it's possible to switch a master page dynamically in .Net, and to be fair this is what SharePoint does with the maser pages stored in the master page gallery anyway. I'm not aware of a truly elegant solution to this problem, but this discussion on Serge van den Oever's blog presents a viable approach using this technique. 

 

So those are some of the issues to consider. There are certainly others, including navigation, CSS customization of standard styles (to ensure collaboration web parts integrate well with your look and feel), and possibly the choice of authentication mechanism. I'll cover these and any others which arise in an upcoming post.

Deploying master pages and page layouts as a feature

This is the fourth article in my series of how to create common SharePoint site artifacts as features. Last time we looked at deploying content types as a feature.

Now that we have content types and all the supporting artifacts deployed, we can focus on deploying the things that make a real difference to how our site works - master pages and page layouts. I'll also cover web part deployment in a forthcoming post.

The basic premise is:-

• develop master pages/layouts using SharePoint Designer (SPD)
• save each file to the filesystem (as opposed to the Master Page Gallery) ready to be added to a feature. Unfortunately, SPD will actually screw up hyperlinks and some control references when you do this - in particular references to user controls using the '~/_controltemplates/' path. The best solution is to copy the contents of the final file into notepad, and save the file to the filesystem with the same name.
• create the feature.xml and element manifest file for the feature. An example of an elements manifest file to deploy 2 master pages and 3 page layouts is shown at the end of this post.
  

Let's talk through the values used in the example below. At the module level (collection of files to deploy to a particular location in SharePoint), we specify the URL and whether the files should only be deployed to the root web or to all webs in the site collection. At the file level, attributes for the master pages are fairly simple:-

• 'IgnoreIfAlreadyExists' - should be true if we want to overwrite an existing file of this name, false if not.
  
• 'Type' - should be 'GhostableInLibrary' for files which exist in a document library such as the Pages, Style Library or Master Page Gallery libraries which exist in a SharePoint publishing site.
  

For the page layouts, things are slightly more complex. Here, we need to specify the following:-

• 'ContentType' - specifies whether the file is a page layout or master page. Use the value '$Resources:cmscore,contenttype_pagelayout_name;' to specify SharePoint's internal string which represents the page layout option.
  
• 'PublishingPreviewImage' - path to URL accessible image file to be displayed when this layout is selected in the listbox when creating a page.
  
• 'PublishingAssociatedContentType' - this is where we specify which content type the layout should be associated with. This means the layout will automatically have this binding and will be ready for use. Note that if this value is omitted, by default your layout will be associated with the basic 'Page' content type from the publishing feature. This means any custom columns you have added will not be available. The value for this property should be in form ';#<Content type name>;#<Content type ID;#>. So a real example would be ';#Welcome Page;#0x010100C568DB52D9D0A14D9B2FDCC96666E9F2007948130EC3DB064584E219954237AF390064DEA0F50FC8C147B0B6EA0636C4A7D4;#'.
  

Another interesting facet of deploying files to SharePoint in this way, is that it's not possible (AFAIK) to update a file deployed from feature 'A' by a separate feature 'B'. This makes sense but gets in the way if you want to update a common file like itemStyle.xsl (used by the Content Query web part) using a feature. This won't work since the file was originally provisioned by the PublishingResources feature, not your custom feature.

I've also seen problems updating page layouts which were associated with content types created through the UI rather than by a feature.

So now that we have our lists, site columns, content types and master pages/page layouts deployed, we can create pages using the layouts and add content to the site.

Next time I'll talk about options around deploying web parts.

Here's the XML sample mentioned earlier:-

<?xml version="1.0" encoding="utf-8"?>
<elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <module name="MasterPagesModule" url="_catalogs/masterpage" rootwebonly="True" path="">
    <file url="cScape.master" ignoreifalreadyexists="TRUE" type="GhostableInLibrary"></file>
    <file url="accessible.master" ignoreifalreadyexists="TRUE" type="GhostableInLibrary"></file>
  </module>
<module name="PageLayoutsModule" url="_catalogs/masterpage" rootwebonly="True" path="">
    <file url="AdvancedSearchLayout.aspx" ignoreifalreadyexists="TRUE" type="GhostableInLibrary">
      <property name="ContentType" value="$Resources:cmscore,contenttype_pagelayout_name;"></property>
      <property name="PublishingPreviewImage" value="~SiteCollection/_catalogs/masterpage/$Resources:core,Culture;/Preview Images/ArticleLinks.png, ~SiteCollection/_catalogs/masterpage/$Resources:core,Culture;/Preview Images/ArticleLinks.png"></property>
      <property name="PublishingAssociatedContentType" value=";#Welcome Page;#0x010100C568DB52D9D0A14D9B2FDCC96666E9F2007948130EC3DB064584E219954237AF390064DEA0F50FC8C147B0B6EA0636C4A7D4;#"></property>
      </file>
<file url="HelplineHomeLayout.aspx" ignoreifalreadyexists="TRUE" type="GhostableInLibrary">
      <property name="ContentType" value="$Resources:cmscore,contenttype_pagelayout_name;"></property>
      <property name="PublishingPreviewImage" value="~SiteCollection/_catalogs/masterpage/$Resources:core,Culture;/Preview Images/ArticleLinks.png, ~SiteCollection/_catalogs/masterpage/$Resources:core,Culture;/Preview Images/ArticleLinks.png"></property>
      <property name="PublishingAssociatedContentType" value=";#RNIB Welcome;#0x010100C568DB52D9D0A14D9B2FDCC96666E9F2007948130EC3DB064584E219954237AF390064DEA0F50FC8C147B0B6EA0636C4A7D4007AC2318FCE0E474eADE554A22E4B6135;#"></property>
    </file>
<file url="HomePage.aspx" ignoreifalreadyexists="TRUE" type="GhostableInLibrary">
      <property name="ContentType" value="$Resources:cmscore,contenttype_pagelayout_name;"></property>
      <property name="PublishingPreviewImage" value="~SiteCollection/_catalogs/masterpage/$Resources:core,Culture;/Preview Images/ArticleLinks.png, ~SiteCollection/_catalogs/masterpage/$Resources:core,Culture;/Preview Images/ArticleLinks.png"></property>
      <property name="PublishingAssociatedContentType" value=";#RNIB Welcome;#0x010100C568DB52D9D0A14D9B2FDCC96666E9F2007948130EC3DB064584E219954237AF390064DEA0F50FC8C147B0B6EA0636C4A7D4007AC2318FCE0E474eADE554A22E4B6135;#"></property>
      </file>
</elements>