Thursday, June 19, 2008

Creating Editor Web Parts

When a page is placed in Edit Mode, a user can select to edit a Web Part's
control properties. An *EditorPart* control enables a user to edit an
associated Web Part control to modify its layout, appearance, properties,
behavior, or other related characteristics.

Sometimes the default functionality will not be enough for your needs. For
example, a Web Part could have a string property with complicated validation
logic behind it, or you may want a Web Part property to be a filter field.
You may also want a Web Part to be rendered like a drop-down list, which
will contain dynamically loaded information.

To create an *EditorPart* control, you need to implement a control that
derives from the *EditorPart* class. Next, you will have to override the *
ApplyChanges* and the *SyncChanges *methods. *ApplyChanges* applies changes
made in the editor control to the Web Part control being edited when the
user clicks OK or Apply. The *SyncChanges* method gets the current values of
the Web Part control being edited and passes them to the editor so that the
editor control can edit them (this also avoids synchronization problems
between the Web Part and the editor).

Next, to render your custom HTML, you need to override the *
CreateChildControls* and the *RenderContents* functions.

Here is an example of a skeleton for a ZIP Code editor part, which provides
a text box where you can enter a ZIP Code as well as validate it.

public class ZipCodeEditor : EditorPart
{
TextBox input = null;
Label displaymessage = null;
Literal lineBreak;
protected override void CreateChildControls()
{
Controls.Clear();
input = new TextBox();
this.Controls.Add(input);
lineBreak = new Literal();
lineBreak.Text = @"
";
Controls.Add(lineBreak);
displaymessage = new Label();
this.Controls.Add(displaymessage);
}
protected override void RenderContents(HtmlTextWriter writer)
{
writer.Write("
");
input.RenderControl(writer);
writer.Write("
");
displaymessage.RenderControl(writer);
}
public override bool ApplyChanges()
{
try
{
//validation logic

//if ValidationSuccessful
ZipCodeWebPart part = (ZipCodeWebPart)WebPartToEdit;
// Update the custom WebPart
part.ZipCode = input.Text;
}
catch (Exception exc)
{
//error handling
}
return true;
}
public override void SyncChanges()
{
input.Text = ((ZipCodeWebPart)WebPartToEdit).ZipCode;
}
}

To associate the editor part with your Web Part, you will need to override
the *CreateEditorParts* method in the Web Part where you will create the
instances of the editor parts. An example of this is as follows:

public class ZipCodeWebPart : System.Web.UI.WebControls.WebParts.WebPart
{
protected string _zipcode;
public ZipCodeWebPart()
{
//
}
[Personalizable(PersonalizationScope.Shared), WebBrowsable(false),
WebDisplayName("ZipCode"),
WebDescription("The ZipCode")]
public string ZipCode
{
get { return _zipcode; }
set { _zipcode = value; }
}
public override EditorPartCollection CreateEditorParts()
{
ArrayList editorArray = new ArrayList();
ZipCodeEditor edPart = new ZipCodeEditor();
edPart.ID = this.ID + "_editorPart1";
editorArray.Add(edPart);
EditorPartCollection editorParts =
new EditorPartCollection(editorArray);
return editorParts;
}
protected override void RenderContents(HtmlTextWriter writer)
{
//
}
protected override void Render(HtmlTextWriter writer)
{
//
}
}

1 comment:

Claral said...

People should read this.