Develop and Customize Web Parts with Custom Tool Parts

Introduction

<!–
OAS_AD(‘flex’);
//–>

<!–
var TFSMFlash_VERSION=6;
var TFSMFlash_WMODE=”window”;
var TFSMFlash_OASCLICK=”http://mjxads.internet.com/RealMedia/ads/click_lx.ads/intm/webdev/www.15seconds.com/focus/component/1478728526/flex/OasDefault/Sophos_WC_GEMS_1bc/webcast_8_21_8_bob.html/37616134306631373438306630306330&#8243;;
var TFSMFlash_SWFCLICKVARIABLE=”?clickTAG=http://mjxads.internet.com/RealMedia/ads/click_lx.ads/intm/webdev/www.15seconds.com/focus/component/1478728526/flex/OasDefault/Sophos_WC_GEMS_1bc/webcast_8_21_8_bob.html/37616134306631373438306630306330?”;
var TFSMFlash_SWFFILE=”http://mjxads.internet.com/RealMedia/ads/Creatives/OasDefault/Sophos_WC_GEMS_1bc/webcast_8_21_8_bob.swf”+TFSMFlash_SWFCLICKVARIABLE;
var TFSMFlash_IMAGEALTERNATE=”http://mjxads.internet.com/RealMedia/ads/Creatives/OasDefault/Sophos_WC_GEMS_1bc/webcast_8_21_8_bob.gif&#8221;;
var TFSMFlash_OASALTTEXT=”Click Here”;
var TFSMFlash_OASTARGET=”_blank”;
var TFSMFlash_OASPROTOCOL=”http://&#8221;;
var TFSMFlash_OASDIM=”WIDTH=’336′ HEIGHT=’280′”;
var TFSMFlash_OASADID=”ad_banner”;

document.write(‘<scr’+’ipt src=”http://mjxads.internet.com/RealMedia/ads/Creatives/OasDefault/Sophos_WC_GEMS_1bc/TFSMFlashWrapper201.js”></scr’+’ipt>&#8217;);
–>
<a href=”http://mjxads.internet.com/RealMedia/ads/click_lx.ads/intm/webdev/www.15seconds.com/focus/component/1478728526/flex/OasDefault/Sophos_WC_GEMS_1bc/webcast_8_21_8_bob.html/37616134306631373438306630306330?&#8221; target=”_blank”><img src=”http://mjxads.internet.com/RealMedia/ads/Creatives/OasDefault/Sophos_WC_GEMS_1bc/webcast_8_21_8_bob.gif&#8221; width=336 height=280 alt=”Click Here” border=0></a> <a href=”http://63.236.18.118/RealMedia/ads/click_nx.ads/intm/webdev/www.15seconds.com@468×60-1,468×60-2,house_ribbon,ciu,flex,accessunit,accessunit_one,accessunit_two,accessunit_three,cp1,cp2,cp3,cp4,cp5,cp6,cp7,cp8,cp9,cp10,cp11,cp12,cp13,marketplace01,marketplace02,marketplace03,marketplace04,marketplace05,marketplace06,marketplace07,marketplace08,marketplace09,marketplace10!flex”><img src=”http://63.236.18.118/RealMedia/ads/adstream_nx.ads/intm/webdev/www.15seconds.com@468×60-1,468×60-2,house_ribbon,ciu,flex,accessunit,accessunit_one,accessunit_two,accessunit_three,cp1,cp2,cp3,cp4,cp5,cp6,cp7,cp8,cp9,cp10,cp11,cp12,cp13,marketplace01,marketplace02,marketplace03,marketplace04,marketplace05,marketplace06,marketplace07,marketplace08,marketplace09,marketplace10!flex&#8221; border=”0″ alt=”flex”></a>
<!–
OAS_AD(‘accessunit’);
//–>

function popWin(url){
spawn = window.open(url,’newWin’,’width=800,height=600,top=0,left=0,location=yes,toolbar=yes,status=true,scrollbars=yes,resizable=yes,fullscreen=no,menubar=no,directories=no’);
spawn.focus();
}
Turbo Screen Sharing
Adobe Acrobat Connect Professional offers users the ability to have a more productive and engaging web conferencing experience while providing the IT department with a program that efficiently utilizes bandwidth and minimally impacts the infrastructure. Learn More! »

Informal Learning: Extending the Impact of Enterprise Ideas and Information
Forward-thinking organizations are turning to enterprise learning in their quest to be better informed, better skilled, better supported at the point of need, and more competitive in their respective marketplaces. Learn More! »

Rapid E-Learning: Maturing Technology Brings Balance and Possibilities
Rapid e-learning addresses both time and cost issues by using technology tools to shift the dynamics of e-learning development. Learn why more skilled learning professionals use these tools and how you can get a solution to keep pace with your business demands. »

Delivering on the Promise of ELearning
This white paper defines the framework to launch e-learning as a set of teaching, training, and learning practices not bound by a specific technology platform or learning management system. It offers practical suggestions for creating digital learning experiences that engage learners by building interest and motivation and providing opportunities for active participation. »

<a href=”http://63.236.18.118/RealMedia/ads/click_nx.ads/intm/webdev/www.15seconds.com@468×60-1,468×60-2,house_ribbon,ciu,flex,accessunit,accessunit_one,accessunit_two,accessunit_three,cp1,cp2,cp3,cp4,cp5,cp6,cp7,cp8,cp9,cp10,cp11,cp12,cp13,marketplace01,marketplace02,marketplace03,marketplace04,marketplace05,marketplace06,marketplace07,marketplace08,marketplace09,marketplace10!accessunit”><img src=”http://63.236.18.118/RealMedia/ads/adstream_nx.ads/intm/webdev/www.15seconds.com@468×60-1,468×60-2,house_ribbon,ciu,flex,accessunit,accessunit_one,accessunit_two,accessunit_three,cp1,cp2,cp3,cp4,cp5,cp6,cp7,cp8,cp9,cp10,cp11,cp12,cp13,marketplace01,marketplace02,marketplace03,marketplace04,marketplace05,marketplace06,marketplace07,marketplace08,marketplace09,marketplace10!accessunit&#8221; border=”0″ alt=”accessunit”></a>

There are several ways a developer can introduce customization to a SharePoint Web Part. The default properties and custom properties developers create are available in the default property pane, making their use transparent to the user. If the default property pane functionality is not rich enough, developers can create a custom user interface called a Tool Part. This adds a sophisticated interface for manipulating the appearance and functionality of the custom property. Tool Parts provide an interface for Web Part properties well beyond the capabilities of the default property pane.

The GetToolParts Method

To add custom Tool Parts to the property pane of the Web Part, the developer must overwrite the GetToolParts method in the Web Part base class. The GetToolParts method returns an array of references to the ToolPart objects that will be included in the property pane for the Web Part. The ToolPart objects are rendered according to the order in the array. There are two standard ToolPart objects: the WebPartToolPart and CustomPropertyToolPart normally render at runtime by default. If the developer overwrites the GetToolParts method with the custom Tool Part, the standard ToolPart objects should manually be added back to the array of references.

The CustomPropertyToolPart Object

This object displays the custom properties developed for the Web Part. The developer has to include a reference to the CustomPropertyToolPart object in the array of references returned by the GetToolParts method.

The WebPartToolPart Object

This object will display all the base class properties of the Web Part.The Visual Studio .NET environment supports the development of Web Parts for SharePoint Portal Server. The Web Part Template provided on MSDN (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odc_sp2003_ta/html/sharepoint_webparttemplates.asp) provides an excellent starting point for the structure of GetToolParts method and template of a custom Tool Part class.

///<summary>

///Gets the custom tool parts for this Web Part by overriding the

///GetToolParts method of the WebPart base class. You must

implement

///custom tool parts in a separate class that derives from

///Microsoft.SharePoint.WebPartPages.ToolPart.

///</summary>

///<returns>An array of references to ToolPart objects.</returns>

//public override ToolPart[] GetToolParts()

//{

// ToolPart[] toolparts = new ToolPart[2];

// WebPartToolPart wptp = new WebPartToolPart();

// CustomPropertyToolPart custom = new CustomPropertyToolPart();

// toolparts[0] = wptp;

// toolparts[1] = custom;

// return toolparts;

//}

Figure 1: The GetToolParts method available by default in the Web Part template.

As you can see, the GetToolParts method appears fully commented without having any impact on the Web Part. The default ToolPart objects, WebPartToolPart and CustomPropertyToolPart are displayed automatically.

It is important to understand how to develop custom Web Parts before commencing any coding. Please refer to the article “Developing Web Parts for SharePoint 2003 in VS.NET” for more information regarding developing Web Parts (http://www.devx.com/dotnet/Article/17518).

Code Example

In this example, a simple Tool Part class will be created that exposes a Web Part property. The custom Tool Part will display in the default property pane. The user will be able to update the Web Part property through the custom Tool Part.It is a two step process to develop a custom Tool Part.

  1. Create the custom Tool Part class
  2. Add a GetToolParts method to the Web Part class

1. Create the custom Tool Part class.

First create a Web Part Library solution using the Web Part Library template.

Figure 2: Web Part Library project available from the template.

This will create a Web Part class. In the Web Part class then create a custom property. Please refer to the article “Create Custom Properties for a Web Part” (http://www.15seconds.com/issue/040219.htm).

An example of a simple string custom property where you can enter a string value is displayed below,

///<summary>

/// This property will get and set a string value as a customer name

/// This will be available in a text box.

///</summary>

[Browsable(false),//Display the property in property pane

Category(“CustomToolPartEx1”),//Create a Customer Details category in property pane

DefaultValue(“”),//Assign a default value

WebPartStorage(Storage.Personal),//Make available in both personal and shared mode

FriendlyName(“Customer Name”),//The caption display in property pane

Description(“The name of the customer”)]//The tool tip

publicstring CustomerName

{

get

{

return strCustomerName;

}

set

{

strCustomerName = value;

}

}

Figure 3: Custom property created in the Web Part.

Next you need to add a new Tool Part class to the Web Part project. In Solution Explorer, right click on the project file, select Add and click Add New Item. Select the Tool Part template as displayed below. Provide a name for the Tool Part template and click Open.

Figure 4: Selecting the Tool Part template.

Make sure the namespace of the both Web Part class and Tool Part class are the same for easy access. The Tool Part class will display as follows:

Figure 5: Tool Part class and namespace.

The CustomToolPart1 class inherits from ToolPart class using the Microsoft.SharePoint.WebPartPages namespace.

To display the Web Part custom property value in Tool Part class, the code to the RenderToolPart method in the Tool Part class must be added. This method renders the Tool Part to the Web page.

To obtain a reference to the Web Part to access or modify the properties, the ToolPart class has an accessor property called ParentToolPane that returns a reference to the ToolPane object. The ToolPane object class determines which Web Part is selected by an accessor property called SelectedWebPart.

The following example demonstrates how to simply create an HTML input control and assign the Web Part custom property value to it.

///<summary>

/// Render this Tool part to the output parameter specified.

///</summary>

///<param name=”output”> The HTML writer to write out to ///</param>

protectedoverridevoid RenderToolPart(HtmlTextWriter output)

{

// Establish a reference to the Web Part.

// CustomWebPart is the web part class name.

CustomWebPart customWebPartEx1 =

(CustomWebPart)this.ParentToolPane.SelectedWebPart;

//Create the input control

output.Write(“Enter the customer name: “);

output.Write(“<input name= ‘” + strHTMLinputControlName);

//Assign the web part custom property value to the input

//control.

output.Write(“‘ type=’text’ value='” +

SPEncode.HtmlEncode(customWebPartEx1.CustomerName) + “‘>

<br>”);

}

Figure 6: RenderToolPart method in Tool Part class.

Overwrite the ApplyChanges Method

This method applies the changes made in the Tool Part back to the associated Web Part. ApplyChanges is a virtual method the developer needs to override inside the Tool Part. This method will be called when the user clicks OK or Apply in the default property pane.

///<summary>

///Called by the tool pane to apply property changes to the selected Web Part.

///</summary>

publicoverridevoid ApplyChanges()

{

// apply property values here

//Get a reference to the web part class

CustomWebPart cw1 =

(CustomWebPart)this.ParentToolPane.SelectedWebPart ;

//Pass the custom text to web part custom property

cw1.CustomerName = Page.Request.Form[strHTMLinputControlName];

}

Figure 7: ApplyChanges method in Tool Part class.

CustomWebPart is the Web Part class name. A reference is obtained for the Web Part using this.ParentToolPane.SelectedWebPart. The custom text is then passed back to the Web Part custom property.

2) Add a GetToolParts method to the Web Part class

Navigate back to the Web Part class and remove the comments around the GetToolParts method provided by the template. Now include the new Tool Part object to the ToolPart object array as displayed below.

///<summary>

///Gets the custom tool parts for this Web Part by overriding the

///GetToolParts method of the WebPart base class. You must ///implement custom tool parts in a separate class that derives from

///Microsoft.SharePoint.WebPartPages.ToolPart.

///</summary>

///<returns>An array of references to ToolPart objects.</returns>

publicoverride ToolPart[] GetToolParts()

{

ToolPart[] toolparts = new ToolPart[3];

//WebPartToolPart Object

WebPartToolPart wptp = new WebPartToolPart();

//CustomPropertyToolPart Object

CustomPropertyToolPart custom = new CustomPropertyToolPart();

toolparts[0] = custom; //Add CustomPropertyToolPart object to

the ToolParts array

toolparts[1] = wptp;//Add WebPartToolPart object to the

ToolParts array

toolparts[2] = new CustomWebPartEx1.CustomToolPart1();//Add

custom tool part object to the ToolParts array

return toolparts;

}

Figure 8: GetToolParts method in Web Part class.

The method contains an array of ToolPart objects. Because this method is being overwritten, the WebPartToolPart and CustomPropertyToolPart object need to be added manually to the ToolPart object array. Then the custom Tool Part is added to the ToolPart array object.

Perform the necessary step to deploy the Web Part to the SharePoint page. Please refer to the article “Developing Web Parts for SharePoint 2003 in VS.NET” for more information regarding deploying Web Parts. (http://www.devx.com/dotnet/Article/17518)

Figure 9: Upload the Web Part.

The following Web Part will display in the Web page.

Figure 10: The Custom Web Part.

Navigate to the default property pane. A new category called “Custom Tool Part Ex1” is created in the property pane. The category name is provided in the Tool Part class constructor as displayed below.

///<summary>

/// Constructor for the class. A great place to set default values for

/// additional base class properties here.

///<summary>

public CustomToolPart1()

{

//The category name that will display in the default property

pane

this.Title = “Custom Tool Part Ex1”;

this.Init += new EventHandler(CustomToolPart1Init);

}

Figure 11: Assigning the category name in the default property pane.

TIP: To access the property pane, select the Edit mode of the Web Part. Then click the down arrow located at top right hand corner of the Web Part. Select “Modify Shared Web Part” (or personnel depend on which mode the Web Part is running).

Figure 12: The Custom Tool Part class we created in property pane.

The default property pane includes the custom Tool Part class created. Now simply enter a customer name and click Ok. The string value entered will display in the Web Part as illustrated below.

Figure 13: The updated Web Part through Tool Part.

Conclusion

Developers can use the Tool Part class to add much more sophisticated functionality to the property pane. For example, imagine an application where the user needs to select a list of columns names to be displayed in a DataGrid in a Web Part. The developer can create a Tool Part class that displays a collection of available columns in a grid. This grid will appear in the default property pane. When the user selects the columns and clicks Ok in the property pane, the column values are passed onto the Web Part to display the DataGrid in the Web Part. This way, the user can customize the DataGrid behaviour in the Web Part through the property pane.

Advertisements

5 Responses to Develop and Customize Web Parts with Custom Tool Parts

  1. Wow, excellent info. This blog is really cool. I bookmarked this and will return once again.

  2. anaymous says:

    looking for starting my career with share point development as since presently working as php developer .so when i go up with web development it will be good for me to proceed up with.just guide me what module i can learn in bangalore and which is suitable for me to go up with for just enetring into mnc as share point developer

  3. buyitfromme says:

    buyitfromme…

    […]Develop and Customize Web Parts with Custom Tool Parts « Sharepoint Musing’s[…]…

  4. north carolina insurance…

    Develop and Customize Web Parts with Custom Tool Parts « Sharepoint Musing’s…

  5. Learn More says:

    It’s the best time to make some plans for the future and it is time to be happy. I have read this post and if I could I want to suggest you few interesting things or advice. Perhaps you can write next articles referring to this article. I want to read more things about it!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: