Fundamentals of SharePoint Web Parts (Part I)

• Download source files - 7.1 Kb

Introduction

Since I have been using Code Project as a reference for several years now, I finally decided to make a few contributions of my own. I have been writing some web part components for SharePoint for about two years and while it is not something I do on a regular basis, I have made a few accidental discoveries that I will share with the readers of Code Project.

Some of the Microsoft SharePoint Documentation is not absolutely clear and clarifying this is one of my goals for this article. I also decided that one of the best, most stable, and visible resources on the web for Microsoft Programmers is the Code Project and thus far Code Project has lacked many articles on SharePoint Technologies Web Parts. That being one of my main interests, I decided I would help fill that void as best as I could manage.

This article will be fairly short as I have planned a companion article on deploying Web Parts to be followed by an article on Web Part Communications. The Web Part Communications functionality is one that really makes the development of Web Part Components useful.

So what are Web Parts in relationship to SharePoint, Windows SharePoint Service or SharePoint Portal Services?
SharePoint is a Portal Package that runs in IIS and utilizes the ASP.NET framework to accomplish its basic functionality. So an ASP.NET developer is a logical candidate for fulfilling the role of Web Part Developer. The development of Windows SharePoint Services was inspired by the first Wiki, the Portland Pattern Repository.

Web Part Components compile to .NET Libraries (.dll) and require a filename.dwp in order to be successfully deployed in the site's Web Part Gallery. Additionally if you decide to start your own Web Part from scratch, you will need to add a WP Manifest (Manifest.xml) and a web part dwp (filename.dwp) file in order to successfully deploy a component. If you intend to deploy, you should add a new cab file project to your Web Part Solution. That way you can make use of the ease of deployment via the staadm.exe utility.

Background (Required Software and Environment)

Required

• Windows 2003 Server
• Windows SharePoint Services v2.0
• Visual Studio 2003
• Web Part Templates

Optional (highly recommended)

• Virtual PC
• VMWare or Virtual Server 2005 (There is currently a free version available for download)
  Link: http://www.microsoft.com/windowsserversystem/virtualserver/default.mspx

Aspects of the code

The WebPartRender and CreateChildControls Method are key to producing output in SharePoint. Without utilizing them or by using them incorrectly, you will see nothing after the initial deployment.

Web Parts utilize the output.Write(""); and ControlName.RenderControl(output); methods to render html/text and WebControls. The CreateChildControls method is useful for instantiating WebControls and any attributes of the particular WebControl. The WebPartRender method is most useful for html and text output formatting but is also required in order to produce output of controls.

Web Parts require a reference to the SharePoint libraries in order to function (see code below). Other references should be added dependent on extended functionality required for the Web Part that you might want or need to develop. All Web Parts will need a companion .dwp file in order to be visible in the Sites Web Part Gallery. Most of what constitutes a good or useful Web Part will be familiar to any ASP.NET developer.

//Sample Code
using System;
using System.ComponentModel;
using System.Data;
using System.Runtime.InteropServices;
using System.Web.UI;
using System.Web.UI.HtmlControls;
using System.Web.UI.WebControls;
using System.Xml.Serialization;
using System.Security;
using System.Security.Permissions;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Utilities;
using Microsoft.SharePoint.WebPartPages;

namespace AKWebPart
{
/// <summary>
/// Description for AKWebPart.
/// Simple Web Part
/// </summary>
[DefaultProperty("Text"),
ToolboxData("<{0}:AKWebPart runat=server></{0}:AKWebPart>"),
XmlRoot(Namespace="AKWebPart")]
[GuidAttribute("5623DE5D-A636-4831-AFA0-6ED54F2A4A25")]

public class AKWebPart : Microsoft.SharePoint.WebPartPages.WebPart
{
//Quick Note: The names for the textboxes used are geared
//towards connecting to the northwind sample database
private System.Web.UI.WebControls.TextBox TextBoxID;
private System.Web.UI.WebControls.TextBox TextBoxLastName;
private System.Web.UI.WebControls.TextBox TextBoxFirstName;
private System.Web.UI.WebControls.TextBox TextBoxAddress;
private System.Web.UI.WebControls.TextBox TextBoxCity;
private System.Web.UI.WebControls.TextBox TextBoxRegion;
private System.Web.UI.WebControls.TextBox TextBoxCountry;
private System.Web.UI.WebControls.Button connectButton;

/// <summary>
/// Render this control to the output parameter specified.
/// </summary>
/// <param name="output"> The HTML writer to write out to </param>
protected override void RenderWebPart(HtmlTextWriter output)
{
    output.Write("<table border=0 id='EmpTable' bgcolor='#DFDFDF/'>");
    output.Write("<fieldset dir='ltr' id='DataFieldset' 
    style='border-style:solid; border-width:1px;
          width: 623px; height: 404px; padding-left:4px; 
    padding-right:4px; padding-top:1px; padding-bottom:1px'>
      <legend><font face='Arial'>Data Fields</font></legend>");
    output.Write("<tr><td>");
    output.Write("</td><td>&nbsp;</td><td>&nbsp;</td></tr>");
    output.Write("<tr><td>");
    TextBoxID.RenderControl(output);
    output.Write("</td><td>");
    TextBoxLastName.RenderControl(output);
    output.Write("</td><td>");
    TextBoxFirstName.RenderControl(output);
    output.Write("</td></tr><tr><td>");
    TextBoxAddress.RenderControl(output);
    output.Write("</td><td>");
    TextBoxCity.RenderControl(output);
    output.Write("</td><td>");
    TextBoxRegion.RenderControl(output);
    output.Write("</td></tr><tr><td>");
    TextBoxCountry.RenderControl(output);
    output.Write("</td><td>");
    connectButton.RenderControl(output);
    output.Write("</td><td>&nbsp;</td></tr>");
    output.Write("</fieldset></table><br>");
}

protected override void CreateChildControls()
{
    TextBoxID = new TextBox();
    TextBoxID.ID = "TextBoxID";
    TextBoxID.Text = "0";
    TextBoxLastName = new TextBox();
    TextBoxLastName.ID = "TextBoxLastName";
    TextBoxFirstName = new TextBox();
    TextBoxFirstName.ID = "TextBoxFirstName";
    TextBoxAddress = new TextBox();
    TextBoxAddress.ID = "TextBoxAddress";
    TextBoxCity = new TextBox();
    TextBoxCity.ID = "TextBoxCity";
    TextBoxRegion = new TextBox();
    TextBoxRegion.ID = "TextBoxRegion";
    TextBoxCountry = new TextBox();
    TextBoxCountry.ID = "TextBoxCountry";
    connectButton = new Button();
    connectButton.ID = "ConnectButton";
    connectButton.Text = "Submit";
    Controls.Add(TextBoxID);
    Controls.Add(TextBoxLastName);
    Controls.Add(TextBoxFirstName);
    Controls.Add(TextBoxAddress);
    Controls.Add(TextBoxCity);
    Controls.Add(TextBoxRegion);
    Controls.Add(TextBoxCountry);
    Controls.Add(connectButton);
    connectButton.Click +=new EventHandler(CellButtonClicked);
}

private void CellButtonClicked(object sender, EventArgs e)
{
    //Non Functional here but it does fire a postback event
}
}
}

Below is the basic syntax of the filename.dwp in this case AKWebPart.dwp. The Assembly tag basically references the namespace of the component.

<!-Sample dwp file-->
<?xml version="1.0" encoding="utf-8"?>
    <WebPart xmlns="http://schemas.microsoft.com/WebPart/v2" >
    <Title>AK Web Part</Title>
    <Description>A silly little demonstration Web Part</Description>
    <Assembly>AKWebPart</Assembly>
    <TypeName>AKWebPart.AKWebPart</TypeName>
    <!-- Specify initial values for any additional base 
        class or custom properties here. -->
</WebPart>

<!--Sample Manifest.xml file-->
<?xml version="1.0"?>
    <!-- You need only one manifest per CAB project for Web Part Deployment.-->
    <!-- This manifest file can have multiple assembly nodes.-->
    <WebPartManifest xmlns="http://schemas.microsoft.com/WebPart/v2/Manifest">
    <Assemblies>
        <Assembly FileName="AKWebPart.dll">
        <!-- Use the <ClassResource> tag to specify resources like image files 
             or JScript files that your Web Parts use. -->
        <!-- Note that you must use relative paths when 
            specifying resource files. -->
        <!--
    <ClassResources>
         <ClassResource FileName="Resource.jpg"/>
    </ClassResources>
        -->
    <SafeControls>
        <SafeControl
        Namespace="AKWebPart"
        TypeName="*"
        />
        </SafeControls>
        </Assembly>
    </Assemblies>
    <DwpFiles>
    <DwpFile FileName="AKWebPart.dwp"/>
    </DwpFiles>
</WebPartManifest>

Points of Interest

The simplest way to deploy a web part is to use the stsadm.exe utility. Using STSADM automates a few tasks that would otherwise need to be performed by hand. Setting the appropriate trust level for a web part is accomplished automatically for you with STSADM. If you were to do this by hand, you would need to do several things and in multiple locations in order for your Web Part to function. First the physical file web.config located in the file system root of an SharePoint Site would need to have an entry added for the component.
For example: In the safecontrols section of the web.config c:\inetpub\wwwroot\web.config, you would need an entry like below.

<safecontrols>
<SafeControl Assembly="AKWebPart, Version=1.0.0.0, Culture=neutral, 
        PublicKeyToken=f1840a0873385597"
    Namespace="AKWebPart" TypeName="*" Safe="True" />
</safecontrols>

Next you would need to install your dll in the main web sites bin directory and install the .dwp file in the wpcatalog directory. These are physical directories located in the standard web site file directories.

stsadm.exe is normally located at c:\Program Files\Microsoft Shared\web server extensions\60\bin.

The main web.config file is located in the physical root of the main SharePoint Web Site. Assuming that SharePoint is installed as the root site the location should be c:/inetpub/wwwroot/web.config.

The main locations of critical components of a Web Part deployement are the file locations
c:\inetpub\wwwroot\bin and c:\inetpub\wwwroot\wpcatalog

The bin location holds the dlls of a Web Part deployment and the wpcatalog location holds the .dwp file which provides the XML data that is displayed in a web part gallery.

You could install a Web Part by hand by installing the appropriate files in the above named directories, but I really don't recommend it.

For more information on SharePoint, read this article on CodeProject
http://www.codeproject.com/spoint/EssentialWSSSPS2003Archit.asp

History

• Version one thus far unless I see an error or someone suggests a correction.
• Added Part II Web Part Deployments. You can view it here.