Guidelines for Using Custom Site Definitions, Configurations, and Templates
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
This topic provides some guidelines for using the two kinds of foundations for new sites in Windows SharePoint Services 3.0: site templates and site definition configurations (which are a part of site definitions).
Custom Site Definitions and Configurations
To create a custom site definition with one or more custom site definition configurations on front-end servers, you must create a copy of an existing site definition directory and create a site definition as described in How to: Create a Custom Site Definition and Configuration. Changes that you make within originally installed files may be overwritten when you install updates or services packs for Windows SharePoint Services, or when you upgrade an installation to the next product version.
Changing a site definition after it has already been deployed can break existing sites and is not supported. If you must modify a site definition after deployment, be aware that adding features can cause fewer problems than changing or deleting them. Changing features often results in loss of data, and deleting features often results in broken views.
For backup/restore and migration operations, you must restore your site to a server that has the same front-end customizations as the server from which you backed up or migrated.
Customizing a site definition often requires that you reset, or stop and restart, Internet Information Services (IIS) before changes take effect.
Always test custom site or list definitions before deploying them.
Modifying site definition files to customize existing sites or lists is not supported. A good guideline is to use site definitions to modify sites that will be created, but to use the object model to modify sites after they are created.
When modifying site definitions, be aware that the contents of pages customized in Microsoft Office SharePoint Designer 2007 are stored in the database. If you modify, or unghost, a page in SharePoint Designer, changes that you later make to the definition may not affect the page.
Note
You can use the vti_hasdefaultcontent field obtained through the Properties property of the SPFile class to determine whether a file is ghosted.
When you are customizing definitions, a convenient way to generate Collaborative Application Markup Language Core Schemas is to use commands provided in the URL Protocol to return CAML markup.
File Name Restrictions
For security reasons, Windows SharePoint Services reads files in the \\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Template directory tree only if their names are composed of ASCII letters, numbers, periods, underscores, or dashes. In addition, file names cannot contain two or more consecutive periods. For example, the following are permitted file names:
AllItems.aspx
Dept_1234.doc
Long.Name.With.Dots.txt
The following are not permitted file names:
HailCæsar.wav
File Name With Spaces.avi
Wow...ThisIsBad.rtf
揵.htm
Advanced Site Definition Features
In addition to changing the values of commonly used elements and attributes in your custom site definition files (see How to: Create a Custom Site Definition and Configuration), CAML provides special elements and attributes that you can use to make advanced customizations of site definitions and site definition configurations, which are described in the following tables.
Elements
Element |
Description |
Where Added |
|---|---|---|
ExecuteUrl |
Specify a page to open immediately after site creation |
As a child of the Configuration element in the Onet.xml file for the site definition. |
ExternalSecurityProvider |
Implement a custom security provider |
As a child of the Component element in the Onet.xml file for the site definition. |
FileDialogPostProcessor |
Customize the Open or Save dialog box (File menu) used in document libraries |
As a child of the Component element in the Onet.xml file for the site definition. |
Attributes of the Project Element in the Onet.xml File for the Web Site Definition
Alternate |
Description |
|---|---|
AlternateCSS |
Add or modify cascading style sheet (CSS) definitions |
AlternateHeader |
Replace the top navigation area in site pages |
CustomJSUrl |
Provide custom ECMAScript (JavaScript or Microsoft JScript code) functions (such as customizing the Edit menu) |
DisableWebDesignFeatures |
Disable features on a site (such as Backup and Subsite Creation) |
Customizing CSS Style Definitions
You can customize CSS style definitions by creating a .css file with a unique name in \\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\LAYOUTS\LCID\STYLES, where LCID is the numeric ID of the language/culture, such as 1033 for English. Copy into this new file the contents of the default .css file specified within .aspx pages of the site definition, and add or update styles in the new .css file. Use the AlternateCSS attribute to specify the path to the new .css file, such as follows:
AlternateCSS =
"/_layouts/[%=System.Threading.Thread.CurrentThread.CurrentUICulture.LCID%]/styles/MyStyles.css">
Site Templates
When deploying a site template, remember that the .stp file maintains a unique identifier in relation to the originally installed site definition and configuration from which the source site of the site template is derived. This means that a site template does not function unless the original site definition is present on the front-end Web server or servers.
See Also
Tasks
How to: Create a Custom Site Definition and Configuration