Section 9.8. Customizing the Property Task Pane

9.8. Customizing the Property Task Pane

Members can change a web part by clicking the web part's down arrow and selecting Modify Shared Web Part or Modify Personal Web Part. That action displays the property task pane. You can customize a web part's property task pane by overriding the GetToolParts method. For example, the following code hides the built-in AllowMinimize property and expands the Custom section of the property task pane, as shown in Figure 9-14.

 Public Overrides Function GetToolParts() As ToolPart()          Dim toolParts(2) As ToolPart          Dim wptp As WebPartToolPart = New WebPartToolPart          Dim custom As CustomPropertyToolPart = New CustomPropertyToolPart          ' Hide one of the built-in properties          wptp.Hide(wptp.Properties.AllowMinimize)          ' Expand the Custom section.          custom.Expand("Custom")          toolParts(0) = wptp          toolParts(1) = custom          Return toolParts      End Function 

The wptp object defined in the preceding code represents the toolpart for the built-in propertiesthose properties inherited from the WebPart base class. The custom object represents the toolpart for all the properties you defined for the web part.

SharePoint generates the controls displayed in the CustomPropertyToolPart class, based on the data type of the custom property and whether or not it is marked as

animal 9-14. Customizing a web part's property task pane

Browsable in the property attributes. Table 9-4 lists the controls generated for various data types.

Table 9-4. Default CustomPropertyToolPart control types

Type	Generated control
String	Text box
Numeric	Text box
Date	Text box
Boolean	Checkbox
Array	Drop-down box
Enumeration	Drop-down listbox

You can override this behavior by creating your own toolpart class and adding it to the toolParts collection. To create a custom toolpart class:

1. Create a new class that inherits from the SharePoint ToolPart class.

2. Get a reference to the parent toolpart using Me.ParentToolPane.SelectedWebPart and converting (casting) the returned object to the web part's type.

3. Override CreateChildControls to add controls to the tool part.

4. Override RenderToolPart to draw the toolpart's user interface.

5. Override ApplyChanges and CancelChanges to commit the toolpart settings to the web part.

The following code illustrates these steps through a custom toolpart that allows users to change the SelectionMode of the Calendar control:

 ' 1) New toolpart class      Class CalToolPart          Inherits ToolPart          Dim _wp As Properties4          Dim _opt As RadioButton()          Dim _initialValue As Integer          Private Sub CalToolPart_Init _           (ByVal sender As Object, ByVal e As System.EventArgs) _           Handles MyBase.Init             ' 2) Get the parent web part and cast to the correct type.             _wp = CType(Me.ParentToolPane.SelectedWebPart, Properties4)             ' Save the inital state in case Cancelled.             _initialValue = _wp._cal.SelectionMode           End Sub           Protected Overrides Sub CreateChildControls()              ' 3) Create option-button controls.              ReDim _opt(4)              _opt(0) = New RadioButton              _opt(0).Text = "None"              _opt(0).GroupName = "SelectionMode"              _opt(1) = New RadioButton              _opt(1).Text = "Day"              _opt(1).GroupName = "SelectionMode"              _opt(2) = New RadioButton              _opt(2).Text = "Week"              _opt(2).GroupName = "SelectionMode"              _opt(3) = New RadioButton              _opt(3).Text = "Month"              _opt(3).GroupName = "SelectionMode"              ' Get the current selection mode.              _opt(_wp._cal.SelectionMode).Checked = True              ' Add controls to the toolpart's Controls collection.              Controls.Add(_opt(0))              Controls.Add(New br)              Controls.Add(_opt(1))              Controls.Add(New br)              Controls.Add(_opt(2))              Controls.Add(New br)              Controls.Add(_opt(3))          End Sub          ' 4) Draw the toolpart          Protected Overrides Sub RenderToolPart _            (ByVal output As System.Web.UI.HtmlTextWriter)              output.Write("Selection mode:<br>")              renderchildren(output)          End Sub          ' 5) Apply the changes to the web part.          Public Overrides Sub ApplyChanges()              ' Find the selected option button              ' and set selection mode to the index              'of that button              For i As Integer = 0 To 3                  If _opt(i).Checked Then _                      _wp._cal.SelectionMode = i               Next           End Sub           ' 5) (Continuted) Cancel changes and restore settings.           Public Overrides Sub CancelChanges()               ' Restore original settings.               _wp._cal.SelectionMode = _initialValue           End Sub       End Class 

In order to make the Calendar control's SelectionMode property available to the toolpart, I changed the scope of the control from Private to Friend in the web part class as shown here:

 ' Make child control properties available to toolpart.  Friend  WithEvents _cal As New Calendar 

Then, to display the new custom toolpart I modified GetToolParts to create an instance of the new class and add the resulting object to the returned toolParts array:

 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''        ' Custom toolparts        Public Overrides Function GetToolParts() As ToolPart()            Dim toolParts(  2  ) As ToolPart            ' Toolpart for built-in properties.            Dim wptp As New WebPartToolPart            ' Toolpart for custom web part properties.            Dim custom As New CustomPropertyToolPart  ' New toolpart for Calendar control properties.            Dim calToolPart As New CalToolPart            calToolPart.Title = "Calendar Toolpart"  ' Add toolparts.            toolParts(0) = wptp            toolParts(1) = custom            toolParts(2) = calToolPart  Return toolParts  End Function 

At runtime, the new toolpart appears in the property pane as shown in Figure 9-15. Members can change the calendar's selection mode by clicking one of the option buttons . The changes made in Figure 9-15 aren't saved after the member navigates away from the page. In order to save settings, you must serialize them by adding a SelectionMode property to the web part class and saving it as described earlier in "Adding Properties."

animal 9-15. Changing the calendar's selection mode through the toolpart

You also might want to hide the other toolparts. In that case, simply omit them from the toolParts array in GetToolParts . For example, the following code displays only the new toolpart:

 Public Overrides Function GetToolParts() As ToolPart()             Dim toolParts(0) As ToolPart             ' New toolpart for Calendar control properties.             Dim calToolPart As New CalToolPart             calToolPart.Title = "Calendar Toolpart"             ' Add toolparts.             toolParts(0) = calToolPart             Return toolParts         End Function 

Finally, you need to be aware that causing postbacks from a toolpart redraws the entire page, discarding the changes made by the toolpart. For that reason, you can't easily use postback controls like command buttons or the Calendar control within a toolpart.