EditorPart is, essentially, Webpart Properties taken to the next level. If you look at Webpart Properties, you have a very limited subset of forms they can take. You have TextBoxes (string type), CheckBoxes (Boolean type), and simple drop-down lists (Enum type). But what if you need a TextArea? What if you need, as my example will show, a dynamic dropdown? Webpart Paroperties (alone) cannot provide you with a solution. This is where EditorParts come in.
EditorPart is really special WebPart. When you use it, it will be built as a seperate class parallel to your webpart’s class. When you impliment an EditorPart, instead of it appearing as a true webpart, it will appear in the EditorPane. This allows you to program the display and actions of the variable settings of your webpart.
The EditorPart class
ASP.NET 2.0 contains an abstract class called EditorPart, this class is used with the ASP.NET 2.0 WebPart class to create customized tool panes. By inheriting from this control you can customize the look and functionality of the tool pane and use standard ASP.NET constructs such as auto post backs, validations etc.
Writing a custom editor basically is a two-step process:
- The WebPart needs to tell the framework which specific editors it wants to use. The framework then will add those editors into the EditorZone.
- You need to write the editors themselves. These simply inherit from the System.Web.UI.WebControls.WebParts.Editor class.
Writing the EditorPart
As mentioned previously, the editor simply inherits from the EditorPart class(Add a new Class file to the same namespace). This class will require you to implement two methods:
- ApplyChanges: This method is responsible for taking the user’s current edits, as displayed in the editor, and apply them to the WebPart itself. In this case, this would mean setting a value to the DisplayText property.
- SyncChanges: This method is responsible for retrieving the current state of the WebPart and updating the editor itself to display the current state of the WebPart.
In either scenario, you can access the WebPart being edited by using the WebPartToEdit property available on the EditorPart itself.
Note: Don’t forget to set ID to the EditorPart; otherwise, it will pop up error when you click “Edit Web Part” on the page.
The controls are added in the CreateChildControls method. This is where you should place most of your control logic, in editor parts, web parts etc.
The SynChanges method is used by the EditorPart to get the values from the Web Part into the Editor Part.
The ApplyChanges method is executed when you click Ok or Apply and is used to set the property values of your Web Part. SyncChanges is always called directly after the ApplyChanges method, to make sure that the properties are in sync.
Note: The EnsureChildControls method is called in order to make sure that child controls have been created and are ready to process input, to perform data binding, or to perform other tasks. Without this method, it will pop up error.
Modify the WebPart class
Now we have to tell the web part that it should use this editor part, instead of the attributed properties. First of all we want to get rid of the automatic interface for the properties, this is done by removing the Personalizableattribute.
Note: Just removing the Personalizable attribute and none of the others (WebBrowsable etc), will still allow you to configure these properties using tools such as SharePoint Designer.
Now only one thing remains and that is to expose the editor part from the web part. To do this you have to make your web part class inherit from the IWebEditable interface and implement it.
The CreateEditorParts method is used to tell the web part zone what editor parts you will show, in this case we only have one. But more advanced web parts may require that you have several.
Tip: You can use the WebPartManager.Personalization status to add different editor parts. For example you can have one for the Shared scope and another for the User scope
The WebBrowsableObject property is used to get a reference to the Web Part, just return the this object in your editor parts. This property is used by the editor part to get which web part to edit, via the WebPartToEdit method.