Custom Tool Parts


Custom Tool Parts

Throughout your investigation of web parts, you have used properties to configure the parts within SPS. The web parts you have created have supported fundamental types such as String and Boolean . The tool pane in SPS automatically creates the appropriate user interface element ”called a tool part ”for these basic properties in the tool pane. For example, the tool pane uses a text box tool part for String properties and a checkbox tool part for Boolean properties.

There may be times, however, when you may want to create more complex properties. In these cases, you may need to create your own custom tool parts to allow the end user to set the properties of your web part. These custom tool parts allow you significant control over how your web parts are configured.

Default Tool Parts

As we have seen, every web part uses tool parts. By default, the web part infrastructure defines two types of tool parts that are associated with every web part: the WebPartToolPart object and the CustomPropertyToolPart object.

The WebPartToolPart object renders all of the properties associated with the WebPart base class. The WebPart base class includes fundamental properties such as Title and Name . This functionality is handled automatically by the base class and the web part infrastructure.

Whenever you create a custom property based on supported types such as String , Integer , and Boolean , the web part infrastructure creates the tool parts for these properties using the CustomPropertyToolPart object. As with the base class properties, the functionality to implement these tool parts is handled automatically by the web part infrastructure. Up to this point, these interactions have been invisible to your web parts.

The WebPart base class is responsible for providing a WebPartToolPart and CustomPropertyToolPart to the web part infrastructure. The WebPart base class creates these objects and sends them to the web part infrastructure when the GetToolParts method is called. Although previously you have never had to write this code, Listing 7-9 shows what the code would look like if you did have to write it.

Listing 7-9: The Default Implementation of GetToolParts
start example
 Public Overrides Function GetToolParts() As ToolPart()     Dim toolParts(1) As ToolPart     Dim objWebToolPart As WebPartToolPart = New WebPartToolPart     Dim objCustomProperty As CustomPropertyToolPart = New CustomPropertyToolPart     toolParts(0) = objWebToolPart     toolParts(1) = objCustomProperty     Return toolParts End Function 
end example
 

In order to create a custom tool part, you must override the default implementation of GetToolParts and add your own part to the set of tool parts passed to the web part infrastructure. When you create your own tool part, you create a new class that inherits from the ToolPart class. Inheriting from the ToolPart class allows you to add the new tool part to the set. Listing 7-10 shows how the GetToolParts method would appear if you added a new tool part based on a custom class named Tool .

Listing 7-10: Overriding the GetToolParts Method
start example
 Public Overrides Function GetToolParts() As ToolPart()     Dim toolParts(2) As ToolPart     Dim objWebToolPart As WebPartToolPart = New WebPartToolPart     Dim objCustomProperty As CustomPropertyToolPart = New CustomPropertyToolPart     toolParts(0) = objWebToolPart     toolParts(1) = objCustomProperty     'This is where we add our tool part     toolParts(2) = New Tool     Return toolParts End Function 
end example
 

Creating a Tool Part

As I said earlier, to create a custom tool part, you need to build a new class that inherits from the ToolPart class. Because a tool part is essentially a specialized web part that runs in the tool pane of SPS, you will find that you use many of the same skills to build a tool part that you used previously to build web parts. You can begin your tool part with a simple class definition shown in the following code.

 Imports System.Web.UI Imports System.Web.UI.WebControls Imports Microsoft.SharePoint.Utilities Imports Microsoft.SharePoint.WebPartPages Public Class Tool     Inherits ToolPart End Class 

Just like a standard web part, tool parts must override the CreateChildControls method to build a user interface. You draw the user interface by overriding the RenderToolPart method in the same way you would for a web part. When the user interface is drawn, the child controls show up in the property pane underneath the category you designate for the tool part.

What makes a tool part different from a standard web part is that it has methods that allow it to receive events from the property pane in SPS. These events are primarily fired whenever a user clicks Apply, OK, or Cancel in the tool pane. The ToolPart class allows your custom tool part to receive these events through the ApplyChanges , CancelChanges , and SyncChanges methods.

The ApplyChanges method is called by the web part infrastructure whenever a user clicks Apply or OK. In this method, you retrieve the new value of the property as it was entered into the property pane by the end user. You must in turn pass the property to the web part so that it can update its own display. In order to pass a value from the property pane to the web part, you must retrieve a reference to the web part using the SelectedWebPart property. The following code shows a simple example.

 Public Overrides Sub ApplyChanges()     'Move value from tool pane to web part     Dim objWebPart As Part = DirectCast(Me.ParentToolPane.SelectedWebPart, Part)     objWebPart.Text = txtProperty.Text End Sub 

After any changes are made in the property pane, the web part infrastructure calls the SyncChanges method. This method is used to pass changes back from the web part to the property pane. This is necessary because the web part and the property pane can be out of sync if the user cancels an action or if there is a validation error you need to report to the user. The following code shows a simple example.

 Public Overrides Sub SyncChanges()     Dim objWebPart As Part = DirectCast(Me.ParentToolPane.SelectedWebPart, Part)     txtProperty.Text = objWebPart.Text End Sub 

The CancelChanges method is called by the web part infrastructure whenever a user clicks Cancel. In this method, you can take action to undo any changes that were made to the web part previously. You can also expect the SyncChanges method to be called after the CancelChanges method completes. The following code shows a simple example.

 Public Overrides Sub CancelChanges()     Dim objWebPart As Part = DirectCast(Me.ParentToolPane.SelectedWebPart, Part)     objWebPart.Text = "" End Sub 



Microsoft SharePoint[c] Building Office 2003 Solutions
Microsoft SharePoint[c] Building Office 2003 Solutions
ISBN: 1590593383
EAN: N/A
Year: 2006
Pages: 92

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net