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>

</Template>

</Templates>

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="http://schemas.microsoft.com/WebPart/v2" xmlns:iwp="http://schemas.microsoft.com/WebPart/v2/Image">

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

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

<FrameType>None</FrameType>

<Title>$Resources:wp_SiteImage;</Title>

<iwp:ImageLink>/_layouts/images/homepage.gif</iwp:ImageLink>

</WebPart>

]]></AllUsersWebPart>

  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.

<td>

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

              <tr>

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

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

                     &nbsp;

               </td>

               <td>&nbsp;</td>

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

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

                     &nbsp;

               </td>

               <td>&nbsp;</td>

 

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.

Saturday, September 02, 2006

Localization in WebParts

Microsoft Sharepoint Portal Server doesn't have support of localization in multiple

Languages natively. The document at

http://www.microsoft.com/technet/prodtechnol/office/sps2003/maintain/spsinatl.mspx#E5F

 

Discusses this situation. It is clearly mentioned that

SharePoint Portal Server 2003 does not support a mixture of different localized portal servers on the server farm, nor does it support a mixture of different localized Windows Server 2003 servers. All servers running Windows Server 2003 in a farm topology must be in the same language, and all servers running SharePoint Portal Server 2003 in a server farm must be in the same language

 

Still, if you want to perform localization in webparts for whatever reasons, it is simple to do so.

We will create a simple MOSS 2007 webpart with localization support.

 

  • Create a simple class library project and reference to the sharepoint namespace.
  • Create a template of webpart
  • Now we will add a resource file to the project. Choose Add New file from the project menu
    And add a resource file for each of the languages. For example

Healthcare.resx

Healthcare.de.resx for German

Healthcare.fr.resx for French

 

Note that you cannot add App_GlobalResources to the project since it is only valid for the web sites

And not the class library projects.

 

  • Add the following reference to your webpart source file
    using System.Configuration;

using System.Globalization;

using System.Resources;

 

We will pick the language settings from the web.config file. Add the following tag to the

<appsettings> section of the web.config file of your sharepoint web site.

<add key=culture value="de-DE">

 

Add the following class variables to your webpart source file.

CultureInfo cult =  CultureInfo.CreateSpecificCulture(ConfigurationSettings.AppSettings["culture"]);

ResourceManager rm;

 

This will create a CultureInfo object based on the language settings in the web.config file.

 

In the constructor of your webpart add a line like this

rm = new ResourceManager("CustomWebParts.HealthCare", this.GetType().Assembly);

 

Where HealthCare is the name of your resource file ex HealthCare.resx and HealthCare.de.resx

And CustomWebParts is the namespace of your webpart.

 

Basically this line creates a resource manager for the specific resource file.

 

Now we will load all the strings which are used in the webpart source to the resource file.

This is fairly easy.

 

Now to load strings at any point in the webpart source we will use the GetString() method of

ResourceManager class. For Ex

 

protected override void CreateChildControls()

        {

            base.CreateChildControls();

            this.Title = rm.GetString("CarePlan", cult);

        }

 

This method sets the title of the webpart to the appropriate language based on the web.config file

 

The above localization is not specific to sharepoint instead it's an asp.net 2.0 feature.

I can mail the source code of the webpart to anyone if needed.

 

Send your suggestions and comments.