3.3. Creating Site DefinitionsIt is interesting to note that if you don't change a built-in page, SharePoint doesn't include it in the custom template. In that case, the built-in page comes from the SharePoint site definition. animal 3-5. Viewing changed pages in a template fileSite definitions are how SharePoint provides predefined templates. These definitions are made up of a number of files that reside on the SharePoint server's file system. You can view the site definitions by browsing the SharePoint server's C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\TEMPLATE folder. SharePoint groups the site definitions into two subfolders : . \1033\STS contains the site definition for the Team, Document Workspace, and Blank site templates; . \1033\MPS contains the site definition for the Meeting workspace site templates. Table 3-3 lists the files SharePoint uses to locate, define, and set the content for its site definitions. Table 3-3. SharePoint site-definition files
Figure 3-6 shows an expanded view of the folders and files where the Team Site, Document Workspace, and Blank site templates are defined. animal 3-6. Locating site definition files3.3.1. Customizing Site DefinitionsCreating custom site definitions is much more difficult than creating custom templates, but it provides complete control over all aspects of new sites and can provide better performance than custom templates. Since site definitions are complex and made up of numerous dependent files, it's easiest to create new definitions by copying and modifying an existing one. To create a custom site definition:
For example, I copied the STS folder and renamed it DotSites; then I edited ONet.xml to alter the top-level navigation bar and add a custom help page as shown by the following changes in bold : <?xml version="1.0" encoding="utf-8" ?> <Project Title="Team Web Site" ListDir="Lists" xmlns:ows="Microsoft SharePoint"> <NavBars> <NavBar Name="SharePoint Top Navbar" Separator="&nbsp;&nbsp;&nbsp;" Body="<a ID='onettopnavbar#LABEL_ID#' href='#URL#' accesskey='J'>#LABEL#</a>" ID="1002"> <NavBarLink Name=" Our Collection " Url="_layouts/[%=System.Threading.Thread.CurrentThread.CurrentUICulture.LCID%]/ viewlsts.aspx"> </NavBarLink> <!-- Deleted Create and Site Settings navigation links --> <NavBarLink Name="Help" Url= 'dothelp.aspx' > </NavBarLink> </NavBar> <NavBar> ... </NavBar> </NavBars> <ListTemplates> ... </ListTemplates> <DocumentTemplates> ... </DocumentTemplates> <BaseTypes> ... </BaseTypes> <Configurations> <Configuration ID="0" Name="Default"> <Lists> <List Title=" Our Collection " Url="Shared Documents" QuickLaunchUrl="Shared Documents/Forms/AllItems.aspx" Type="101" /> ... </Lists> <Modules> <Module Name="Default"/> <Module Name="WebPartPopulation"/> <Module Name="DotHelp" /> </Modules> </Configuration> </Configurations> <Modules> ... <Module Name="DotHelp" Url="" Path=""> <File Url="DotHelp.aspx" Type="Ghostable" /> </Module> </Modules> </Project> The ellipses in the example summarize some of the other elements ONet.xml containsI won't spell those out just yet, but they're covered in the SharePoint SDK if you're curious . Figure 3-7 illustrates the changes to the NavBarLink , List , and Module elements highlighted above. Next, I created a new file based on WebTemp.xml and renamed WebTempDotSites.xml to tell SharePoint how to load the new site definition as shown here: <?xml version="1.0" encoding="utf-8" ?> <Templates xmlns:ows="Microsoft SharePoint"> <Template Name="DotSites" ID="3"> <Configuration ID="0" Title="Dot Site" Hidden="FALSE" ImageUrl="/_layouts/images/stsprev.png" Description="Template for Designs of the Times."> </Configuration> </Template> </Templates> The Template element's Name attribute matches the folder name containing the site definition ( DotSite ). The Configuration element determines the title, description, and image that appear when creating a new site based on a particular configuration from the site definition. Each Configuration corresponds to a single template in SharePoint. A site definition can provide multiple templatesfor example, the STS site definition provides configurations for three templates: Team Site, Document Workspace, and Blank Site. Finally, I ran iisreset.exe on the SharePoint server. When SharePoint restarts, it automatically loads site definitions described in all the files named WebTemp*.xml . Now, when I create a new site based on the Dot Site template, SharePoint creates a site that looks like Figure 3-7. 3.3.2. Adding and Changing Pages in Site DefinitionsIn the preceding section, I added a help page and changed the Help link on the navigation bar to point to that page by modifying its Url attribute. The change to the NavBarLink element was very simple: <NavBarLink Name="Help" Url= 'dothelp.aspx' > </NavBarLink> animal 3-7. Seeing the effect of ONet.xml changesThe change to include the new page in the site definition was a little more complex. To add a new page to a site definition, add the Module element in two places as shown here: <Configurations> <Configuration ID="0" Name="Default"> <Modules> <Module Name="DotHelp" /> </Modules> </Configuration> </Configurations> <Modules> ... <Module Name="DotHelp" Url="" Path=""> <File Url="DotHelp.aspx" Type="Ghostable" /> </Module> </Modules> The Configuration element defines different template variations that a single site definition provides. The Modules element within Configuration tells SharePoint which modules to include in each configuration. The second Modules element lists the location where SharePoint can find the module and whether or not the module is ghosted . Ghosted modules are not copied to the site's content. Instead, they are read from the site definition and cached in server memory. Default.aspx is a good example of a ghosted module. For the preceding example, I created a new file named DotHelp.aspx in the same server-side folder as default.aspx : >dir /w Directory of C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions \TEMPLATE33\DotSites [.] [..] default.aspx [DOCTEMP] DotHelp.aspx [DWS] [LISTS] [XML] Since ghosted files aren't copied into site content, you can change those files in the site definition, and sites based on that definition automatically change. Figure 3-8 shows how this works. animal 3-8. Changing ghosted files automatically changes sites based on the definition
You can easily try this on any of your existing sites. Go to the site definition you based your site on and add some text to the site's Default.aspx page. For example, add this text to the end of the page: <h1>This is a change</h1> </body> </html> Next, display the site's home pageyou'll see the new heading text at the bottom of the page. Notice that you didn't need to restart SharePoint to see the change to the file.
3.3.3. Debugging Site DefinitionsYou must restart SharePoint for changes to the site definition's XML files to take effect. After restarting SharePoint, you might get an error the first time you request a page from the SharePoint site in your browser. Repeat the request and it should work. Any errors or inconsistencies in ONet.xml prevent the site definition from working. Even a simple typo, such as incorrectly capitalizing the NavBar element, will display a generic error page if you try to create a new site based on that definition. The error page doesn't give you a clue where the error occurred, so it is best to:
If you don't have an XML editor you can install the Internet Explorer Tools for Validating XML ( iexmltls.exe ) from http://www.microsoft.com/downloads. Then simply open the XML file in Internet Explorer to check the form. |