创建带 Custom Tool Part的Web Part
Creating a Web Part with a Custom Tool Part
Written by: Rickie Lee (rickieleemail＠yahoo.com)
Jan. 1, 2005
你可以使用custom tool part来为web part的属性创建custom user interface，custom tool part可以很好超出缺省属性面板的特性。
创建custom tool part并与web part关联需要完成如下2个步骤：
1. 在Web Part class中增加GetToolParts方法（Web Part template提供了一个注释的示例代码）
在Web Part class中重载WebPart基类的GetToolParts方法，GetToolParts方法返回引用新ToolPart对象的数组，新ToolPart对象将以在数组中的顺序显示在Web Part的属性面板中。如果Web Part需要，你可以显示多个ToolParts。需要注意的是，当你重载WebPart类的GetToolParts方法时，缺省的ToolPart对象（WebPartToolPart和CustomPropertyToolPart）不能自动显示，因此你必须包含显示它们的代码。
缺省情况下，GetToolParts方法将返回CustomPropertyToolPart和WebPartToolPart对象。CustomPropertyToolPart对象将显示内置的tool part，这些tool part用来显示定制属性（custom properties）。如果你想通过使用内置的tool part来显示一些web part的定制属性，你必须在GetToolParts方法的返回数组包含对CustomPropertyToolPart对象的引用。WebPartToolPart对象将显示Web Part所有基类属性。在Web Part开发人员重载该方法后，他不得不明确显示这些缺省tool parts。
你可以在Web Part template中找到如下示例代码，该代码演示GetToolParts方法如何缺省实现。
/// <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] = custom;
// toolparts[1] = wptp;
// return toolparts;
//}
(1) 简单的字符串定制属性示例
///<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;
}
}
(2) 增加custom tool part对象后的GetToolParts方法：
/// <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[3];
WebPartToolPart wptp = new WebPartToolPart();
CustomPropertyToolPart custom = new CustomPropertyToolPart();
toolparts[0] = custom;
toolparts[1] = wptp;
// This is the custom ToolPart.
toolparts[2] = new CustomToolPart1 ();
return toolparts;
}
2. 创建custom tool part class
在Web Part class中重载GetToolParts方法后，你需要为custom tool part创建一个单独的class：
第一步是增加一个新的Tool Part class
public class CustomToolPart1: Microsoft.SharePoint.WebPartPages.ToolPart
第二步是重载ApplyChanges方法
ApplyChanges方法应用custom tool part中的改变到关联的Web Part中，因为ApplyChanges是一个虚方法，因此你必须要重载并实现它。在用户点击属性面板上的OK或Apply按钮时，调用ApplyChanges方法，通过ApplyChanges方法传送更新的属性值到对应的Web Part。
为了获取要更新Web Part属性值的引用，ToolPart class有一个明为ParentToolPane的存取属性，该属性返回ToolPane对象的引用。ToolPane对象保持当前选中Web Part的引用，SelectedWebPart对象返回当前Web Part对象。也就是可以通过ParentToolPane.SelectedWebPart属性来获取当前选择的Web Part。
如下是ApplyChanges方法的重载代码，这里假设Web Part class为CustomWebPart：
该方法将输入的文本字符串内容返回到关联的Web Part
///<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];
}
重载custom tool part的RenderToolPart方法：
如下的代码演示如何创建一个HTML输入控件，并将Web Part的定制属性值赋予给该控件
///<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>");
}
在SPS属性面板的界面如下所示：
References:
1. Microsoft SharePoint Products and Technologies 2003 Software Development Kit
2. Gayan Peiris, Develop and Customize Web Parts with Custom Tool Parts, http://www.15seconds.com/issue/040427.htm