Monday, June 9, 2008

Working with Page Templates

When the CustomSitePages feature is activated, it contains declarative logic in elements.xml to provision site page instances from its page templates. The code in the FeatureActivated event extends the navigation components of a WSS site by adding two new drop-down menus to the top link bar with menu items to navigate to the newly provisioned site page instance.

Let’s start with a simple definition for a page template. Examine the following definition for the page template named Page01.aspx.
%@ Page MasterPageFile="~masterurl/default.master"
meta:progid="SharePoint.WebPartPage.Document" %>
asp:Content runat="server" ContentPlaceHolderID="PlaceHolderMain">
h3>Hello World
A simple page template used to create site pages
meta:progid attribute is included to make that page compatible with the SharePoint Designer, and is also available in the SPFile object’s ProgID property. Once site page instances have been provisioned by using this page template, users can open these pages with the SharePoint Designer and customize their content.
Keep in mind that a page template, such as Page01.aspx, serves no purpose until you begin using it to provision site page instances. This can be done by creating a feature that contains a special type of element known as a Module.
When you create a Module, you add one or more inner File elements. The key point is that each File element is used to provision an instance of a file from a file template. Remember that the file template exists on the file system of the front-end Web server.
elements xmlns="">
file url="Page01.aspx" type="Ghostable">
Note that the File element within this example is created with a Url attribute that points to the source file for the page template. When you activate a feature that contains this Module element, WSS provisions a site page instance within the target site at the following relative path.SitePages/Page01.aspx
Note that the File element in the previous example contains a Type attribute with a value of Ghostable. When a site page instance, such as Page01.aspx, is provisioned, it initially exists in an uncustomized state and benefits from the principles of page ghosting. This means that you can activate this feature in a thousand different sites within a Web application and that all sites use a single compiled version of the page. Page ghosting also makes it possible to make changes to the page template on the file system of the front-end Web server and have those changes affect all of the sites that have pages provisioned from this page template.
Only two possible settings exist for the Type attribute: Ghostable and GhostableInLibrary.These two settings are used to differentiate between files that are provisioned inside a document library and those that are not. In this case, the site page instance has a Type of Ghostable because it is not being provisioned inside a document library. Later in the chapter, you will encounter an example of a File element whose Type attribute value will be defined as GhostableInLibrary.
Safe Mode Processing
It’s important to understand that all customized site pages are parsed and processed in a
special mode known as safe mode. The primary motivation for safe mode involves the
fact that standard users can modify the contents of site pages. In other words, a user (such
as a site owner) possessing no administrator privileges within the farm can make any
modifications to a page within a site. Consider a scenario in a large farm in which a site
administrator attempts to mount an attack on the Web server by writing C# code within a
customized site page inside an in-line script block. Safe mode prevents this type of attack by
disallowing in-line script in any customized source.
Examine the code in the page template named Page02.aspx. It contains a simple in-line script
to write a message back to the browser.
%@ Page Language="C#" MasterPageFile="~masterurl/default.master"
meta:progid="SharePoint.WebPartPage.Document" %>
asp:Content ID="main" runat="server"
h3>Page 2

% Response.Write("Hello world from server-side script!"); %>
Note that this page and the in-line script run just fine as long as the page remains uncustomized in a ghosted state. Remember that WSS compiles a ghosted page into an assembly DLL for processing. However, as soon as a user modifies any aspect of this page with the SharePoint Designer and moves the site page into an unghosted state, WSS then begins to use safe mode to process it. Because the page contains in-line script, WSS refuses to process it in safe mode and generates the error message. For this reason, you should avoid adding in-line script to page templates.
For example, assume that you want to allow in-line scripts for site pages inside the SitePages folder in a site at the path of /sites/Sales. You can accomplish this by adding the following PageParserPath element
within the SharePoint section of the web.config file.
SafeMode ... >
AllowServerSideScript="true" />
If you examine the PageParserPath element, you see that the VirtualPath attribute has a Web application relative path followed by an asterisk, which includes every site page in that particular folder. Also note that the CompilationMode attribute has a value of Always and the AllowServerSideScript attribute has a value of true. This instructs the safe mode parser to compile all site pages into assembly DLLs and allow in-line script.
At the very least, you should prefer a Compilation-Mode setting of Auto instead of Always so that only pages that actually contain script are compiled into assembly DLLs, whereas those pages that do not contain script continue to be parsed and processed in no-compile mode.
Safe Controls
Tells what controls a user might place on a customized page. Safe mode allows the farm administrator to determine which controls can be used in pages that are processed in safe mode.
Customized pages can only contain server-side controls that are explicitly registered as safe controls. Registering a control as a safe control is accomplished by adding a SafeControl entry into the web.config file for the hosting Web application.
Assembly="Microsoft.SharePoint, …"
AllowRemoteDesigner="True" />

No comments: