Section 3.3. Creating Site Definitions


3.3. Creating Site Definitions

It 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 file

Site 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

File(s)

Use to

Location

DocIcon.xml

Add file types and control how those files are opened from all sites.

.\XML

WebTemp.xml

Add or hide site definitions.

.\1033\XML

Default.aspx

Define scripts and layout of the home page for the site.

.\1033\STS or . \1033\MPS

ONet.xml

Define the navigation areas, list definitions, document templates, default lists, configurations, and modules for the site.

.\1033\STS\XML or .\1033\MPS\XM L

Schema.xml

Describe lists included in the site.

. \1033\STS\LISTS\ listname or .\1033\MPS\LISTS\listname

AllItems.aspx , DispForm.aspx , EditForm.aspx , NewForm.aspx

Define scripts and layout for the various views of a list.

.\1033\STS\LISTS\ listname or .\1033\MPS\LISTS\ listname


1033 is the locale ID for the United States. If you are working with other locales, the folder name matches your locale IDfor example, 2057 for the United Kingdom or 1081 for India.


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 files

3.3.1. Customizing Site Definitions

Creating 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:

  1. Make a backup copy of the entire Template folder so you can restore the original definitions if you break anything.

  2. Copy and rename the STS folder. This copied folder will be the basis for your new site definition.

  3. Modify the site definition in the copied folder. The key file to edit is ONet.xml .

  4. Create a new WebTemp.xml file to reference the new site definition.

  5. Restart SharePoint to load the new site definition.

  6. Create a new site based on the site definition to make sure it works.

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="&amp;nbsp;&amp;nbsp;&amp;nbsp;" Body="&lt;a ID='onettopnavbar#LABEL_ID#'    href='#URL#' accesskey='J'&gt;#LABEL#&lt;/a&gt;" 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 Definitions

In 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 changes

The 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

I tried using ghosting with an HTML page, but it didn't work because HTML pages are cached differently than ASP.NET (. aspx ) pages.


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.

Changing Default.aspx , or any other ghosted file, in the site definition affects all sites based on that definition. However, if you open a site in FrontPage and edit one of the ghosted files, that file becomes unghosted and is instead stored as site content. Even minor edits remove ghostingwhich has two unintended consequences: it increases disk usage since the page is then stored as site content, and it prevents changes in the site definition from appearing automatically.


3.3.3. Debugging Site Definitions

You 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:

  • Use a real XML editor, such as FrontPage, XML Spy, or Visual Studio, that can check the form of XML documents. Checking the form before saving can avoid XML syntax errors such as misspelled element names or incorrect capitalization.

  • Keep a backup of ONet.xml , make one change at a time, restart SharePoint, and see if the change broke anything. This is tedious and slow-going, but it helps a lot when you are first learning to create site definitions.

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.



Essential SharePoint
Essential SharePoint 2007: A Practical Guide for Users, Administrators and Developers
ISBN: 0596514077
EAN: 2147483647
Year: 2005
Pages: 153
Authors: Jeff Webb

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net