April 17, 2015 // By Matt Youngstrom
A very commonly misunderstood concept in SharePoint is the notion of page customization and uncustomization. While this topic has been hashed and re-hashed, it seems that every time I revisit it, I gain new insight. This post will try to sort out some of the spaghetti to bring more clarity and also try to point out a different perspective on a familiar concept.
Page Templates, Page Instances and Ghosts!
In SharePoint, design elements like pages and master pages are based on files associated with a site definition. The site definition is what describes a site as a team site, a publishing site or some custom kind of site.
These files live on the file system in folders to which IIS is aware, and SharePoint uses these files as templates to create page instances. These templates do not include data – just the design and structure of the page. The data is merged when page instances are created.
For example, when you navigate to http://<domain>/_layouts/viewlsts.aspx, SharePoint creates a page instance based on the viewlsts.aspx page template in the c:\program files\common files\microsoft shared\web server extensions\12\TEMPLATE\LAYOUTS directory. If you navigate to http://<domain>/<subsite>/_layouts/viewlsts.aspx, a page instance is created based on the same viewlsts.aspx page template. The page looks and feels the same, but displays different data based on the site that is currently open.
These page instances are "ghosts" of the actual templates, because the instances are never saved to the file system; they only exist as eerie spectres in memory.
A common need is to customize these page templates so that the corresponding "ghosts" or page instances are customized as well.
There are several ways to accomplish this:
- Change the underlying templates. Doing this, however, will affect every other page instance generated on the farm.
- Create a new template for the new page and place it on the file system. This template is available to every site and may not be generic enough to be useful in every site.
- ”Unghost" the page by saving the page instance. In this case, the page instance is no longer a "ghost," because it is now fully embodied through the action of saving it. In the case of SharePoint, the page instance is saved to the content database.
The first two options refer to what is also called "application pages" (which is a poor name in my opinion, because they are actually page templates). These page templates perform the best because SharePoint does not have to retrieve the fully embodied, unghosted page from the content database. They also require more work to create and deploy.
In regard to the third option, the "unghosted" page must be retrieved from the database. The extra steps necessary to do this increase the response time and therefore decrease performance. Unghosted pages, however, are much easier to create and deploy. They only require a tool like SharePoint designer to create. They can also be created programmatically through the SharePoint API, but they do not require an administrator to deploy.
So how do page instances become "customized" or "unghosted?" When you use SharePoint designer to modify the page instance in a way that differs from the original page template and then attempt to save it, SharePoint will ask if you are "sure you want to customize" the page. If you say "yes," SharePoint will disassociate the page instance from its underlying template and save a copy of it in the content database.
So to summarize thus far for pages:
- Ghosted Pages ("uncustomized") are page instances based on page templates
- Unghosted Pages ("customized") are fully embodied pages that were once based on a page template from which they are now disassociated.
Now, we need to introduce another concept: Site Pages. We've been talking about them up to this point without defining them as such, but Site Pages are a more accurate term for pages. They are what a user sees when navigating the site. As we've seen, they can be ghosted or unghosted.
These site pages are constructed using a design element known as a Master Page. Like Site Page templates, Master Pages can exist on the file system or they can be customized and saved in the content database. While a page is being constructed, SharePoint will fetch the Master Page from the file system or the content database.
And just in case you weren't confused enough…With regard to design elements, the terms "ghosted" and "unghosted" have a subtle difference in meaning from Site Pages. Saying a design element is "ghosted" or "unghosted" is not related to instances of underlying templates, but rather the location in which SharePoint retrieves the design element during .NET page construction.
Interesting results of this include:
- An unghosted Site Page may be constructed using a ghosted Master Page
- A ghosted Site Page instance may be constructed using an unghosted Master Page
- An unghosted site page may be constructed using an unghosted Master Page
Files like CSS and images – which are not used during .NET page construction but are loaded by the browser during client page rendering – follow a similar definition as Master Pages for the terms "ghosted" and "unghosted." They are either retrieved from the file system or the content database, depending on their status. Have a look at this post from Marc Chamois. It gives a very complete picture of how to ghost and unghost these design elements.
Special Case: SharePoint Server & GhostableInLibrary
In SharePoint Server we can use a type of site called a "publishing" site. This is a site based on a site definition that includes content publishing infrastructure and is not available in SharePoint Foundation. In addition to publishing content, ghosted design elements in a publishing site are exposed through the Master Page gallery and can be published just like content.
A new Master Page deployed to the file system on the server via a SharePoint Feature will not appear in the Master Page gallery if the element "type" attribute is left blank or it is set to "Ghostable." To make it appear, the feature associated with the Master Page has to be marked as "GhostableInLibrary." This means that an item associated with the file will be created in the Master Page gallery. The file itself will not be stored in the content database, however. SharePoint will continue to use a cached copy of the file from the file system until it has been customized.
Again, the best way to tell of a design element's status is to try the technique explained in MarcChamois' article.