4. Building Web Parts - DotNetSpider...U2U trains over a thousand software developers a year in .NET U2U specializes in .NET Solution Development, is Microsoft Certified Technical

4. Building Web Parts 1

4. Building Web Parts

Sample module by Patrick Tisseghem, U2U Managing Partner, Architect and Trainer for .NET Extract from U2U courseware “Building Solutions for Microsoft SharePoint 2003 Products and Technologies”.

Copyright 2003 by U2U nv/sa, Belgium – For use in U2U courses only. Visit www.u2u.net To comment on this page, please send us an email at [email protected].


Copyright © 2003 U2U nv/sa, B-1082 Brussel, Belgium. u2u nv/sa Technologiestraat 1, B-1082 Brussels, BELGIUM

Niets uit dit document mag worden verveelvoudigd en/of openbaar gemaakt door middel van druk, fotokopie, microfilm, elektronisch of op welke andere wijze ook en evenmin in een retrieval systeem worden opgeslagen zonder voorafgaande schriftelijke toestemming van de auteur.

Hoewel dit document met zeer veel zorg is samengesteld, aanvaarden de auteurs geen enkele aansprakelijkheid voor schade ontstaan door eventuele fouten en/of onvolkomenheden in dit document.

Copyright © 2003 by U2U nv/sa, B-1082 Brussels, Belgium. All rights reserved.

No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of the author.

This publication is provided "as is" without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement.

This publication could include technical inaccuracies or typographical errors. Changes are periodically added to the information herein; these changes will be incorporated in new editions of the publication.

Printing history:

August 2003: preliminary version in English

Published by U2U nv/sa, Technologiestraat 1, B-1082 Brussels, BELGIUM


U2U trains over a thousandsoftware developers a year in .NET

www.u2u.netU2U specializes in .NET Solution Development, is Microsoft Certified Technical Education Center based in Brussels.We offer training services on-schedule in Brussels and training on-site throughout whole Europe and Middle-East.More info on http://www.u2u.net U2U nv/sa, Technologiestraat 1, B-1082 Brussels, tel 0032/2.466.00.16

4. Building Web Parts

To comment on this page, please send us an email at [email protected].

4

4.1 The Basics

Web Parts are the basic extensibility objects in SharePoint. They are the building blocks of a so-called smart page in a SharePoint site. Out of the box, SharePoint provides us with a number of Web Parts such as the Content Editor Web Part and the Image Web Part. This list is expanded when installing the Office 2003 Web Parts. A number of Web Parts are also available in the online library.

In this lesson, you will learn

• about the Web Part template you can install as an extension to Visual Studio.NET • the files that make up a Web Part • the basic steps of creating a Web Part

4.1.1 Web Parts are ASP.NET Server Controls

The .NET Framework provides us with a number of class libraries to create ASP.NET applications. SharePoint itself makes use of these libraries to generate the Web pages that make up a site. Developers working in Visual Studio.NET make use of server controls to build the graphical user interface of their Web pages. Pure vanilla HTML can be replaced with smart server-side objects that:

• are capable of maintaining state between post-backs • can be accessed in an object-oriented way in your server-side code • are able to generate browser-specific HTML • are able to accept server-side event handlers

Copyright 2003 by U2U nv/sa, Belgium – For use in U2U courses only. Visit www.u2u.net


Developers who want to create custom Web Parts now can do this in Visual Studio.NET. A Web Part is actually a class that ultimately derives from the System.Web.UI.Control class and thus can be considered as a server control. You do not inherit directly from this class however. It is possible to do this, but then you will have to implement all the necessary interfaces in order to plug your custom Web Part into the SharePoint framework. Microsoft provides a project template that you can download from the downloads section of the MSDN site (http://msdn.microsoft.com) which gives you access to a class, the WebPart class, encapsulating all this plumbing. Your job is to inherit from this WebPart class and add your custom code to it.

4.1.2 Web Part Libraries

Custom Web Parts can be created in Visual Studio.NET by selecting the Web Part Library template. To demonstrate the process of building a Web Part we will create one that consumes the Amazon Web Service.


http://msdn.microsoft.com/


Amazon provides these Web Services via its developer’s kit you have to download from http://www.amazon.com/webservices. Once installed, you need to apply for a developer’s token that will be used to identify yourself when consuming the services.

A Web Part Library project at least contains the following types of files:

• One or more files (*.cs or *.vb) containing classes deriving from Microsoft.SharePoint.WebPartPages.WebPart.

• Every Web Part class should have a corresponding .dwp file. This is an XML file containing some details of the Web Part, such as the title and the description, but more important, a link to the assembly containing the code that needs to be executed. DWP files are the ones that will be dropped into a Web Part library and made available in this way to the users of the portal.

• Your project should also contain one manifest.xml. This file is used during the deployment of the Web Part. It will contain the configuration elements that need to be merged in the web.config of the WSS or SPS site (e.g. indicating that your Web Part is a Safe Control)

4.1.3 Web Part Class

In addition to a new Web Part Library project template, Visual Studio.NET also offers you now a number of item templates generating specific classes or XML files for your Web Part project.

The first two, the Consumer and the Provider Web Part are normal Web Part classes that implement interfaces making it possible for the user of the smart page to make connections between Web Parts. The Tool Part generates a class you can use to extend the task pane with custom properties you expose in your Web Part. In this lesson we will only focus on the basics and therefore the last three items.

Let us remove the first two files and add a new Web Part item named AmazonSearch and a DWP file using the same name.


http://www.amazon.com/webservices


After cleaning up some lines, your generated class contains the following basic code:

using System.ComponentModel; using System.Web.UI; using System.Web.UI.WebControls; using System.Xml.Serialization; using Microsoft.SharePoint; using Microsoft.SharePoint.Utilities; using Microsoft.SharePoint.WebPartPages; namespace U2U.Samples.WebParts { [ToolboxData("<{0}:AmazonSearch runat=server></{0}:AmazonSearch>"), XmlRoot(Namespace="AmazonWebPartLibrary")] public class AmazonSearch : Microsoft.SharePoint.WebPartPages.WebPart { protected override void RenderWebPart (HtmlTextWriter output) { output.Write(); } } }

Notice the one method that gets overridden here: the RenderWebPart. This is the one you as a Web Part developer will use to generate the HTML that will represent your Web Part in the portal page. A number of scenarios are possible here. You can create a HTML snippet using a string and provide this string as an argument for the Write() method of the HtmlTextWriter. The HtmlTextWriter exposes also other methods which give you a more structured way of generating your HTML (such as the RenderBeginTag() and RenderEndTag()).

4.1.4 Creating Child Controls

A last scenario is the creation of server controls that will act as child controls of your AmazonSearch control. We will allow a user to enter a name of an author and search for any matching books on the Amazon site. The HTML representing the TextBox and Button can be generated as a string within the RenderWebPart method. A better approach however is to create a number of child controls for this AmazonSearch control and let them each render their part of the HTML. This way we can easily associate some event handlers for the necessary actions a user has to be able to perform.

Creating child controls in a server control is done by overriding the base CreateChildControls method. We have one event-handler for the click on the search button.



private Label labelSearch = null; private TextBox textBoxSearch = null; private Button buttonSearch = null; private Label labelResults = null; protected override void CreateChildControls() { labelSearch = new Label(); labelSearch.Text = "Search Amazon:"; this.Controls.Add(labelSearch); textBoxSearch = new TextBox(); textBoxSearch.Width = new Unit(100); this.Controls.Add(textBoxSearch); buttonSearch = new Button(); buttonSearch.Text = "Search"; buttonSearch.Click += new EventHandler(this.SearchAmazon); this.Controls.Add(buttonSearch); labelResults = new Label(); this.Controls.Add(labelResults); } protected void SearchAmazon(object sender, EventArgs e) { }

4.1.5 Consuming the Amazon Web Service

Amazon provides several ways of consuming their Web Service. One way is to create an HTTP GET request and send it to the Amazon URI.

This is the query we will launch:

http://xml.amazon.com/onca/xml2?t=webservices-20&dev-t=[developer’s%20token%20goes%20here]&AuthorSearch=Ingo%20Rammer&mode=books&type=lite&page=1&f=xml

The query will be sent via a WebRequest object and the resulting response will be displayed in a custom generated table we will drop in the label. Note that there are of course many ways to visualize the results.

protected void SearchAmazon(object sender, EventArgs e) { StringBuilder sb = new StringBuilder(); try { string request = "http://xml.amazon.com/onca/xml2?" + "t=webservices-20&dev-t=[your dev token]&"+ "AuthorSearch=" + textBoxSearch.Text + "&mode=books&type=lite&page=1&f=xml"; HttpWebRequest req = (HttpWebRequest)WebRequest.Create(request); HttpWebResponse resp = (HttpWebResponse)req.GetResponse();



StreamReader s = new StreamReader (resp.GetResponseStream(),Encoding.ASCII); XmlDocument doc = new XmlDocument(); doc.LoadXml(s.ReadToEnd()); s.Close(); foreach(XmlNode aNode in doc.DocumentElement.ChildNodes) { if(aNode.Name == "Details") { sb.Append("<DIV>"); sb.Append("<TABLE width='500px'”><TR>"); // Photo of book sb.AppendFormat("<TD width='150px' valign='top' " + "rowspan='5'><IMG src='{0}'></TD>", aNode.ChildNodes[7].InnerText); // Title of book sb.AppendFormat("<TD><A href='{0}'><B>{1}</B></A></TD>", aNode.Attributes.GetNamedItem("url").Value, aNode.ChildNodes[1].InnerText); // Authors sb.Append("<TR><TD><I>"); foreach(XmlNode authorNode in aNode.ChildNodes[3].ChildNodes) { sb.AppendFormat("{0}<BR>",authorNode.InnerText); } sb.Append("</I></TD></TR>"); // publisher sb.AppendFormat("<TR><TD>{0}</TD>", aNode.ChildNodes[5].InnerText+"</TR>"); // releaseDate sb.AppendFormat("<TR><TD valign='top'>{0}</TD>", aNode.ChildNodes[4].InnerText+"</TR>"); // price sb.AppendFormat("<TR><TD valign='top'><B>{0}</B></TD>", aNode.ChildNodes[10].InnerText+"</TR>"); sb.Append("</DIV>"); } } sb.Append("</TABLE>"); } catch(Exception ex) { labelResults.Text = "Sorry, unable to retrieve the books!"; } labelResults.Text = sb.ToString(); }

4.1.6 The Rendering Block

The last block of code we will have to write to finish our Web Part is the RenderWebPart method. Here we first ensure that all the child controls are created, and next we write out the



HTML. A table is inserted in the Web Part and every control we have created as a child control is asked to render its HTML inside this table.

protected override void RenderWebPart(HtmlTextWriter output) { EnsureChildControls(); output.AddAttribute(HtmlTextWriterAttribute.Width,"100%",true); output.AddAttribute(HtmlTextWriterAttribute.Cellpadding,"3",true); output.RenderBeginTag("TABLE"); output.RenderBeginTag("TR"); output.RenderBeginTag("TD"); this.labelSearch.RenderControl(output); output.RenderEndTag(); output.RenderBeginTag("TD"); this.textBoxSearch.RenderControl(output); this.buttonSearch.RenderControl(output); output.RenderEndTag(); output.RenderEndTag(); output.RenderBeginTag("TR"); output.AddAttribute(HtmlTextWriterAttribute.Colspan,"2",true); output.RenderBeginTag("TD"); this.labelResults.RenderControl(output); output.RenderEndTag(); output.RenderEndTag(); output.RenderEndTag(); }



4.2 Packaging and Deploying Web Parts

4.2.1 Web Part Libraries

Web Parts need to be deployed at specific locations, also referred to as libraries. Users, with the proper rights, visiting their smart pages can browse for Web Parts available in one of these Web Part libraries:

• Web Part Page Library This library contains the Web Parts for a specific page. Any Web Part that you close (that is removing of the page), is available again via the Web Part Page Library.

• Site Library Web Parts can also be restricted to a specific site (team, division, my site, …).

• Virtual Server Library When you deploy your Web Parts here, you will make them available to any Portal site that is hosted by that specific virtual server.

• Online Library This library contains Web Parts that are made available via the Web.

We will drop our Amazon Web Part in the virtual server library making it available to everybody using our portal.

It is obligatory that Web Part assemblies distributed for everybody have a strong name. Use the strong name utility within the SDK (sn.exe) to generate a public private key pair and include it in the build process of your assembly. The assemblies need to be dropped in the GAC.

4.2.2 The DWP File

Every Web Part is accompanied by a DWP file. The DWP file refers to .NET assembly generated via Visual Studio.NET. Open it and edit it accordingly. The public key token can be retrieved from the assembly by dropping it first in the Global Assembly Cache (GAC) and viewing its properties. You can then remove it again out of the GAC since we will deploy the assembly as a private assembly for the SharePoint portal.

<?xml version="1.0" encoding="utf-8"?> <WebPart xmlns="http://schemas.microsoft.com/WebPart/v2" > <Title>Amazon Search</Title> <Description>Allows a user to search for the books of an author.</Description> <Assembly>AmazonWebPartLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=6cc39a1aeddf221c</Assembly> <TypeName>U2U.Samples.WebParts.AmazonSearch</TypeName>  </WebPart>

Copyright 2003 by U2U nv/sa, Belgium – For use in U2U courses only. Visit www.u2u.net

To comment on this page, please send us an email at [email protected].


4.2.3 The Manifest

As mentioned, the manifest.xml is used during the deployment and contains the list of DWP’s made available within your project. This file also allows you to define the list of resources (images, xml files) your Web Part is using. These resources will then be copied in the appropriate folder within the SharePoint portal.

<?xml version="1.0"?>   <WebPartManifest xmlns="http://schemas.microsoft.com/WebPart/v2/Manifest"> <Assemblies> <Assembly FileName="AmazonWebPartLibrary.dll"> <ClassResources> <ClassResource FileName=""/> </ClassResources> <SafeControls> <SafeControl Namespace="U2U.Samples.WebParts" TypeName="*" /> </SafeControls> </Assembly> </Assemblies> <DwpFiles> <DwpFile FileName="AmazonSearch.dwp"/> </DwpFiles> </WebPartManifest>

4.2.4 Deploying the Web Part Files

The actual deployment can be done manually or via the STSADM.EXE tool provided by SharePoint. The following locations are used by SharePoint:

• Your assembly (AmazonWebPartLibrary.dll) needs to be dropped in the GAC.

• Your DWP files need to be dropped in the /wpcatalog folder

• Your resources should be placed in the /wpresources folder

• And finally, the web.config of the SharePoint site should contain an entry specifying that your Web Part is a safe control to be used on the portal pages.

We will use the STSADM.EXE tool to do all the work for us. As a developer, you will have to create a cabinet file (AmazonWebPartLibrary.cab) containing the different files you want to deploy:



Build the setup project and open a command prompt to execute the STSADM.EXE. This tool can be found in the folder “C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\bin”.

The syntax for installing the Web Part is the following:

Stsadm.exe –o addwppack –f AmazonWebPartLibrarySetup.cab

Don’t worry if the tool gives you a deployment failed message (remember that you are still working with a beta version). You should verify whether the dwp and dll are copied correctly and whether the web.config has the entry for your Web Part. If so, you are ready to use the Web Part.

4.2.5 Testing the Web Part

Portal users with the appropriate rights can now browse the virtual server library for your Web Part and drop it upon one of their pages. Using the textbox they are now able to enter a name of an author (or part of it) and the Web Part will communicate with the Amazon Web Service.





4.2.6 Debugging a Web Part

What about debugging a Web Part? In many cases you will probably not have your code working correctly immediately. Web Parts can be debugged by attaching VS.NET as a debugger to the wp3wp.exe process that corresponds to the application pool in which your portal code is running. Once you succeed in doing this, you will be able to make use of all the powerful debugging tools of VS.NET.

It is also advised that you change the output path of your Web Part project in VS.NET so that the generated assembly is immediately replacing the one that is stored in the virtual server library.

4.2.7 Safe Mode Rendering

So you have seen how relatively easy it is to create Web Parts that are dropped on SharePoint pages. Administrators of servers typically will ask immediately: what about security? How can I make sure that Web Parts developed either internally or externally will not crash my SharePoint server?

The answer is safe mode rendering. SharePoint provides a safe execution environment for your Web Parts. Administrators can decide one by one which Web Parts are safe controls. They can verify whether the code is not harmful or is coming from untrusted developers.

You need administrative permissions to be able to register the control as a safe control in the SharePoint libraries.

• The .NET assembly containing the server-side code that needs to be executed is to be deployed either in the bin directory of your virtual server or in the Global Assembly Cache (GAC).

• Next, you need to enable the assembly in the SafeControls list in the web.config of your virtual server directory.

If the class has not been marked as safe, the control will not instantiate during the rendering on the page. The part will be visible in the Web Part library, but not usable.





4.3 Lab 1 – Creating the Amazon Book Review Web Part

In the previous two lessons, you have seen the basics of creating Web Parts. It is time now to create one your self. In this lab, you are asked to create an Amazon Book Review Web Part. As you may know, Amazon visitors can comment on books (or other products). It is often interesting to read these reviews before buying the book. Your shop will be to make that functionality available on a ‘smart’ page within a SharePoint site.

For the purpose of the course, you will work with an already registered developer’s token. If you want to repeat this lab at home, we advise you to download the Amazon’s Web Service Developer’s Kit and register for your own developer’s token (http://www.amazon.com/webservices).

Estimated duration: 60’

4.3.1 Exercise 1 – Creating the Web Part project in Visual Studio.NET

Your first job is to create a new project in Visual Studio.NET (name it MyAmazonWebParts). Do not add your new Web Part to the existing solution you may have created along with the trainer in the lessons. The purpose of the lab is also to repeat all the steps for packaging and deploying the Web Part.

Remove the dwp and the WebPart1 class from the project. Add the necessary files to create a new Web Part called AmazonBookReview.

4.3.2 Exercise 2 – Creating the Child Controls

The Web Part will not show a very complicated interface. You need two labels, a textbox and a button on the page. Use the proper method of your parent class to create these child controls.

Associate an event handler to the button. In the handler, write the necessary code to consume the Amazon Web Service. The request you need to send can again be done using a plain HTTP-GET method.

string request = "http://xml.amazon.com/onca/xml2?" + "t=webservices-20&dev-t=[D1LKOL21AANCMO]&"+

"AsinSearch=" + textBoxASIN.Text + "&mode=books&type=heavy&page=1&f=xml";

Create an HTML table using the StringBuilder class that will present the response from the Amazon Web Service to the user. Feel free to give it your personal touch.


http://www.amazon.com/webservices)


4.3.3 Exercise 3 – Rendering the HTML

Use the RenderWebPart procedure to render all of the HTML in the page.

4.3.4 Exercise 4 – Packaging and Deploying

Time to test your Web Part. As a first step, create a public key pair using the Strong Naming SDK Utility (sn.exe) using the –k option. Provide a value for the AssemblyKeyFile attribute in the AssemblyInfo.cs. Also give a proper version number to your assemby. Rebuild your project. The result is a signed assembly with a strong name.

What is the public key token for your assembly?

………………………………………………………………………………………………………..

Modify the DWP file with a title, description, the necessary information concerning the full name of the assembly packaging your Web Part code, and finally the fully qualified name for the class representing the Web Part. Refer to the Amazon Search DWP for an example.

Modify the manifest.xml file with the details on the DWP’s that will be deployed in one of the SharePoint libraries. Refer to the Amazon Search DWP for an example.

What was the purpose again of this manifest.xml?

………………………………………………………………………………………………………………………………..

………………………………………………………………………………………………………………………………..

………………………………………………………………………………………………………………………………..



Create a new cabinet project in your solution to package all the necessary files for the automatic deployment via the STSADM.EXE tool. Copy all the files you need into this cabinet project.

Build the cabinet project.

Open a command prompt and execute the STSADM.EXE tool. What should you do to verify whether the installation of the Web Part was succesfull?

………………………………………………………………………………………………………………………………..

………………………………………………………………………………………………………………………………..

Create a new Web Part page in your SharePoint site and test your work. If you have problems, use the debugging capabilities of Visual Studio.NET to fix your bugs.



4.4 Web Parts and User Controls

In the previous lessons you have learned the steps of creating a Web Part using Visual Studio .NET. At this moment, developers of Web parts do not have a designer for a WYSIWYG creation of the controls embedded within the Web part. Several people mentioned in the newsgroups available on the Web the possible usage of user controls in the development process of Web Parts for SharePoint pages. This lesson summarizes all these ideas and describes a framework for building Web Parts making use of ASP.NET user controls.

4.4.1 SharePoint Request Handling

SharePoint sites are hosted on a IIS 6.0 virtual server where an ISAPI filter (stsfltr.dll) intercepts all of the incoming requests. The requests are handled by the SharePoint framework consulting the config SQL Server database and then generating the response based on the data available in the content SQL Server database. Since all of it is running on the ASP.NET framework, an HttpHandler (Microsoft.SharePoint.ApplicationRuntime.SharePointHandlerFactory) is taking the responsibility of actually generating the dynamic response of the SharePoint pages.

A direct result of this, is that ordinary ASP.NET applications and Web Services will have difficulties running their code on the SharePoint extended virtual server. The only way you can avoid the stsfltr.dll to intercept a request directed towards your own ASP.NET application or Web Service running on the same virtual server as SharePoint, is by adding these sites to the managed path listing of SharePoint.

Here is the procedure of allowing normal ASP.NET related requests to by-pass the stsfltr.dll:

• Activate the SharePoint Central Administration site from within your Administrative Tools.

• Click on the Configure Virtual Server Settings. • Select your Virtual Server.



• Click on the Define Managed Paths link in the Virtual Server Management section.

• Add a path to exclude, pointing to the URL of your custom ASP.NET application.

To help us build our Web Parts in a more visual way, we can add a path for an ASP.NET application that will contain the user controls to be embedded on Web Parts. In the example below, I have created a new virtual directory in IIS called UserControls and used SharePoint Central Administration to exclude this path. Now we are ready to host any normal ASP.NET-related files in this directory.

4.4.2 Creating the Amazon Search User Control

Visual Studio.NET provides excellent support for the building of ASP.NET applications. User controls provide to developers a quick way of creating re-usable building blocks that can be dropped upon existing or new Web pages.

I refer to the previous lessons for more details regarding the Amazon Web Service and the code associated with it. Looking at the code of that first version, you can notice that all of the child controls (such as the label, the textbox and more) are created in code itself.

private Label labelSearch = null; private TextBox textBoxSearch = null; private Button buttonSearch = null; private Label labelResults = null; protected override void CreateChildControls() { labelSearch = new Label(); labelSearch.Text = "Search Amazon:"; this.Controls.Add(labelSearch); textBoxSearch = new TextBox(); textBoxSearch.Width = new Unit(100); this.Controls.Add(textBoxSearch);



buttonSearch = new Button(); buttonSearch.Text = "Search"; buttonSearch.Click += new EventHandler(this.SearchAmazon); this.Controls.Add(buttonSearch); labelResults = new Label(); this.Controls.Add(labelResults); }

Making use of the framework user controls provide us, we have the ability to simplify the Web Part code considerably.

Create a new ASP.NET application using Visual Studio.NET. You can directly point to the new UserControls virtual directory, or decide to first create the ASP.NET application using a non-SharePoint specific virtual server and later deploy the necessary files into the UserControls virtual directory (that is, the ASCX file and the generated assembly).

Tip: To avoid problems, remove the web.config and the global.asax from your project.

I have opted here for the same approach as in the previous lessons. A label will be filled up during the execution of our code with the results returned by the Amazon Web Service. However, now that you have the designer to facilitate your work, you can make use of all the possible ASP.NET server controls (such as the rich databound controls) to display the results to the user.

A Web form can easily be added to the project and used for testing and debugging your code.

The event-handler for the search button is still executing the same code as before:

private void buttonSearch_Click(object sender, System.EventArgs e) { StringBuilder sb = new StringBuilder(); try { string request = "http://xml.amazon.com/onca/xml2?" + "t=webservices-20&dev-t=[Your Amazon Token]&"+ "AuthorSearch=" + textBoxAuthor.Text + "&mode=books&type=lite&page=1&f=xml"; HttpWebRequest req = (HttpWebRequest)WebRequest.Create(request); HttpWebResponse resp = (HttpWebResponse)req.GetResponse(); StreamReader s = new StreamReader (resp.GetResponseStream(),Encoding.ASCII); XmlDocument doc = new XmlDocument(); doc.LoadXml(s.ReadToEnd()); s.Close();



foreach(XmlNode aNode in doc.DocumentElement.ChildNodes) {

if(aNode.Name == "Details") { sb.Append("<DIV>"); sb.Append("<TABLE width='500px' " + "style='font-family:arial;font-size:10pt;'><TR>"); // Photo of book sb.AppendFormat("<TD width='150px' valign='top' " + "rowspan='5'><IMG src='{0}'></TD>", aNode.ChildNodes[7].InnerText); // Title of book sb.AppendFormat("<TD><A href='{0}'><B>{1}</B></A></TD>", aNode.Attributes.GetNamedItem("url").Value, aNode.ChildNodes[1].InnerText);

// Authors sb.Append("<TR><TD><I>"); foreach(XmlNode authorNode in aNode.ChildNodes[3].ChildNodes) { sb.AppendFormat("{0}<BR>",authorNode.InnerText); } sb.Append("</I></TD></TR>"); // publisher sb.AppendFormat("<TR><TD>{0}</TD>", aNode.ChildNodes[5].InnerText+"</TR>"); // releaseDate sb.AppendFormat("<TR><TD valign='top'>{0}</TD>", aNode.ChildNodes[4].InnerText+"</TR>"); // price sb.AppendFormat("<TR><TD valign='top'><B>{0}</B></TD>", aNode.ChildNodes[10].InnerText+"</TR>"); sb.Append("</DIV>"); } } sb.Append("</TABLE>"); } catch(Exception ex) {

labelResults.Text = "Sorry, unable to retrieve the books!"; } labelResults.Text = sb.ToString();

}

4.4.3 Creating the User Control in the Web Part

Once the user control is doing what it is supposed to do, it is ready to be embedded within a Web Part. All you have to do now is to create a new project based on the Web Part library project template that is available for download from the MSDN site.

The Web Part library project needs a reference to the .NET assembly generated by the ASP.NET Web application in which you have created the user control. If the namespace you have used for the user control is different than the one you have used for the Web Part, then you will have to declare the namespace at the top of your Web Part code.



The CreateChildControls() only contains now the code that takes care of the creation of our user control object and adding it to the controls collection of the Web Part. In the RenderWebPart() we ask the user control to render itself. As you see, the code is a lot simpler than the one written in the previous lessons.

using System; using System.ComponentModel; using System.Web.UI; using System.Web.UI.WebControls; using System.Xml.Serialization; using Microsoft.SharePoint; using Microsoft.SharePoint.Utilities; using Microsoft.SharePoint.WebPartPages; namespace U2U.Samples.WebParts { [ToolboxData("<{0}:AmazonUserControl runat=server></{0}:AmazonUserControl>"), XmlRoot(Namespace="U2U.Samples.WebParts")] public class AmazonUserControl : Microsoft.SharePoint.WebPartPages.WebPart { protected AmazonSearch amasearch = null; protected override void CreateChildControls() { this.amasearch = new AmazonSearch(); this.Controls.Add(this.amasearch); } protected override void RenderWebPart(HtmlTextWriter output) { this.EnsureChildControls(); this.amasearch.RenderControl(output); } } }

The deployment of the Web Part follows the same procedure as described in the previous lesson. In short, you make sure you have a DWP file that contains all the details necessary for SharePoint to load the Web Part (that is the title, the description, the fully qualified name of the assembly and the class representing your Web Part). If you make use of the stsadm.exe utility to deploy the Web Part, you also have to modify the manifest.xml in your solution explorer with an entry for your Web Part. The Web Part dll, the dwp file and the manifest.xml should then be packaged in a cabinet file.

When everything has been deployed correctly, users will see the dwp in the virtual server library. They can add the Web Part on the page via a drag and drop operation.





4.5 Connecting Web Parts

An exciting feature of the ‘smart’ pages in a SharePoint site is that users can drag and drop Web Parts on a page and connect these Web Parts with each other. These Web Part connections allow our Web Parts to send and receive basic types of information. For those of you who have been doing these kinds of things with the previous version of SharePoint, you will experience that the framework provided now makes it much more easier, productive and richer to do your work.

Web Part connections can be demonstrated very quickly with the Office Web Parts that are available in your virtual server library.

Add an Office SpreadSheet Web Part and a PivotChart Web Part on the page. Connect to some data in the SpreadSheet and put your page into design mode. Using the control menu of your Web Part, you can connect the SpreadSheet with the PivotChart in a very user-friendly manner.

The question of course is, can we add the same functionality to our custom Web Parts? I hope to provide you the necessary information in this lesson.

4.5.1 The Connections Framework

As mentioned, SharePoint (be it on a portal or on a team site) provides your Web Parts with a connection framework that makes it possible for these Web Parts to send and receive basic types of data. Examples are cell data, a complete row from a list or even a list itself.

The only thing that Web Parts have to do in order to hook into this framework is to expose a standardized set of interfaces. We will of course cover these interface in more detail later in this lesson.

The cool thing about the whole connections framework in SharePoint is that we can have completely independent Web Parts talking to each other and interchanging data with each other. It does not matter whether these parts are created by Microsoft, third party vendors or you or your co-workers. Once they expose the interfaces and once they are dropped on a page, the SharePoint Web Part framework will automatically detect the connectability between the various Web Parts. The framework will even auto-detect the different combinations that are possible for doing the data interchange.

Important to note is that the connections can and will be made by end users and not directly by the developers themselves. Developers will create Web Parts that expose the interfaces. Users will either in the browser itself or in FrontPage will connect the parts with each other.



4.5.2 What are the scenarios?

You can think of a lot of scenarios where you could use this concept of connecting Web Parts with each other.

Master/Detail Relations

Here is an example showing one Web Part displaying information about employees in a grid-like fashion. Another part can show the details regarding the selected employee. So Web Part one (the master) is sending either cell data (e.g. the ID of the employee) or even the complete selected row to the second Web Part which knows what to do with it.

Parent/Child Relations

Two Web Parts displaying data in grids can be linked to each other to display parent-child relations. Here is an example with orders and order details.

Data Entry and Filtering

Search forms can be connected with Web Parts that are capable of displaying the results of the search operation. Think of the Amazon Search Web Part we have created in the previous lessons. We can create a second Web Part that receives the search input and is responsible for displaying the result of the consuming of the Web Service. Not anymore doing everything in that one Web Part.



Calculations

Actually, a variation on the master/detail scenario. The second Web Part knows about the details of the selected book and based on certain business rules, it can display the details of the book in a more form-like manner and also it can do a number of calculations for the user.

Alternate Views

Data in one Web Part can be displayed using an other view in another Web Part. Here the entire list of data in the inventory form is displayed as a chart in the second Web Part.

Data Enhancements

Give a richer user experience by connecting two Web Parts displaying data in different ways. For example the second Web Part can receive the entire selected row and displays one of the cells in the row in a enhanced way (in this case as a photo instead simply binary info).



4.5.3 Demonstration – Making the Connections

Before we continue and have a closer look into the interfaces of the connections framework itself, your trainer will do a little demo with Web Parts that are available out-of-the box.

The goal of this demo is to demonstrate how a custom list storing details of the trainers at U2U can be made visible on a Web Part page using the two views we have created in previous lessons. Since they are custom lists, they already expose a number of interfaces we can use to hook up each of them with each other.

Here is the Web Part page showing the two lists we are going to use for the demo.

After switching the page in design mode, we can connect the U2U Trainers Web Part with the Details Web Part using the context menu of the first one.

The connections framework then needs to know which columns to use for making the mapping. So, you will get to see two dialog boxes asking you the column of the first list and the column of the second list you want to use for the mapping.



After having done this, the Web Part is enhanced with radio buttons to enable a user to make a selection. Making the selection has an immediate effect on the details Web Part as you can see.

4.5.4 Providers and Consumers

What do the Web Parts in all these scenarios have as common underlying technology in order for them to connect with other Web Parts? All of them expose some SharePoint specific interfaces. A Web Part can play the role of a provider of data, and one can play the role of a consumer of data. A Web Part can even play both of these roles.



The following provider and consumer interfaces can be implemented by your Web Parts. These are the basic interfaces consisting out of providers communicating data to a consumer of the same type. For the moment we will discuss only the one-to-one mappings. We will see later that you can also combine different types of interfaces with each other. Additionally, some of the interfaces allow for connections only using FrontPage 2003.

Each of these interfaces provide a different level of granularity in regard to the data that is transmitted from one Web Part to the other.

ICellProvider -> ICellConsumer

A Web Part implementing an ICellProvider interface is able to communicate one piece of data to a Web Part implementing the ICellConsumer interface. Examples are master/detail scenarios where the master is communicating for example an employee id to the consumer. The consumer uses this id to do a lookup in the database for more details on the employee.

IRowProvider -> IRowConsumer

Typically interfaces exposed by grid-like Web Parts have the need to communicate a row of data to each other. The calculations scenario can be built with Web Parts exposing these types of interfaces.

IListProvider -> IListConsumer

Web Parts can also communicate an entire list of data to each other. Web Parts exposing these interfaces can be created to support the alternate view scenario.

IFilterProvider -> IFilterConsumer

The data entry and filtering scenario can consist out of one Web Part providing some columns and values to the second Web Part which is using it to filter some internal data.



4.5.5 Events and Event Handlers

All of the interfaces we have discussed in the previous topic consist out of events and event handlers. What follows is a summary these per interface we will discuss.

ICellProvider

• Events o CellProviderInit()

This is an initialization event. It allows the provider to broadcast some initialization information to all the Web Parts that make a connection to it. An example can be the communication of the cell name to the provider.

o CellReady() This is the event that the provider will actually fire when it is ready to send the data to the consumers. This event is for example triggered when the user makes a selection (of for example a trainer).

• Event Handlers o CellConsumerInit()

This procedure handles the event that is fired by a Web Part that implements the IcellConsumer interface.

ICellConsumer

• Events o CellConsumerInit()

• Event Handlers

o CellProviderInit() The procedure that handles the CellProviderInit event triggered by the Web Part implementing the ICellProvider.

o CellReady() The procedure that handles the CellReady event triggered by the Web Part implementing the ICellProvider. This is probably the most important one here because here you receive the data from the provider and you as a consumer have to react to it.

IRowProvider

• Events o RowProviderInit()

Same as the previous. An initialization event that can be fired to notify the consumer. In this case, it can be the listing of row columns.

o RowReady() This one is fired and passes the complete row to the consumer part.

• Event Handlers o No event handlers here because the IRowConsumer interface is not exposing

any event.

IRowConsumer

• Events o None



• Event Handlers o RowProviderInit()

Do something when the provider gets initialized. o RowReady()

Do something when the provider sends you a row of data.

IListProvider

o Events o ListProviderInit()

This is our initialization event. o ListReady()

This is the event we fire to send the actual list of values to the consumer. o PartialListReady()

This event can be fired to send a partial segment of the list to the connected Web Part. This can be usefull in a streaming scenario where you do not have the complete list yet in your provider Web Part and already want to send some of it to the consumer Web Part.

o Event Handlers o None

IListConsumer

o Events o None

o Event Handlers

o ListProviderInit() o ListReady() o PartialListReady()

IFilterProvider

o Events o SetFilter()

Event to be used to establish the filter criteria for the connected parts. o ClearFilter()

This event will be fired to clear out those filter criteria. o NoFilter()

This event is fired to notify the connected Web Parts that there are no changes in the filtering criteria.

o Event Handlers o FilterConsumerInit()

Deals with the initialization event fired by the consumer.

IFilterConsumer

• Events o FilterConsumerInit()

• Event Handlers

o SetFilter()



o ClearFilter() o NoFilter()

4.5.6 Provider and Consumer Web Parts in Visual Studio.NET

The Visual Studio.NET Web Part project template delivers two classes that already implement either a provider or a consumer interface. To demonstrate the basic interfaces mentioned above, we will built a new Web Part library project in VS.NET. The library is called HRWebPartLibrary and will contain a number of Web Parts that can be used to display and work with human resources information.

Visual Studio.NET allows for the addition of two specific classes implementing an ICellProvider or an ICellConsumer interface. Note that there is no class template per specific interface. You will have to manually implement the other interfaces yourself.

We will cover one example in detail.

List of Employees -> More details on the Employee

A first Web Part we are going to add is the EmployeeListWP exposing the ICellProvider interface. The goal of the Web Part is to display a list of employees with columns providing some values. With a second Web Part implementing an ICellConsumer interface, the user will be able to see the full details of the selected employee. The first Web Part will communicate the employeeId to the second one.

Creating the Web Parts

Both the Web Parts can be created first using the technique of the user controls. This way we can minimize the code we have to write in the Web Parts themselves and we can also better test and debug the basic content code.

The list of employees is displayed using a datagrid control. The second Web Part simply displays some of the details of the employee in a table.



Both user controls are available on your CD-ROM.

We can use them to build our Web Parts. Let us start with the first one, the EmployeeListWp. Add a Provider Web Part and a Web Part Dwp to your Web Part project.



We will make sure first that the user control makes up the content of the Web Part before covering the interface that is implemented by the class.

Repeat the steps of lesson 3 to load the user control and ask it to render its HTML.

private EmployeeList uc = null; protected override void CreateChildControls() {

uc = (EmployeeList)Page.LoadControl ("/UserControls/EmployeeList.ascx"); this.Controls.Add(uc);

} protected override void RenderWebPart(HtmlTextWriter output) { this.EnsureChildControls(); uc.RenderControl(output); }

Deploy everything according to the rules and test your Web Part in a SharePoint page.



We can now do the same thing for the details by adding a new Consumer Web Part together with a dwp file. The manifest.xml has to be updated with a new entry for the dwp file.

The EmployeeDetailWP Web Part contains the following code for the building up of its contents:

private EmployeeDetails uc = null; protected override void CreateChildControls() { uc = (EmployeeDetails)Page.LoadControl ("/UserControls/EmployeeDetails.ascx"); this.Controls.Add(uc); }

protected override void RenderWebPart(HtmlTextWriter output) { this.EnsureChildControls(); uc.RenderControl(output); }

Here is the result after putting all the pieces together, deploying the Web Parts correctly and adding them to a page.

At this moment, no interaction has been established by the two Web Parts. However, the basic connection framework does already exists since we have one part implementing a provider interface and a second part implementing a consumer interface.



Setting up the Provider Connection Interface

The EmployeesListWP already implements the ICellProvider interface. Looking at the ICellProvider interface definition in the Object Browser, you notice that two events are specified.

These events need to be implemented in your class. (The class template has already generated this code.)

public event CellProviderInitEventHandler CellProviderInit; public event CellReadyEventHandler CellReady;

One additional member, the CellConsumerInit method, also needs to be implemented in your class. This method is not used that much. It allows a provider to be notified of the type of the cell data the consumer is interested in.

public void CellConsumerInit (object sender, CellConsumerInitEventArgs cellConsumerInitArgs) { }

Actually that is all you need to implement for the ICellProvider interface. But it is not enough. The WebPart base class has 6 methods that need to be overridden in order to be hooked up in the Web Part Framework as a connectable Web Part.

EnsureInterfaces() The Web Part Framework calls this method on your Web Part to see whether you are exposing certain interfaces. Within this method you have to register each of the interfaces you are exposing. The registration is done by calling the RegisterInterface() method providing a value for each of the 8 parameters:

• InterfaceName Each interface implemented by the Web Part should get a unique name. Just like in the old days, you can prefix the name of your interface with a _WPQ_ token that is recognized by the framework and replaced at runtime with a generated name for your Web Part.

• InterfaceType The type of interface you are exposing. A number of constants are defined via the InterfaceTypes enum.



• MaxConnections Developers can limit the amount of connections that can be made using this interface. This is most of the time used by consumer interfaces to protect the consumer Web Part for an overload of input. You have two options: one or unlimited.

• RunAtOptions Connections can be activated and implemented on the client, on the server, or both. For this course we will concentrate on connections that are doing their work on the server.

• InterfaceObject Simply a reference to the object implementing the interface.

• InterfaceClientReference This parameter is only to be given a value when you go for client-side connections. In that case, you need to provide the identifier for the client-side object implementing the interface. Again use the _WPQ_ token to generate a unique ID. Use String.Empty for server-side connections.

• MenuLabel This is the label that the user will see when they click on the connections submenu.

• Description This is a more detailed explanation only displayed in specific authoring environments such as FrontPage 2003.

In our Web Part, the EnsureInterfaces() looks like this:

public override void EnsureInterfaces() { try { RegisterInterface ( "EmployeeIDProvider_WPQ_", InterfaceTypes.ICellProvider, WebPart.UnlimitedConnections, ConnectionRunAt.Server, this, String.Empty, "Communicates Employee ID to", "Passes the primary key of the list" ); }



catch(SecurityException e) { } }

The result of these modifications are other labels in the menu when connecting the two Web Parts.

CanRunAt()

This method is called by the Web Part Framework to decide whether the connection needs to be implemented on the client or on the server. This has already been set in the RegisterInterface calling, but here you can manipulate this at runtime depending on the state of your Web Part.

In our example, we will not modify anything here:

public override ConnectionRunAt CanRunAt() { return ConnectionRunAt.Server; }

PartCommunicationConnect()

This method is called by the Web Part Framework immediately after the user has created a succesful connection between your Web Part and the consumer. You can write code based on the information that is coming in as arguments, decide to react to this connection and for example update your user interface.

The following arguments are provided:

• string interfaceName the friendly name of the provider interface that has been connected

• WebPart connectedPart a reference to the consumer Web Part itself

• string connectedInterfaceName the friendly name of the consumer interface that has been connected

• ConnectionRunAt runAt whether this was done on the server or on the client

For example, the user control displaying the list of employees has a label displaying the status of the Web Part. Default it is set to not connected. Using PartCommunicationConnect() procedure, we can change this label.



Here is the code:

public override void PartCommunicationConnect (string interfaceName, WebPart connectedPart, string connectedInterfaceName, ConnectionRunAt runAt) { EnsureChildControls(); uc.labelStatus.Text = "Connected"; }

PartCommunicationInit()

Provider parts can notify consumer parts that they are ready to send information to them. This is done by the provider when raising the CellProviderInit event. The place where you raise that event is in the PartCommunicationInit() procedure since this one gets executed when the framework successfully connects both parts.

You will notice that there is already some code added to this procedure. We will modify it a little bit. The provider sends the consumer the type of information it is going to send. Later in the consumer we will make use of this.

public override void PartCommunicationInit() { //If there is a listener, send init event if (CellProviderInit != null) { //Need to create the args for the CellProviderInit event CellProviderInitEventArgs cellProviderInitArgs = new CellProviderInitEventArgs(); //Set the FieldName cellProviderInitArgs.FieldName = "Employee ID"; //Fire the CellProviderInit event. //This basically tells the Consumer Web Part what type of //cell it will be receiving when CellReady is fired later. CellProviderInit(this, cellProviderInitArgs); } }



PartCommunicationMain()

This procedure gives the provider another chance to raise events to the consumer. When implementing the ICellProvider interface for example, we can raise the CellReady event notifying the consumer that we are ready and we are sending some data. Again, the template gives us the starting code. We modify the code a bit and assign the data we want to send to the consumer. In our case, this is the selected employee id exposed by the user control via the SelectedEmployeeID property.

public override void PartCommunicationMain() { //If there is a listener, send CellReady event if (CellReady != null) { //Need to create the args for the CellProviderInit event CellReadyEventArgs cellReadyArgs = new CellReadyEventArgs(); //Set the Cell to the value of the TextBox text umer //This is the value that will be sent to the Cons cellReadyArgs.Cell = this.uc.SelectedEmployeeID; //Fire the CellReady event. //The Consumer will then receive the Cell value CellReady(this, cellReadyArgs); } }

CellConsumerInit There is one last procedure in our provider part we have to consider. The CellConsumerInit is actually an event handler for an event the consumer can trigger. The consumer can for example be the boss and decide what type of field you need to send.

public void CellConsumerInit (object sender, CellConsumerInitEventArgs cellConsumerInitArgs) { }



Setting up the Consumer Connection Interface

Consider now the consumer part. It implements the ICellConsumer interface.

We have two event handlers and one event the consumer can raise.

CellProviderInit

Use this procedure to react when the provider connecting to your consumer is firing its CellProviderInit event. In our example, the provider is sending the field it is going to use for the data using this event. Let us make use of it and display it in a label in the user control.

public void CellProviderInit (object sender, CellProviderInitEventArgs cellProviderInitArgs) { this.uc.labelField.Text = cellProviderInitArgs.FieldName; }

CellReady

This is the most important procedure in the consumer since this is the place where the action occurs. The consumer receives here the data that it can use to adapt itself. Our consumer part receives the employee id with which it can update the user control.



public void CellReady(object sender, CellReadyEventArgs cellReadyArgs) { if(cellReadyArgs.Cell != null) { this.uc.SetDetails(int.Parse(cellReadyArgs.Cell.ToString())); } }

As with the provider interface, we have a couple of additional procedures to take care of.

EnsureInterfaces()

The Web Part needs to register all the interfaces it implements so that the framework can display them in the context menu. Notice how we limit the connection to only one provider.

public override void EnsureInterfaces() { try { RegisterInterface ( "EmployeeDetail_WPQ_", InterfaceTypes.ICellConsumer, WebPart.LimitOneConnection, ConnectionRunAt.Server, this, String.Empty, "Display detail for employee coming from", "Connect to this part to have details of employee listed" ); } catch(SecurityException e) { } }

CanRunAt()

This method is called by the Web Part Framework to decide whether the connection needs to be implemented on the client or on the server. This has already been set in the RegisterInterface calling, but here you can manipulate this at runtime depending on the state of your Web Part.



In our example, we will not modify anything here:

public override ConnectionRunAt CanRunAt() { return ConnectionRunAt.Server; }

PartCommunicationConnect()

Here we can add code that gets executed when our consumer gets connected. The template provides some code that is inserted here to increase an internal counter storing the amount of connections being made.

public override void PartCommunicationConnect(string interfaceName, WebPart connectedPart, string connectedInterfaceName, ConnectionRunAt runAt) { EnsureChildControls(); //Check if this is my particular cell interface if (interfaceName == "EmployeeDetail_WPQ_") { //Keep a count of the connections _cellConnectedCount++; } }

PartCommunicationInit()

This is the place where you have to raise the CellConsumerInit event. Although this is optional, it is always best to raise the event. In a lot of scenarios, it is used to tell the provider the type of data you would like to receive in the consumer.

public override void PartCommunicationInit() { //If the connection wasn't actually formed then //don't want to send Init event if(_cellConnectedCount > 0) { //If there is a listener, send init event if (CellConsumerInit != null) { //Need to create the args for //the CellConsumerInit event CellConsumerInitEventArgs cellConsumerInitArgs = new CellConsumerInitEventArgs(); //Set the FieldName cellConsumerInitArgs.FieldName = "Only employee id!"; //Fire the CellConsumerInit event. CellConsumerInit(this, cellConsumerInitArgs); } } }



There is one more procedure (GetInitEventArgs), but this one is only used when supporting transformers. We will have a look at this later.

4.5.7 Exposing Custom Properties

Web Parts come with a number of default properties. These properties can be given a value if you select the Modify My Web Part menu.

The task pane is opened and a number of properties are displayed.

It is very easy to expose your own custom properties. Developers can create properties in their Web Parts and have the task pane displaying these properties in various ways. We will start first with the simple procedure and conclude with a more complex example where we override the GetToolParts() method of the base WebPart class.



Creating a simple property

The EmployeeDetailsWP Web Part displays the table with a certain color. We can allow the user to change this color using the task pane. For this we simply have to create a property in the user control and map this property to a property of the Web Part itself.

Here is the property as it is defined in the user control:

public string TableColor { get { return headerCell.BgColor; } set { headerCell.Attributes.CssStyle.Add ("background-color", value); tableDetails.Attributes.CssStyle.Add ("border","solid 1px " + value); } }

In the Web Part we bring it to the outside:

[DefaultValue("darkblue")] public string WebPartBackgroundColor { get { this.EnsureChildControls(); return uc.TableColor; } set { this.EnsureChildControls(); uc.TableColor = value; } }

A number of attributes can be used to annotate your property. It is even obligatory to provide a default value for your property. If this is not the case, then the framework will give you an error when trying to modify the Web Part.

Here is the list of possible attributes:

• Browsable Set to False if you don’t want to display the custom property in the property pane. Also, if you set the WebPartStorage attribute to Storage.None, your property won't display in the property pane.



• Category The title of the section of the property pane that displays the custom property. If you don't specify the Category attribute, your custom property is displayed in the Miscellaneous section of the property pane. Note If you specify one of the default categories, such as Appearance, your Category attribute setting is ignored, and your property is displayed in the Miscellaneous section.

• DefaultValue The default value of the custom property. Specifying the default value minimizes the Web Part's storage requirements by storing the property's value only if it is different from the default.

• Description The contents of the ToolTip that appears when you hover over the custom property in the property pane.

• FriendlyName The caption displayed for the custom property in the property pane. If you don't specify this attribute, the actual property name will display in the property pane.

• ReadOnly Set to True if you want the custom property to be read-only in the property pane. Additionally, if your property code does not include a set accessor, your property will be read-only and setting the ReadOnly attribute is not required.

• WebPartStorage You have three possibilities here:

o Storage.AllUsers A change to the property has an effect on all the users.

o Storage.PerUser Users are allowed to modify this property and have the value saved in its own profile.

o Storage.None The custom property won’t be displayed in the property pane.

So, using additional attributes we can further customize the appearance of our property in the task pane. The display name can be better. A description can be added and we can also create our own category.

[DefaultValue("darkblue"), Description("Give here the color you like for the table."), Category("U2U"), FriendlyName("Table Color"), WebPartStorage(Storage.Personal)] public string WebPartBackgroundColor ...



Note: Because Web Part properties can be customized and are saved in the SharePoint storage system as XML, you have to do the following to support the properties you want saved (this has already been done if you make use of the Web Part template in VS.NET):

• Add a reference to the System.Xml.dll assembly to your project.

• Include the XML Serialization namespace by adding the following using directive near the top of the code: using System.Xml.Serialization;

• Add an XML namespace attribute, either at the root level of your assembly or at the property level. If you add the XML namespace at the root level, you are not required to assign XML namespaces at the property level. An XML namespace assigned at the property level will override the XML namespace assigned at the root level. The XmlRoot attribute has the following form: [XmlRoot(Namespace="name of namespace")]

SharePoint will display a specific control depending on the data type you define for your property:

• Boolean -> Check box • Enum -> Dropdown • Integer -> Text box • String -> Text box

Creating a Custom ToolPart

Instead of relying on the default property pane, you can also create your own ToolPart. We will work out a small example demonstrating the basic steps.

The Web Part

The part can of course be as complex as you would like it to be. We will create a small Web Part that simply will display a small text string inputted by the user not anymore through a custom property, but now via a custom toolpart.



Here is the Web Part code:

using System; using System.ComponentModel; using System.Web.UI; using System.Web.UI.WebControls; using System.Xml.Serialization; using Microsoft.SharePoint; using Microsoft.SharePoint.Utilities; using Microsoft.SharePoint.WebPartPages; namespace U2U.Samples.SharePoint { [DefaultProperty("Text"), ToolboxData("<{0}:SimpleText runat=server></{0}:SimpleText>"), XmlRoot(Namespace="U2U.Samples.SharePoint")] public class SimpleText : Microsoft.SharePoint.WebPartPages.WebPart { private const string defaultText = ""; private string text = defaultText; [Browsable(true),Category("Miscellaneous"), DefaultValue(defaultText), WebPartStorage(Storage.Personal), FriendlyName("Text"),Description("Text Property")] public string Text { get { return text; }



set { text = value; } } protected override void RenderWebPart(HtmlTextWriter output) { output.Write("Hello " + SPEncode.HtmlEncode(Text)); } } }

Now you are ready to transfer the text property to a custom toolpart.

Override the GetToolParts() method of the base class. The GetToolPart method returns an array of references to the ToolPart objects that will be displayed in the property pane for your Web Part.

public override ToolPart[] GetToolParts() { return base.GetToolParts ();

}

The ToolPart objects are rendered by the tool pane in the order listed in the array. This provides you with the ability to show multiple ToolParts if your Web Part requires them. Note that when you override the WebPart class’s GetToolParts method, the default ToolPart objects (WebPartToolPart and CustomPropertyToolPart) aren’t displayed automatically. You must include code to display them.

By default, the GetToolParts method will return the CustomPropertyToolPart and WebPartToolPart objects. The CustomPropertyToolPart object will display the built-in ToolPart that is shown by default for custom properties as in the previous example. If you want to display some of the custom properties for your Web Part using the built-in custom properties ToolPart, you must include a reference to the CustomPropertyToolPart object in the array of references returned by your GetToolParts method. The WebPartToolPart object will display ??? after the Web Part developer overrides this method, he has to specifically opt to show these default toolparts.

In our example, we need a custom ToolPart class displaying the just a textbox the user can fill in. For this we need to create a new ToolPart class inheriting from the Microsoft.SharePoint.SmartPages.ToolPart base class.

public class SimpleTextToolPart: ToolPart { }

A number of properties can be initialized in the constructor of the class:

public SimpleTextToolPart () { this.AllowMinimize = false; this.Title = " Enter here your name!";



this.UseDefaultStyles = true; }

The AllowMinimize property gives you the possibility to turn of the minimization of the ToolPart. Next we use the Title property to give a title to our ToolPart and we request the usage of the default style using the property UseDefaultStyles.

Since the ToolPart is by itself a ASP server control, we have to take care of the rendering of the HTML that needs to be displayed to the user.

private TextBox textBox = null; protected override void RenderToolPart(HtmlTextWriter output) { this.textBox = new TextBox(); output.Write("<B>Enter your name: </B>"); this.textBox.RenderControl(output); }

The custom ToolPart must be made available to the user via GetToolPart() method.

public override ToolPart[] GetToolParts() { ToolPart[] toolparts = new ToolPart[3]; WebPartToolPart wptp = new WebPartToolPart(); CustomPropertyToolPart custom = new CustomPropertyToolPart(); toolparts[0] = custom; toolparts[1] = wptp; // This is the custom ToolPart. toolparts[2] = new SimpleTextToolPart(); return toolparts; }

In addition to the two default ToolParts, the WebPartToolPart and the CustomPropertyToolPart, we are going to expose also our SimpleTextToolPart by adding an object of the class into the array that is returned by this method.

Override the ApplyChanges Method

As its name implies, the ApplyChanges method applies the changes made in your tool part back to the Web Part it is associated with. Because ApplyChanges is a virtual method, you must override it to implement it in your tool part. The ApplyChanges method is called when the user clicks OK or Apply in the property pane. This is where you send the value of any updated properties back to the Web Part.

To obtain a reference to the Web Part to update its properties, the ToolPart class has an accessor property called ParentToolPane that returns a reference to the ToolPane object. The ToolPane object is the class that keeps track of which Web Part is selected, and in turn, it has an accessor property called SelectedWebPart that returns a WebPart object for the current Web Part.

public override void ApplyChanges() { SimpleText wp1 = (SimpleText)this.ParentToolPane.SelectedWebPart;



// Send the custom text to the Web Part. wp1.Text = this.textBox.Text; }

Time to test the Web Part and the custom ToolPart. Together with the default ToolPart, you will see now your custom ToolPart appearing in the task pane.


On-site U2U coursesSpecial Package

Group pricefor 10 students

5000 € for 5 days

What is included in the price of 5000 €?

• The price includes the organization of 5 training days on-sitein your class rooms.

• The number of students that participate to the course isNOT limited.

• All courseware is included for 10 participants: • 10 course books, 500 pages each • 10 CD’s with course slides in PDF format, course samples

and lab solutions • Course can be given in English, Dutch or French. • Indicative course hours 9:00 – 17:00 • No extra cost will be charged for travel expenses.

The travel and eventual hotel cost for the trainer are included inthe price. This offer is valid for on-site courses in Europe.For Middle-East and Africa, please contact us for an exact costcalculation.

What is NOT included in the price of 5000 €?

• Training room with individual pc’s, pc projector, white board isnot included in the price.Each pc should be installed with Microsoft Visual Studio.NET

• If requested we can install the U2U mobile classroom withSiemens portables and Sony Beamer.

• Lunches, coffee and beverages for the participants. • The number of participants to the course is NOT limited.

But only 10 student kits are included in the price.Extra student kits (book and CD) can be ordered at 75 € per kit.

Conditions

This offer is valid for all U2U courses with code UVBNE, UCSPR,UNOOP, UNETA and UNETE that are organized on-site before31/12/2003. For other courses, please contact us for an exactcost calculation.Prices are listed in EURO and do not include VAT. There is no VAT charged for VAT

registered companies in the European Union other than Belgium. VAT will not be

charged for companies outside the European Union.

On-site U2U Courses

U2U is specialized in the organization of on-site courses through-out whole EMEA (Europe, Middle East and Africa). And for thecoming months, we would like to offer you a special on-site packagevalid for the five .NET courses that are listed here below. The pack-age includes the organization of a 5-day course at your site and allthe courseware for 10 participants. The special price of the packageis only 5000 €, including the travel expenses of the trainer.A simple calculation reveals that this special package brings yourtraining cost per student per day back to 100 €.

The U2U trainer

The U2U trainer has an academic Master degree inScience, is certified as Microsoft Certified SolutionDeveloper and is Microsoft Certified Trainer. Theprofile of the trainer can be obtained at forehand.

U2U nv/saTechnologiestraat 1 • B-1082 BRUSSELS

✆ + 32 2 466 00 16 • 2 + 32 2 466 67 71: http://www.u2u.net • + [email protected]

Courses on demandAt least as important as our scheduled courses are our customizedcourses. As we noticed that a growing number of companiesprefers on-demand training, U2U offers the following formula:

What you want: customizationThe content of the courses can be fully adjusted to your particularneeds. To use your time optimally and to make the most of the course,you can choose which topics you want to integrate in the course. Youfind the contents of our courses on the U2U website. After you havemade your selection, we propose a duration and period for the request-ed course and include our offer. The content of the course will be drawnup beforehand in close cooperation with you. We guarantee the qualityof the course as we only employ experienced and flexible professionalinstructors who can adapt themselves to the demand and requirementsof individual course participants. Contact us today and request yourfree offer.

Where you want: our mobile classroomU2U takes pride in its flexibility: we do not only teach you what you want,but even where you want. Our classrooms in Brussels are at your dis-posal, but we can also organize courses on-site. We offer courses inDutch, French and English. In addition to our scheduled courses, weorganize courses on demand at our training center or even on-sitethroughout whole Europe, Middle East and Africa. It is easy for us toinstall our mobile pc-class (Siemens portables and XGA-beamer) in youroffice or in a seminar center near you. Upon your request we will pres-ent you a personalized offer.

Above all, U2U is a Competence Center for Software Developers.

But U2U is also an official Microsoft Partner and a Microsoft Certified Technical Education Center.

And that’s not the end of the story; there’s more to it. The numerous Microsoft official trainings we offer

are only the tip of the iceberg, and fit in with a larger aspiration. As a competence center, we first of all

want to be the epicenter of pioneering work in software development. Furthermore, U2U is a meeting

place for developers who want to keep track of the latest technologies. At U2U, you’ll find the solutions

to your development problems of today, and you’ll prepare for tomorrow.

Group pricefor 10 students

5000 € for 5 days

U2U Calendar July 2003 - December 2003U2U nv/sa - Technologiestraat 1 - 1082 Brussels - BELGIUM ✆ +32 2 466 00 16 Fax + 32 2 466 67 71 : www.u2u.net + [email protected]

Course hours: First day of course 9:30-17:00, next days: 9:15-17:00. Course hours MSDN hands-on evening sessions 18:00-21:00.Prices listed in Euro, 21% VAT not included.

Group discounts: 10% second person, 20% from third person

Conditions group discounts see www.u2u.net. Cancellations up to 8 days before the course or seminar are at no charge. Cancellations after this date, as well as no-shows, will be liable for the full registration fee.Substitutions may be made at any time by providing U2U with written notice of the names of both the original and substitute registrant. Please send cancellation and/or substitution information by e-mail

([email protected]) or to: U2U nv/sa, Technologiestraat 1, 1082 Brussels, Belgium, or fax to +32 2 466 67 71.

Book a U2U calendar course a month and a half in advance, and get a discount of 10%

Microsoft SQL Server 2000 Development Price Days Jul Aug Sep Oct Nov DecMS2071 Querying SQL Server 2000 with Transact-SQL 640 € 2 days 21 2 1MS2072 Administering a Microsoft SQL Server 2000 Database 1600 € 5 days 6MS2723 Microsoft SQL Server 2000 for Experienced Database Professionals 960 € 3 days 14 22 24MS2591 Implementing Replication Using Microsoft SQL Server 2000 960 € 3 days 16 24 26MS2073 Programming a Microsoft SQL Server 2000 Database 1600 € 5 days 22 1MS2074 Designing and Implementing OLAP Solutions with Microsoft SQL Server 2000 1600 € 5 days 13 1MS2092 Populating a Data Warehouse with Microsoft SQL Server 2000 Data Transformation Services 1600 € 5 days 21MS2093 Implement Business Solutions with MDX in MS SQL Server 2000 960 € 3 days 12MS2091 Building XML-Enabled Applications Using Microsoft SQL Server 2000 960 € 3 days 29 22Development with .NET Enterprise Servers Price Days Jul Aug Sep Oct Nov DecWindows Server 2003UWSPR Programming the Microsoft .NET Servers 1600 € 5 days 18 13 1MS2281 Designing a Microsoft Windows .NET Directory Services Infrastructure 640 € 2 days 28 24MS2279 Planning and implementing MS Windows Server 2003 Active Directory Infrastructure 1600 € 5 days 24MS2274 Managing a Microsoft Windows Server 2003 Environment 1600 € 5 days 25 27MS2275 Maintaining a Microsoft Windows Server 2003 Environment 960 € 3 days 15 3MS2821 Designing and Managing a Public Key Infrastructure 960 € 3 days 8 17MS2830 Designing Security for Microsoft Networks 960 € 3 days 10 19MS2433 Microsoft Visual Basic Scripting Edition and Microsoft Windows Script Host Essentials 960 € 3 days 20MS2439 Scripting Microsoft Windows Management Instrumentation 640 € 2 days 23SharePoint, BizTalk, CommerceUSPPS Building Solutions for Microsoft SharePoint 2003 Products and Technologies 1600 € 5 days 25 6 8UOFS3 Developing Microsoft Office 2003 Solutions 1600 € 5 days 8 17MS2095 Implementing Microsoft SharePoint Portal Server 2001 960 € 3 daysMS2380 Developing Collaborative Solutions using Microsoft Office XP Developer 1600 € 5 days 13MS2728 Building Microsoft BizTalk Server 2002 Solutions 1280 € 4 days 2 4MS2729 Building Microsoft Commerce Server 2002 Solutions 1280 € 4 days 20MS2730 Building Microsoft Content Management Server 2002 Solutions 1280 € 4 days 8 15MS2382 Building Corporate Portals using Digital Dashboards 960 € 3 days 12Introductory courses Price Days Jul Aug Sep Oct Nov DecMS2667 Introduction to Programming 960 € 3 days 2 12 22UXHTM XHTML Essentials 640 € 2 daysUWDDE DHTML Essentials 960 € 3 daysUCLAN The C Language Essentials 1100 € 3 days 2 29UCPPC C++ Essentials for C Programmers 1600 € 5 days 3Microsoft Visual Studio 6.0 Price Days Jul Aug Sep Oct Nov DecVisual Basic 6.0 ProgrammingMS1303 VB6 Language and GUI Essentials 1600 € 5 days 8 13 1MS1013 VB6 Development : ADO Essentials and COM(COMBI) 1600 € 5 days 22 3 15MS1907 VB6 Enterprise : ADO Advanced and MTS/COM+ 1600 € 5 days 20MS1301 Mastering Visual Basic for Applications for building MS Office 2000 Solutions 1100 € 3 days 1Visual C++ 6.0 ProgrammingMS1011+1015 VC++6 : Microsoft Foundation Classes(COMBI) 2000 € 5 days 8 15MS1304+1595 VC++6 : COM Essentials using ATL and ADO(COMBI) 2200 € 5 days 17ASP ProgrammingMS1905 Building Web Applications using ASP and XML 1200 € 4 days 15 24MS1913 Exchanging and Manipulating Data Using XML and XSLT 1200 € 4 days 6 8Windows DNA 2000 DesignMS1607 Windows DNA and COM+ Overview 320 € 1 day 20MS1934 Modeling Windows DNA-based Applications with Rational Rose 1200 € 3 days 21MS1910 Designing and Implementing Distributed Applications on Windows 2000 1800 € 5 days 24MS1609 Designing Data Services and Data Models 960 € 3 days 8 22

Get Ready for .NET Price Days Jul Aug Sep Oct Nov DecIntroduction to .NET ProgrammingMS2717 Introduction to .NET Development 640 € 2 days 2 3 9MS2559 Introduction to Visual Basic .NET Programming with Microsoft .NET 1600 € 5 days 25 29 3 1MS2609 Introduction to C# Programming with Microsoft .NET 1600 € 5 days 8 13 24Object-Oriented Programming in .NETUVBNE Object-Oriented Programming in VB.NET 1600 € 5 days 4 15 27 8MS2373 Programming with Visual Basic .NET (for VB6 programmers) 1600 € 5 days 15 27 8UCSPR Object-Oriented Programming with C# 1600 € 5 days 4 1 13 1MS2124 Programming with C# 1600 € 5 days 1 13 1UCSJV C# Language Essentials (Accelerated) 640 € 2 days 1 20 8Windows and Web Programming in .NETUNETA Building Windows and Web Applications in .NET 1600 € 5 days 18 22 3 15MS2727 Developer Skills Builder for Microsoft .NET and VB.NET 3200 € 10 days 15 27 8MS2565 Developing .NET Applications for Windows with VB.NET 1600 € 5 days 8 17MS2555 Developing .NET Applications for Windows with C# 1600 € 5 days 8 17MS2571 Application Upgrade and Interoperability Using VB.NET 640 € 2 days 4 5 11ASP.NET and XML.NETMS2500 Introduction to XML and the Microsoft .NET Platform 640 € 2 days 15 24MS2663 Programming with XML in the Microsoft .NET Framework 960 € 3 days 17 26MS2310 Developing Web Apps Using Visual Studio.NET and ASP.NET 1600 € 5 days 15 27 24MS2640 Upgrading Web Development Skills from ASP to Microsoft ASP.NET 960 € 3 days 1 12Become an Expert in .NET Price Days Jul Aug Sep Oct Nov DecObject-Oriented Pattern Programming in .NETUNOOP Intensive Object-Oriented Programming in .NET 1600 € 5 days 7 1 20 8MS2415 Programming the Microsoft .NET Framework with Visual Basic .NET 1600 € 5 days 1 20 8MS2349 Programming the Microsoft .NET Framework with C# 1600 € 5 days 1 20 8UNUML UML for .NET Programmers 640 € 2 days 22 20.NET FrameworkUNETE Programming .NET Enterprise Applications 1600 € 5 days 14 29 17MS2389 Programming with Microsoft ADO.NET 960 € 3 days 10 19MS2524 Developing XML Web Services Using Microsoft ASP.NET 960 € 3 days 4 6 15MS2557 Building COM+ Applications using Microsoft .NET Enterprise Services 1600 € 5 days 6MS2805 Security Seminar for Developers 400 € 1 day 29 8MS2350 Developing and Deploying Secure Microsoft .NET Framework Applications 960 € 3 days 29 8MS2300 Developing Secure Web Applications 960 € 3 days 8 1 10UNETX Microsoft .NET System Programming 1600 € 5 days 3.NET Compact FrameworkMS2556 Developing Smart Device Applications with the .NET Compact Framework 1600 € 5 days 22 15MS2514 Developing Mobile Web Applications with Microsoft Mobile Internet Toolkit 960 € 3 days 12 22C++.NETMS2558 Programming with Managed Extensions for Microsoft Visual C++.NET 1200 € 3 days 8 29 3Get Certified for .NET Price Days Jul Aug Sep Oct Nov DecMCSD1 MCAD and MCSD.NET Core Exam 1 and 2 Training 3260 € 8 days 8 8 17MCSD2 MCAD and MCSD.NET Core Exam 3 Training 1950 € 5 days 4 6 15MS2710 MCSD.NET Core Exam 4 Training:.NET Solution Architectures 1285 € 3 days 19 12MS2073 MCSD Elective Exam Training: Programming a MS SQL Server 2000 1950 € 5 days 22 1Microsoft .NET Architecture and Design Price Days Jul Aug Sep Oct Nov DecMS2710 Analyzing Requirements and Defining Microsoft .NET Solution Architectures 960 € 3 days 19 12MS2090 Create a Database Using Microsoft Visual Studio .NET Enterprise Architect 960 € 3 days 3MS2390 Developing Disconnected Database Solutions Using Microsoft VS.NET 640 € 2 days 5MS2260 Designing E-Business Applications with Microsoft .NET Enterprise Servers 960 € 3 daysMS2420 Designing B2B Integration Solutions 960 € 3 days 12MS2088 Designing a Highly Available Web Infrastructure 1280 € 4 days 7

Documents

4. Building Web Parts - DotNetSpider...U2U trains over a thousand software developers a year in .NET U2U specializes in .NET Solution Development, is Microsoft Certified Technical