Monday, March 1, 2010

SharePoint 2010 - WebTemplate feature

The new WebTemplate feature element in SharePoint 2010 was introduced mainly as a way to define site definitions in sandbox solutions (since you can't use the traditional site definitions in sandboxes). Still, this doesn't mean that you can't use WebTemplate features in a farm solution - there they can be used as an alternative to the old-style site definitions. About the pros and cons of the WebTemplate feature element – one thing that I can see at this point (we’re still lacking complete documentation on that) is that you may have one or more site definitions in a single feature and you have the option to have site definitions in separate features within a single SharePoint project. So, instead of having to maintain two different types of artifacts – features and traditional site definitions you may have the latter as a feature or a set of features too – this allows for finer control over what site definitions you may have in your farm – you can install and uninstall the WebTemplate features thus enabling or disabling the various site definitions that you have created instead of having to remove the whole solution to get the traditional site definitions removed.

Let me now show you how you can create a WebTemplate feature – so you can start with an empty SharePoint project (or with an existing project of yours) and add an empty SharePoint element to it. You can leave the default name of the element – e.g. EmptyElement1 but it is a good idea to give it the same name as you will put in the Name attribute of the WebTemplate element. I will explain shortly why this is necessary. In the elements.xml file of the empty element item you need to have the WebTemplate element’s XML similar to this one:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

  <WebTemplate Name="SimpleSite" Title="Simple site" BaseTemplateID="1" BaseTemplateName="STS" BaseConfigurationID="0" DisplayCategory="Simple sites" />

</Elements>

In the WebTemplate element you have four mandatory attributes – Name, BaseTemplateID, BaseTemplateName, BaseConfigurationID. While the Name attribute defines the internal name of the site template (that you can use with the object model to create sites based on that definition), the other attributes though required and seemingly specifying something like a site definition inheritance don’t actually do that. At least while I tested I didn’t see that any features or module elements defined in the base site definition got activated when a site based on the new one was created. The exact values for these attributes you can check in the webtemp.xml file or derived webtemp*.xml files in the 14/1033/XML folder. Two other attributes that are important though not mandatory are the Title and the DisplayCategory ones – the former specifies the display name of the site template that will appear in the create site collection or create site application pages and the latter - the category tab under which the template will appear on these pages.

After you have the WebTemplate element in the elements.xml file, you will need the onet.xml file which is actually exactly the same format as we know from the traditional site definitions. As was the general practice with SharePoint 2007 when we used to copy-paste and later modify onet.xml files from the standard site definitions when creating custom ones in this sample I just copied the onet.xml from the STS site definition without any modifications whatsoever. There is one difference however in the onet.xml files for WebTemplate feature elements and the traditional ones – in the former you can have just one Configuration element – actually there may be more than one in your onet.xml (as in the STS onet.xml) but just the one with ID=0 will be used. There is something important about the onet.xml file here – it needs to be in a subfolder of the feature’s root folder with the same name as the Name attribute of the WebTemplate element. That’s why it is handy to have the element item’s name the same as the Name attribute as I mentioned above, otherwise you will need to modify the DeploymentLocation property of the onet.xml file. Note also that the DeploymentType property of the onet.xml (and of the other files that you may have in the site definition) should be set to ElementFile.

The last thing that you need to set is the scope of the feature project item that contains the WebTemplate element item – the scope should be set to Farm – this is the only possible value for farm solution WebTemplate elements. The thing with farm scoped features is that you don’t need to activate them, simply installing them makes them available in the SharePoint farm – so basically you only need to deploy the containing solution to the farm to have the site definitions visible.

Here is a small screenshot of the solution explorer view of the sample project that I created for demonstrating the WebTemplate element:

testdef

So you see that besides the elements.xml and onet.xml files I also added two aspx files to the WebTemplate site definition – they are actually also copied from the standard STS template and are provisioned with a Module element inside the onet.xml file (actually this is true only for the default.aspx file since only the default configuration from the onet.xml file is used here).

After you deploy the solution containing your WebTemplate feature you will be able to see your new site template in the create site collection page in the central administration site – as in the case with my sample solution:

sitetempl

[Updated: 28 Sep 2011]

You can download the sample solution from here. Note – when you create a new site based on this sample site definition it will be exactly the same as look similar to the standard team site template – remember that I simply copied the onet.xml from the standard STS site definition. Note that all the features from the ONET.XML file of the standard STS site definition will be activated in the site based on this custom WebTemplate definition, but in the case of the standard team site definition the newly created site will have additionally all stapling features targeting the standard team site definition (whose number is quite big actually). This is an important difference to have in mind, because the feature stapling mechanism works only with the old style site definitions and not with WebTemplate definitions.

And one list thing here, quite important though – if you need to create a site collection or a site based on a WebTemplate site definition with the object model (or in a portal site definition manifest file) you need to provide the web template name in the following format:

{[id of the WebTemplate feature]}#[Name of the WebTemplate element]

In my sample solution the exact name is this:

{797fb1e4-d407-4599-9853-9a0adbaef1c7}#SimpleSite

This is because the ID of the WebTemplate feature is 797fb1e4-d407-4599-9853-9a0adbaef1c7 and the Name attribute of the WebTemplate element is SimpleSite. Note that you need the curly braces around the feature’s ID.

28 comments:

  1. Great post Stefan. I put together a similar post on my site with an example/sample of a trimmed down ONET.XML.

    http://www.sharepointbits.com/blog/sharepoint-2010-custom-site-templates.html

    ReplyDelete
  2. Have you tried to create a web pith powershell New-SPWeb command using webtemplate name in -Template parameter? I have with very poor results. This format doesn't work {797fb1e4-d407-4599-9853-9a0adbaef1c7}#SimpleSite.

    ReplyDelete
  3. you need to put quotes around the template name like:
    -Template "{797fb1e4-d407-4599-9853-9a0adbaef1c7}#SimpleSite"

    ReplyDelete
  4. It seems that the GUID have to be uppercase. I tried it with lowercase and it resulted this: "WARNING: Template is not found and is not applied."

    With uppercase GUID the site was created with correct template.

    ReplyDelete
  5. HI I tries with {GUID}#sitename through c#.net code it gives File not found error.

    ReplyDelete
  6. Hello palanivel,
    you can check the exact {GUID}#sitename name from the central administration's "create site collection page" - after you select the correct tab in the "select a template" picker (the one on the last image in the posting) you can open the "developer tools" of IE 8 (using the F12 shortcut) and with the pointer tool (leftmost in the tool's toolbar) you need to click on the picker. In the "HTML" view of the tool you will see a "select" HTML element and after you expand it you will see "option" elements for the site templates in the selected category - these will contain the internal names of the site templates.

    ReplyDelete
  7. Hi Stefan,

    do you know how to retrieve the exact name for a subsite WebTemplate? (will not appear in "create site collection" page)

    ReplyDelete
  8. Hi Enric,

    you can use the standard "create site" page instead, you will need to navigate to it entering the URL in browser's link bar manually - it is /_layouts/newsbweb.aspx (the "New Site" link in "Site Actions" menu links to a silverlight containing page which is not suitable in this case)

    ReplyDelete
  9. Hi Stefan,
    Congrats on the post!
    Do you by any chance know how to create a portal site definition manifest? As far as I can see here http://msdn.microsoft.com/en-us/library/ms447717(v=office.14).aspx the WebTemp*.xml files no longer handle portal definitions.

    Thanks!

    ReplyDelete
  10. Hi Coci,
    actually the portal site definition functionality is unchanged in SharePoint 2010. You can check the standard SharePoint webtempsps.xml which contains the "SPSPORTAL" portal site definition.

    ReplyDelete
  11. Hi Stefan,

    I created a Site Template as a WSP.
    Then using PowerShell,
    1. I created a site collection without specifying a template.
    2. Uploaded the WSP in the solution and installed it.

    Now I want to set the template of the site to the custom template that I installed. I tried using Set-SPSite command.

    But it throws a "WARNING: Template is not found and is not applied." message.

    I tried both Holle's and your suggestion but that didnt work.

    Note: I installed the solution using Sandboxed command 'Install-SPUserSolution'

    What is interesting is that when I hit the site in the browser, I do get to select my custom template.

    But I still want to do it through PowerShell.

    Please help..!!

    ReplyDelete
  12. Hi Rahul,
    can you try with this PowerShell snippet:

    $site = Get-SPSite http://myserver/sites/mysite
    $web = $site.RootWeb
    $web.ApplyWebTemplate("{797fb1e4-d407-4599-9853-9a0adbaef1c7}#SimpleSite")

    providing the correct [feature id/template] name combination for your case in the SPWeb.ApplyWebTemplate method.

    ReplyDelete
  13. Thanks Stefan for the quick reply...Found it in another blog as well..tested this and it certainly works..!!

    Find the script that I used to automate this process of creating a site from a custom site template to be used as a Sandboxed WSP

    http://rahul-vartak.blogspot.com/2010/12/deploying-sharepoint-2010-sites-using.html

    Section B) -> Note r)

    Thanks once again..!! Glad to find people working on similar issues on this post..:)

    ReplyDelete
  14. Hello Stefan,

    I created web template as you mentioned above. If I set feature scope to Farm it gives an Error as WebTemplate could not be deployed to Farm but If I select Site then it works. I can see the feaure but cannot use it since template is for site collection. Can anyone help on that?

    ReplyDelete
  15. Hi Mughal,
    This depends on the type of solution that you create - if it is a sandbox solution, then you can use only "Site" scoped feature for the WebTemplate element. If it is a farm solution - then you can only use a "Farm" scoped feature. And from here the visibility of the WebTemplate - in a sandbox solution it will be available only in the site collection to which you deploy the sandbox solution and in the farm solution, the WebTemplate will be globally available in the whole farm.

    ReplyDelete
  16. Hi Stefan,

    I have question. If i built Web Template. I activated web template and created few site collection based on Web Template.
    Later i would like to modify WebTempalte with additional feature to Onet.xml.
    How do i proceed with it.
    If i modify ONET.XML and redeploy it. I do not see new feature on old Site collection

    Appreciate your response

    ReplyDelete
  17. Hi Kaps,
    the automatic updating of "WebTemplate"-s in existing sites is not available out of the box. The same is actually true for the traditional site definitions and this has been a serious problem with SharePoint. I've actually seen many SharePoint experts discouraging the use of site definitions (including WebTemplates) for exactly this reason. Possible approaches would be to leverage the new feature upgrading functionality - either for the WebTemplate feature itself or for a specially designed feature that is added to the ONET.XML
    I've been thinking of implementing a more general solution for this exact issue for some time now, so maybe I will dedicate a whole new posting to it.

    Greets
    Stefan

    ReplyDelete
  18. Hi Stefan,

    Thanks for the great post!

    You state that "when you create a new site based on this sample site definition it will be exactly the same as the standard team site template".

    I might be wrong, but I don't think this is exactly true. When you use the default Team Site template lots of features (both site and web scoped) are activated by default using the Feature Stapling mechanism. Since Feature Stapling isn't available using WebTemplates, none of these features are activated when one creates a WebTemplate based on, for instance, the STS#0 site definition. I implemented this scenario on my development machine and only 4 Site Collection scoped features are activated. When I create a site based on the Team Site definition, around 50 (also hidden) Site Collection features are active by default. This means a huge difference in the offered functionality...

    ReplyDelete
  19. Hi Mark,

    Yes, what you say is exactly correct. At the time I wrote the article I didn't consider the impact of the stapling features, whose number as you rightly point out is close to 50 for the STS#0 site definition (the number is different for the different site definition). Thanks for the correcting remark, I will modify the posting accordingly.

    Greets
    Stefan

    ReplyDelete
  20. Hi Stefan,

    I am struggling with how to change the layout and included web parts in the default.aspx file. It appears that the default.aspx file that is included in the web template feature is not actually used... Even if I remove it, it is still applied, which points to it being applied from the base template and not the one we are providing.

    Have you got any suggestions?

    Best regards,
    "Bear"

    ReplyDelete
  21. Hi Stine,
    You are right about this - I haven't noticed that, because I almost never use Module elements inside the ONET.XML file, instead I use separate features for "Module" provisioning. I tested the case with the Module element in the ONET.XML and saw your issue. As a simple work-around you can remove the Module element from the ONET.XML file (plus the Module reference under the "Configuration" element) and move the file provisioning to a separate feature. This feature then you will reference under the "WebFeatures" element in your ONET.XML file.
    Let me know if this solves your issue.

    Greets
    Stefan

    ReplyDelete
  22. I like your Post very much and It is very interesting. I will use this Info to Develop the SharePoint Applications. Thanks for share this valuable Information.

    ReplyDelete
  23. Thx Stefan - the hint with the "developer tools" of IE 8 (using the F12 shortcut) to dig out the right ("{GUID}#MyCustomTemplate") saved my day :-)
    good job
    Rainer

    ReplyDelete
  24. Wonderful bloggers like yourself who would positively reply encouraged me to be more open and engaging in commenting.So know it's helpful.
    Sharepoint Training in Chennai

    ReplyDelete
  25. Thanks for one marvelous posting! I enjoyed reading it; you are a great
    author. I will make sure to bookmark your blog and may come back
    someday. I want to encourage that you continue your great posts, have
    a nice weekend!
    Hadoop admin training in Chennai
    software testing institute in Chennai
    javascript course in Chennai

    ReplyDelete