Thursday, January 05, 2006

Extreme Sharepoint Design: Modifying User-Defined Web Part Pages

User-defined web part pages allow web designers and portal members to create isolated pages with the same basic functionality as a standard area or site page. Because they are stored in document libraries instead of the area or site collection hierarchy, they can be created, deleted, and modified without affecting portal navigation, taxonomy or search results. They serve as an effective, low-impact method for enabling user creativity.

Customizing user-defined web part pages is not quite as tricky as overhauling a complete site definition but they do present the designer with a few unique challenges. For one thing, there are several types in every definition and each one is slightly different. For another, they have a few built-in limitations that will cause problems if you don't know what to watch out for. Coordinating the look and feel of these pages with the overall portal design will improve consistency and encourage users to create their own pages without impacting the portal architecture.

User-defined web part pages are stored in the DOCTEMP\SMARTPGS directory of each site definition, named in ascending numerical order (SPSTD1.ASPX, SPSTD2.ASPX, and so on). Each numbered file is directly related to an option in the Web Part Page Creation Wizard (SPCF.ASPX) section titled "Layout". The 'Choose a Layout Template' select box contains eight options for page layout, from a simple, single-column design to a complete, multi-zone web part page. Should you choose to edit Web Part Page Creation wizard page to add or remove items to/from this list, you will notice that the options are out of order in the select box code (line 251 of SPCF.ASPX):

<SELECT id="onetidWebPartPageTemplate" name="WebPartPageTemplate" size="8" onchange="DoTemplateOptionChange()">
<OPTION value="1">Full Page, Vertical</OPTION>
<OPTION value="3">Header, Left Column, Body</OPTION>
<OPTION value="4">Header, Right Column, Body</OPTION>
<OPTION value="2" selected="true">Header, Footer, 3 Columns</OPTION>
<OPTION value="5">Header, Footer, 2 Columns, 4 Rows</OPTION>
<OPTION value="6">Header, Footer, 4 Columns, Top Row</OPTION>
<OPTION value="7">Left Column, Header, Footer, Top Row, 3 Columns</OPTION>
<OPTION value="8">Right Column, Header, Footer, Top Row, 3 Columns</OPTION>

The options relate to each page in the site definition as follows:

Option 1 -> spstd1.aspx -> Full Page, Vertical
Option 2 -> spstd3.aspx -> Header, Left Column, Body
Option 3 -> spstd4.aspx -> Header, Right Column, Body
Option 4 -> spstd2.aspx -> Header, Footer, 3 Columns
Option 5 -> spstd5.aspx -> Header, Footer, 2 Columns, 4 Rows
Option 6 -> spstd6.aspx -> Header, Footer, 4 Columns, Top Row
Option 7 -> spstd7.aspx -> Left Column, Header, Footer, Top Row, 3 Columns
Option 8 -> spstd8.aspx -> Right Column, Header, Footer, Top Row, 3 Columns

In addition, each option has an animated GIF of the same name associated with it that provides a thumbnail view of the page design. These images are located in the 60\TEMPLATES\LAYOUTS\1033 directory. Display of the thumbnails is controlled by the following script at the top of SPCF.ASPX:

function DoTemplateOptionChange()
var index = document.frmWebPage.WebPartPageTemplate.selectedIndex;
document.frmWebPage.PreviewImage.src = strImagePath + "spstd" + document.frmWebPage.WebPartPageTemplate.options[index].value + ".gif";
document.frmWebPage.PreviewImage.alt = document.frmWebPage.WebPartPageTemplate.options[index].text;

These images may be replaced with a custom animated gif that reflects the new page design or directed to another file name by editing the DoTemplateOptionChange() function.

Modifying the pages themselves is done in much the same manner as any other definition file - start with the default code and add or remove tags and HTML code as necessary - but there are a few issues to bear in mind when working with web part pages:

1. Web part zones in the page body (excluding the TitleBar zone; see below) are contained within a specific set of table cells which are referenced by a script that determines whether or not to display the cell based on it's contents (or, more accurately, the lack thereof). To recreate this functionality, be sure to place your web part zones inside the following cell:

<td id="_invisibleIfEmpty" name="_invisibleIfEmpty" valign="top" width="100%">

It is also necessary to include the following script somewhere on the page (the default location is just after the closing row tag in the parent table for the web part zones):

<script language="javascript">if(typeof(MSOLayout_MakeInvisibleIfEmpty) == "function") {MSOLayout_MakeInvisibleIfEmpty();}</script>

2. By default, the TitleBarWebPart is added to each web part page when it is rendered. This web part displays the page title and 'Modify Shared Page' menu link. This web part is NOT specified in any SCHEMA.XML file and cannot be disabled. Furthermore, it's target is the TitleBar zone and this zone must exist on the page or an error will occur after page creation. The zone can be located anywhere on the page (it does not have to exist in the "_invisibleIfEmpty" table cell). To hide it from view, it can be placed within a container DIV whose 'display' style is set to 'none', but doing so will require the addition of the Settings Link control (<WebPartPages:SettingsLink runat="server" />) in the title area.

3. If the portal design incorporates custom menus, those menus changes will cascade down to the web part pages. Incorporate any definition-specific menu options into the corresponding web part pages and remove any elements with localized dependencies (such as <SharePoint:RelatedTasks>, which depends upon the <Toolbar Type="RelatedTasks"> section in SCHEMA.XML) or context-sensitive options.

4. Web part pages in each definition are similar but not exactly the same. Take note of the different controls used in portal definition pages and STS definition pages; for example, pages in SPSPERS use <SPWC:PersonalSpaceNavigation> while pages in STS use <Sharepoint:Navigation>. Similarly, the HTML layout code may change from page to page, with DIV's, Tables, and other elements in unusual locations. As with any site definition modifications, when copying and pasting code be aware of the differing page registrations for each definition type and any tags which that definition relies upon for proper page rendering (like <SPSWC:PersonalSpaceNavigation runat="server" /> on personal site pages).

To implement web part page modifications, simply copy the modified files to the target server(s). Since there are no XML files associated with this page type, changes will be seen immediately without having to reset IIS.

UPDATE: Dennis has a great post on adding your own custom templates to the 'Create' page in SPS/WSS.