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.
- Create the custom Tool Part class
- 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.
