Sunday, September 03, 2006

Site Definitions Demystified - Creating a custom site definition having Custom webparts

There are two confusing terms in MOSS 2007, site templates and site definitions.


A site template is a .stp file which contains only the difference of changes from the

Original site definition. A user wants to install a custom .stp file must have a site

Definition installed from which the .stp file was saved.

(Note: In MOSS B2, you can only save top level sites. i.e. site collection as a site

Template. This is a bug and will be corrected in B2TR.)


A site definition on the other hand is a complete definition with a directory structure

Containing .aspx files and important Onet.xml file.


We will create here a simple site definition which when applied shows a custom webpart

On page.


The site definitions are stored in this directory

\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates


Each site definition needs an entry in webtemp*.xml file which are located here

\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\1033\XML


To begin with:


Make a copy of this directory

Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates\sts

In the Site Templates directory and name it sample. This will create a site definition named sample having the

Same structure as team site i.e. sts directory.


Now to make it appear in the create site list, create a file named webtempsample.xml in the directory

\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\1033\XML

And paste these contents


<?xml version="1.0" encoding="utf-8" ?>

<!-- _lcid="1033" _version="12.0.4017" _dal="1" -->

<!-- _LocalBinding -->

<Templates xmlns:ows="Microsoft SharePoint">

<Template Name="SAMPLE" ID="10001">

<Configuration ID="0" Title="Sample Site" Hidden="FALSE" ImageUrl="/_layouts/images/stsprev.png" Description="This sample template creates a site for teams to create, organize, and share information quickly and easily. It includes a Document Library, and basic lists such as Announcements, Calendar, Contacts, and Quick Links." DisplayCategory="Custom Site Definitions" >    </Configuration>

 <Configuration ID="1" Title="Sample Blank Site" Hidden="FALSE" ImageUrl="/_layouts/images/stsprev.png" Description="This sample template creates a Windows SharePoint Services-enabled Web site with a blank home page. You can use a Windows SharePoint Services-compatible Web page editor to add interactive lists or any other Windows SharePoint Services features." DisplayCategory="Custom Site Definitions" >    </Configuration>

<Configuration ID="2" Title="Sample Document Workspace" Hidden="FALSE" ImageUrl="/_layouts/images/dwsprev.png" Description="This sample template creates a site for colleagues to work together on documents. It provides a document library for storing the primary document and supporting files, a Task list for assigning to-do items, and a Links list for resources related to the document." DisplayCategory="Custom Site Definitions" >    </Configuration>



Reset the IIS and try creating the new site. We will get a custom tab while choosing the site definition which

Three choices.


Now the important bit, we will now modify the site definition file onet.xml and place a custom webpart in the definition

So that when site definition is created, a custom webpart appears on the page.

I assume we have a custom webpart .dll and .dwp file ready.


Open the onet.xml file from

\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates\sample\xml


This is the main file of the site definition and it stores the structure of whole site definition.

Observe this section of the file, the <modules> tag.

  1. <Modules>
  2. <Module Name="Default" Url="" Path="">
  3. <File Url="default.aspx" NavBarHome="True">
  4. <View List="$Resources:core,lists_Folder;/$Resources:core,announce_Folder;" BaseViewID="0" WebPartZoneID="Left" />
  5. <View List="$Resources:core,lists_Folder;/$Resources:core,calendar_Folder;" BaseViewID="0" RecurrenceRowset="TRUE" WebPartZoneID="Left" WebPartOrder="2" />
  6. <AllUsersWebPart WebPartZoneID="Right" WebPartOrder="1"><![CDATA[

<WebPart xmlns="" xmlns:iwp="">

<Assembly>Microsoft.SharePoint, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c</Assembly>

  1. <TypeName>Microsoft.SharePoint.WebPartPages.ImageWebPart </TypeName>






  1. <View List="$Resources:core,lists_Folder;/$Resources:core,links_Folder;" BaseViewID="0" WebPartZoneID="Right" WebPartOrder="2" />
  2. <NavBarPage Name="$Resources:core,nav_Home;" ID="1002" Position="Start" />
  3. <NavBarPage Name="$Resources:core,nav_Home;" ID="0" Position="Start" />
  4. </File>
  5. </Module>


If we try to understand this section, we also have an .aspx file in our site definition directory. If we observe the .aspx

File, we will see that it defines two webpart zones, left and right . See the snippet below of .aspx file :

The ids of webpart zones are left and right respectively.


             <table width="100%" cellpadding=0 cellspacing=0 style="padding: 5px 10px 10px 10px;">


               <td valign="top" width="70%">

                     <WebPartPages:WebPartZone runat="server" FrameType="TitleBarOnly" ID="Left" Title="loc:Left" />




               <td valign="top" width="30%">

                     <WebPartPages:WebPartZone runat="server" FrameType="TitleBarOnly" ID="Right" Title="loc:Right" />





The onet.xml defines which webpart goes into these zones and the order of those webparts. If we see the line number

Five above, it defines the right webpart zone and places the .dwp file of the out of the box ImageWebPart in the

CDATA section.


Now delete everything in the CDATA section and place the .dwp file of your custom webpart. We will also have to place

The .dll file in the web application bin directory.



Now again reset the IIS and create a new site based on this definition.

When we will create a site out of this customized site definition, we will get a custom webpart already created on the site

On the right zone.


There are lots of possibilities in customization of onet.xml file. We could have modified the left webpart and zone and

Place another webpart there. Or we could have modified an .aspx file and added more webpart zones.

If that's not enough, we could have added our own custom .aspx file and added its entry in the modules section of the

Onet.xml file. The possibilities are endless !


Mail me your comments and suggestions. I can mail the custom site definition discussed here to the interested.


Anonymous said...

If i want to have a stp file to be used in another site collection, i just need to upload the stp fiel in the site template gallery of that site collection ? would it be possible to save a site template with a scope of farm ?

Madhur said...

If that stp file is created out of "out of the box" site definition, then its fine. otherwise you need to put your custom definition to the server you are uploading your stp file too.

site template can be saved of subsites and site collection. There is no stp file for farm or web application.

Unknown said...

Hi Madhur

I tried your suggestion. I could see the 3 templates - choices. when i create a site it says '403 forbidden after going to default.aspx for that site.

Unknown said...

Solved.....I changed the security permissions for 'sample' folder to inherit rights from parents

Madhur said...

Glad tat it was solved....

Prasad said...

Hi Madhur;

I've created a site definition as you said.
I had a custom web part created and I want to use that web part in my new site definition. for that I've added the <AllUsersWebPart> tag as -

<AllUsersWebPart WebPartZoneID="Right" WebPartOrder="1"><![CDATA[

   <WebPart xmlns="" >

      <Title>Test Web Part 004</Title>

      <Description>Test Web Part 004.</Description>

      <Assembly>TestWebPart004, Version=, Culture=neutral, PublicKeyToken=4aeebad95715deaf</Assembly>




But when I create site based in that new site definition, site is created with no errors but at the Web part area where I added my custom web part it gives me the error as -

Error :

Web Part Error: A Web Part or Web Form Control on this Page cannot be displayed or imported because it is not registered on this site as safe.

How can I add web part as safe control before creting web application for the site?

Any thing I'm doing wrong in it?
Please help me out.

Madhur said...

Hi Prasad

Did you raise the trust level of your web application. Raise the trust level in web.config to Full. check out the exact settings which you need to do.

Anonymous said...

hi Madhur,
I want to know if this will affect existing sites? I have sTP file and sites created out of it.
1. Is it possible to modify this STP file? please provide me some useful link.
2. will changing template , like adding a new list propagate the change to already created sites? How is this possible?
3. Is it possible to propogate change in site definitions (Onet.xml) to affect already existing sites. i changed onet.xml, included new list in it, but it only affects new sites. no changes in existing site?
How can i force changes on sites already created? Some way?

Prasad said...

I had already set the Trust Level to "Full".

Madhur said...

hi prasad..
sorry for late replying. which application's trust level you are setting to full. also have you put the assembly name in web.config's safecontrols section.

Prasad said...

I'm doing entry as safecontrol in inetpub's web.config as well as central admin's web.config.

And I'm making trust level "Full" of web application that I'm creating where I want to apply my site definition.

Madhur said...

hi prasad..
you will also have to put the safe control section in web application where you are creating your site definition. the path should be
c:\inpetpub\www\wss\virtual directories\your port\web.config

Hope it helps

Anonymous said...

Hi ,
Great tip. ThaX.
Is there any way to use the existing site difinition of SharePoint 2003 in SharePoint 2007.



Madhur said...

Hi soumendra...
I am afraid its not possible. The architecture of site definitions of 2003 is completely different from that of 2007 due to introduction of features...

Anonymous said...

Hi Thanks for the quick response.
Now I am no where since I have many site definition present in my V2 portal and my client wants to migrate all of them to V3 having same look and feel.


Mikhail Dikov said...

Useful post, thanks.

Anonymous said...

Hi Madhur,
I have created one STP file and also I installed it properly on MOSS server 2007 with DOS command. I can create site using this Template. I have given it to my client and he also installed it properly but he is not able create site collection from selecting this Template and he getting error as "Template you have chosen is invalid or cannot be found", if you know any solution to this, Please reply as early as possible

Vikas Palaskar

Madhur said...

hi vikas
i have seen this error many times.. usually this occurs due to difference in versions of sharepoint used.. i.e. if u tryin to restore a beta template on a RTM version....
check if this is the case

Prasad said...

Hi Madhur
I had one querry. If I created one site definition and on base of that I created sites say 100 sites. Now I wish to do some change centrally for those 100 sites. I heard that there is a way to do that. If I will modify my master page in site definition then it will take effect in all my 100 sites. So I don't have to go for changing sepearately each site's master page. Is it right? If not then how can I make changes centrally after creating site definition and 100s of sites based on that?


Madhur said...

Hi prasad
Even i am confused about this possibility...
I thought its possible but someone pointed out me in groups that its really not happening ....

Anonymous said...

can we able to create a new site
definition without copying from the existing one

Unknown said...

Hi Madhur,
I have created a site collection using Central Administration Page.
Using SharePoint Generator i created a site definition from site collection.
I deployed the site definition creted using Visual Studio 2005.
Site Definition got deployed successfully, and I was able to use it while creating other site collection. But i don't know how to add new aspx page to Site Definition. If u can provide some light on this, it would be great help for me.

Ivan Sanders said...

If you are creating sites using stp's the sites are un-ghosted.

You will be unable to apply changes to the sites created with stp's.

The correct way is to use site definitions in both v2 and v3

If you use the upgrade definition xml file you can assocaite the v2 sites with a new v3 site definition.

ghost hunter http;// will show you which sites are unghosted in v2. experiment with using stp's and site definitions and you can see the differences

Unknown said...

Hi madhur,

Can we create a copy of an existing website say localhost:4000 on different port say localhost:4001

Anonymous said...

how to add our own custom .aspx file and how to add its entry in the modules section of the onet.xml file.

Its urgent Please help me ASAP.

Unknown said...

Hi This is meera

how to add our own custom .aspx file and how to add its entry in the modules section of the onet.xml file.

Its urgent Please help me ASAP.

Madhur said...


You can get this information from many blogs such as

Madhur said...

Hi sharif

I have just posted the link .. see the previous comment ...

Anonymous said...

I have a custom web part created and I want to use that web part in Allitems.aspx for all discussion board. How it can be done.

Anonymous said...

Hi Madhur,

I would like to customize a survey.

What I need is to add file on every response of a survey. Means user can upload file when respond to a survey.

I need to test it in WSS2.0 as well as MOSS 2007. My plan was to change onet.xml and create a new directory and change the schema.xml file. Unfortunetly it not works with WSS2.0 (I did't try on MOSS 2007).

Can you please give me idea / tricks how to accomplish it.

Thanks in advance.


Madhur said...

I was not able to achive your requirement using ootb survey feature. i guess u will need to custoomize one custom list to give it a functionality of survey since files can be uploaded to lists ....

Anonymous said...

Hi Madhur,

I have created a MOSS site with anonymous access. I have created a list which accepts user feedbacks which is stored in custom list. By default custom list stores users identity and if site is with anonymous access it generates an error while saving the data in list.

Is it possible to keep the anonymous access to the site and at the same time save user data in list?

Madhur said...

I have never worked with anonymous sites .. so dont exactly know.
But one thing, you can do is attach an event handler to the list and handle the ItemAdding event to catch the error

Is the error also generated, if that user field is not compulsory ?

ThummyT said...

Hi, I'm working on a custom site definition based on the team site definition (sts - default) too. (MOSS 2007) In my definition I only added some custom lists and made some layout changes, nothing spectacular. Everything else is still the same as in sts. It works well now, apart from one, nasty issue.
In a generated sts site I can add a webpart to a page, and then I can choose from a large list of webparts (38 different ones), when I add a webpart to a page in a site generated from my custom definition I only can choose from 11 webparts... Outlook Web Acces, Sitemap, Search & Sites-aggregator webparts are not in the list then.

Do you have any idea how this comes? (And what to do about it)

ThummyT said...

PS. After generating a site collection I can manually activate those Site Collection Features, but the team-site definition seems to do that automagically, and I do need to create that in my definition too...

Anonymous said...

Hi Madhur,
i am also having the same issue as raised by someone before regarding site template invalidity.
As per your reply i checked the two version of sharepoint. they are the same. could you guide me as to what might be the reason?

Anonymous said...

i fallowed same as you said upto craete new site definition and webtemp.xml. once site colletion is created successfully . i open that colletion URL in Browser but i am getting error like page can not found
any idea plzz ???

Vijay Kumar said...

Hi madhur

Is it possible to make changes in already created site via its site definition ? please respond it is urgent.

vijay narang

Vijay Kumar said...

Hi madhur

This is another question which i need to answer to my senior that is it possible to completely change site definition of already created site ? even i dont know is site have concern with site definition after creation.

thanx in advance
vijay narang

Madhur said...


Its not possible to change sites which already have been created using site definition.

Nico said...

Hi Madhur!
I'm creating a site with a custom .stp template created from a site that contains a custom web part.
When I create this new site and navigate to the sub site where the web part should be, the message "Web Part Error: A Web Part or Web Form Control on this Page cannot be displayed or imported. The type could not be found or it is not registered as safe." is displayed.
The safe control is declared in web.config file. Also, I can add the web part editing the page.
Any suggestion ?
Thank you!!!

Madhur said...

hi Nico

Make sure that assembly is not changed (i.e. version no. etc) between the time of taking the site template and making restore.

Are you restoring it to same web application or different?

Nico said...

I tried the both options restoring the site.
But I'll check the assembly and do more clean tests, because I just copy the dlls from one application to other. Maybe there is the error.
Thanks again, I will post here the solution if I can find it.

Nico said...

I could fix this..
the problem was in the annotations for the web part class.
The Xml attributes was missing,
So, be carefull with that!


Anonymous said...

I have a dataview webpart created using SPD and it works fine.. I want to add this webpart as a feature into AllUsersWebPart node of module.xml file. I did copied the .webpart code into CDATA of that node but getting error..

Please guide.


Anonymous said...

Great!!!Superb writing!!!
custom website usa

Leyo said...

Did you raise the trust level of your web application. Raise the trust level in web.config to Full. check out the exact settings which you need to do.
creation de site web