Hi all,
we saw how to build a simple address Web Part in my last post of my post series about Visual Web Part development. We saw how we are able to bind persistent custom properties to our web part instances by simply using attributes associated to our properties. These properties are then mapped automatically for us in the web part editor. This behavior may be enough for most of the cases, however, there are certain situations, where we want to have more control on the behavior of the web part editor. Examples are the addition of more complex controls and data validation. In this post we are going to explore the customization of Editor Parts for our Web Parts.
Walkthrough
At the beginning of this post we are going to explore what are the automatically rendered properties of the Web Part framework. These types are mapped automatically to control in our Editor Parts for us.
After this introduction, we are going to create an Editor Part by following these steps:
- Step 1: Create a new class and inherit from Editor Part and add the abstract methods
- Step 2: Add the controls to the Editor Part
- Step 3: Synchronize the content of the controls in the Editor Part with the properties of your Web Part class
- Step 4: Add a Editor Part reference to your Web Part
Which types are automatically mapped by the Web Part framework?
We know, that basic types are mapped automatically to controls in our Editor Parts for us. To check the different rendered controls, we have to create a new project called EditorPartExample.
- create a Visual Web Part project EditorPartExample
- Add in this project a new Visual Web Part EditorTestWebPart
- add the following code into the EditorTestWebPart.cs file. (If you don’t know how to do it, follow this and this post).
namespace EditorPartExample.EditorTestWebPart
{
public enum EditorTestEnum
{
Value = 1,
Value = 2,
Value = 3
}
[ToolboxItemAttribute(false)]
public class EditorTestWebPart : WebPart
{
// Visual Studio might automatically update this path when you change the Visual Web Part project item.
private const string _ascxPath = @~/_CONTROLTEMPLATES/EditorPartExample/EditorTestWebPart/EditorTestWebPartUserControl.ascx";
[Personalizable(), WebBrowsable(), Category("Web Part Properties")>
public String PropertyAsString { get; set; }
[Personalizable(), WebBrowsable(), Category("Web Part Properties")>
public int PropertyAsInteger { get; set; }
[Personalizable(), WebBrowsable(), Category("Web Part Properties")>
public Boolean PropertyAsBoolean { get; set; }
[Personalizable(), WebBrowsable(), Category("Web Part Properties")>
public EditorTestEnum PropertyAsEnum { get; set; }
protected override void CreateChildControls()
{
Control control = Page.LoadControl(_ascxPath);
Controls.Add(control);
}
}
}
Only for illustrative purposes we are using different basic types and check how they look like in our Editor Part. Deploy your project and add the newly create Web Part to any page. Edit the page and you see these different mapping:
- String: mapped as text editor
- Integer (numeric values in general): mapped as text editor with a number validation (try to insert a String and press “Apply” if you don’t believe me)
- Boolean: mapped as checkbox
- Enum types: mapped in a dropdown list
Pretty neat stuff, however, we encounter some drawbacks when using only the automated approach:
- you can’t include complex types (e.g., list of custom classes)
- you don’t have much control on the validation of your controls. However, you can do this with basic types (check this post if you want to see how it may work).
- you have to stick on the standard layout rules of the Editor Part (e.g., if you want to modify an integer property with a range of values included into a dropdown box that can’t be defined as an enum type)
Creating the first Editor Part
If we want to get more from the Editor Part, we have to customize it and create our own. Fortunately, this step is not so difficult as you might think. The Web Part framework does most of the job for us, we only need to create a new class and inherit from the EditorPart class of the Web Part framework. Then we have to add custom code and create our user interface from scratch. The steps needed to accomplish this task are:
- Step 1: Create a new class and inherit from Editor Part and add the abstract methods
- Step 2: Add the controls to the Editor Part
- Step 3: Synchronize the content of the controls in the Editor Part with the properties of your Web Part class
- Step 4: Add a Editor Part reference to your Web Part
To illustrate these steps, we are going to create a custom Editor Part that edits our property PropertyAsInteger in a custom way: we want a Dropdown list with the values ranging from 0 to 5. When the user edits the Web Part, he will see the Dropdown list and use it to modify the value of our Web Part property.
Step 1: Create a new class and inherit from Editor Part and add the abstract methods
First of all, we are going to create a new class called SampleEditor.cs and add it to our EditorTestWebPart container and setup the class to inherit from the EditorPart class of the Web Part framework. Please change the code of the SampleEditor.cs to the code you see in the next code snipped.
namespace EditorPartExample.EditorTestWebPart
{
public class SampleEditor : EditorPart
{
public override bool ApplyChanges()
{
throw new NotImplementedException();
}
public override void SynchChanges()
{
throw new NotImplementedException();
}
}
}
Step 2: Add the controls to the Editor Part
We only created a simple class. Now, we are going to extend it and put some controls. In our case we are going to add a DropDown list holding the values from 0 to 5. The code snipped that does it is shown below:
namespace EditorPartExample.EditorTestWebPart
{
public class SampleEditor : EditorPart
{
private DropDownList list;
protected override void OnInit(EventArgs e)
{
base.OnInit(e);
list = new DropDownList();
}
protected override CreateChildControls()
{
base.CreateChildControls();
this.Controls.Add(list);
}
protected override void OnPrerender(EventArgs e)
{
base.OnPreRender(e);
list.DataSource = new int[] { 0, 1, 2, 3, 4, 5 };
list.DataBind();
}
public override bool ApplyChanges()
{
throw new NotImplementedException();
}
public override void SynchChanges()
{
throw new NotImplementedException();
}
}
}
What we did until now? We defined a Dropdown and initialized it in the OnInit method of the Web Part. In the CreateChildControls added the control to the Editor Part control list. At the end, we added an array of integers ranging from 0 to 5 to the datasource property of our dropdown list. There are still two methods that need to be implemented
Step 3: Synchronize the content of the controls in the Editor Part with the properties of your Web Part class
The content synchronization between Web Parts and Editor Parts is done by two methods:- The ApplyChanges method is called when the Editor Part applies the changes or presses ok. This is the right moment to save the properties back to our Web Part.
- On the other hand, the SynchChanges method is used to synchronize the Web Part properties with our Editor Part.
In our example we are doing following. The code snippet that follows reflects these actions:
- In the ApplyChanges method we are retrieving the Web Part instance that is currently edited and set the property that we want to change to the property defined in our Dropdown list. Afterwards, we tell to the Web Part framework that we passed correctly the values by returning true.
- In the SynchChanges method we do it in the inverse order. We take the values from the Web Part that we want to edit and synchronize them with the controls in our Editor Part.
namespace EditorPartExample.EditorTestWebPart
{
public class SampleEditor : EditorPart
{
private DropDownList list;
protected override void OnInit(EventArgs e)
{
base.OnInit(e);
list = new DropDownList();
}
protected override CreateChildControls()
{
base.CreateChildControls();
this.Controls.Add(list);
}
protected override void OnPrerender(EventArgs e)
{
base.OnPreRender(e);
list.DataSource = new int[] { 0, 1, 2, 3, 4, 5 };
list.DataBind();
}
public override bool ApplyChanges()
{
EditorTestWebPart webPart = this.WebPartToEdit as EditorTestWebPart;
if (webPart != null)
{
webPart.PropertyAsInteger = int.Parse(list.SelectedValue);
}
return false;
}
public override void SynchChanges()
{
EditorTestWebPart webPart = this.WebPartToEdit as EditorTestWebPart;
if (webPart != null)
{
list.SelectedValue = webPart.PropertyAsInteger.ToString();
}
}
}
}
Step 4: Add a Editor Part reference to your Web Part
We are almost finished. Our simple custom Editor Part is finished, but, the Web Part framework does not know that we want to bind this editor part to our Web Part. Therefore, we need to tell to the EditorTestWebPart, that we want to use this custom Editor Part when going in edit mode. In addition, we have to tell to the Web Part framework, that the property PropertyAsInteger should not be generated automatically in our editor. To do this we have to follow these steps:
- Go to the EditorTestWebPart.cs
- Override the method CreateEditorParts and add your Web Part to the EditorPart collection
- Remove the WebBrowsable attribute from the PropertyAsInteger property
- The final code in the Web Part EditorTestWebPart.cs will look like that:
namespace EditorPartExample.EditorTestWebPart
{
public enum EditorTestEnum
{
Value = 1,
Value = 2,
Value = 3
}
[ToolboxItemAttribute(false)]
public class EditorTestWebPart : WebPart
{
// Visual Studio might automatically update this path when you change the Visual Web Part project item.
private const string _ascxPath = @~/_CONTROLTEMPLATES/EditorPartExample/EditorTestWebPart/EditorTestWebPartUserControl.ascx";
[Personalizable(), WebBrowsable(), Category("Web Part Properties")>
public String PropertyAsString { get; set; }
[Personalizable(), WebBrowsable(), Category("Web Part Properties")>
public int PropertyAsInteger { get; set; }
[Personalizable(), WebBrowsable(), Category("Web Part Properties")>
public Boolean PropertyAsBoolean { get; set; }
[Personalizable(), WebBrowsable(), Category("Web Part Properties")>
public EditorTestEnum PropertyAsEnum { get; set; }
protected override void CreateChildControls()
{
Control control = Page.LoadControl(_ascxPath);
Controls.Add(control);
}
public override EditorPartCollection CreateEditorParts()
{
List<EditorPart> editorParts = new List<EditorPart>();
SampleEditor sampleEditor = new SampleEditor();
sampleEditor.ID = this.ID + "_sampleEditorPart";
editorParts.Add(sampleEditor);
return new EditorPartCollection(base.CreatEditorPart, editorPart);
}
}
}
And we are done. Finally, you only need to deploy the solution to SharePoint and use your Web Part.
Summary
Now, that you saw how to create and combine a custom Editor Part with a Web Part, you can do whatever you want. However, there is still a big drawback with this technique. You have to create your Editor Part from scratch by hand. However, I will show you in a post that will follow in the next day, that with some simple modifications, we will be able to use the same approach of the Visual Web Parts with our Editor Parts. Are you interested how this might work? Then follow and bookmark my post series about Visual Web Part development. :)
Best regards,
Patrick Lamber
