Implementing a Simple Web Forms Control Designer
A Web Forms designer class controls the design-time appearance of a control by providing design-time HTML to a designer host. The .NET Framework provides a base designer class, System.Web.UI.ControlDesigner, that provides base functionality for a server control designer. ControlDesigner defines the following key methods for rendering design-time HTML.
Public Class ControlDesigner Inherits HtmlControlDesigner Public Overridable Function GetDesignTimeHtml() As String ... End Function Protected Overridable Function GetEmptyDesignTimeHtml() As String ... End Function Protected Overridable Function GetErrorDesignTimeHtml(e As Exception) As String ... End Function ' The helper method that provides default placeholder HTML ' cannot be overridden. Invoke this method when it is not possible to ' render a meaningful representation of the control at design time. Protected Function CreatePlaceHolderDesignTimeHtml(s As String) As String ... End Function End Class [C#] public class ControlDesigner : HtmlControlDesigner { public virtual string GetDesignTimeHtml() {...} protected virtual string GetEmptyDesignTimeHtml() {...} protected virtual string GetErrorDesignTimeHtml(Exception e) {...} // The helper method that provides default placeholder HTML // cannot be overridden. Invoke this method when it is not possible to // render a meaningful representation of the control at design time. protected string CreatePlaceHolderDesignTimeHtml(string s) {...} }
The GetDesignTimeHtml method returns design-time HTML for a control. The base implementation of GetDesignTimeHtml invokes the Render method of the control, thereby rendering the same HTML at design time as at run time. The task of the designer is to override GetDesignTimeHtml so as to render HTML that is more appropriate at design time.
The GetEmptyDesignTimeHtml method supplies an HTML string to render at design time if the run-time HTML string rendered by the control is empty, such as when properties are not set. The base implementation of the GetEmptyDesignTimeHtml method returns the fully qualified name and ID of the control. A designer can override this method and invoke CreatePlaceHolderDesignTimeHtml, or it can return alternate HTML.
The GetErrorDesignTimeHtml method provides the HTML to be used for the design-time representation of the control when an error is encountered.
To implement a simple Web Forms control designer
- Define a class that derives directly or indirectly from System.Web.UI.ControlDesigner.
- (Optional) Override the GetDesignTimeHtml method inherited from ControlDesigner.
- (Optional) Override the GetEmptyDesignTimeHtml method inherited from ControlDesigner.
- (Optional) Override the GetErrorDesignTimeHtml method inherited from ControlDesigner.
The Web Forms Templated Data-Bound Control Designer Sample contains an example of a nontrivial designer that overrides these methods.
The following code sample shows a trivial designer (SimpleDesigner) for a simple ASP.NET server control (Simple), which is defined at the end of this topic. Simple has a Text property that it renders at run time as a text string. SimpleDesigner performs one simple task — it renders the Text property of Simple as a hyperlink at design time, thus making the design-time representation different from the run-time representation.
Imports System Imports System.IO Imports System.Web Imports System.Web.UI Imports System.Web.UI.Design Imports System.Web.UI.WebControls Imports CustomControls Namespace CustomControls.Design Public Class SimpleDesigner Inherits System.Web.UI.Design.ControlDesigner Public Overrides Function GetDesignTimeHtml() As String ' Component is the instance of the component or control that ' this designer object is associated with. This property is ' inherited from System.ComponentModel.ComponentDesigner. Dim simple As Simple = CType(Component, Simple) If simple.Text.Length > 0 Then Dim sw As New StringWriter() Dim tw As New HtmlTextWriter(sw) Dim placeholderLink As New HyperLink() ' Put simple.Text into the link's Text. placeholderLink.Text = simple.Text placeholderLink.NavigateUrl = simple.Text placeholderLink.RenderControl(tw) Return sw.ToString() Else Return GetEmptyDesignTimeHtml() End If End Function End Class End Namespace [C#] using System; using System.IO; using System.Web; using System.Web.UI; using System.Web.UI.WebControls; using System.Web.UI.Design; using CustomControls; namespace CustomControls.Design { public class SimpleDesigner : System.Web.UI.Design.ControlDesigner { public override string GetDesignTimeHtml() { // Component is the instance of the component or control that // this designer object is associated with. This property is // inherited from System.ComponentModel.ComponentDesigner. Simple simple = (Simple) Component; if (simple.Text.Length > 0) { StringWriter sw = new StringWriter(); HtmlTextWriter tw = new HtmlTextWriter(sw); HyperLink placeholderLink = new HyperLink(); // Put simple.Text into the link's Text. placeholderLink.Text = simple.Text; placeholderLink.NavigateUrl = simple.Text; placeholderLink.RenderControl(tw); return sw.ToString(); } else return GetEmptyDesignTimeHtml(); } } }
The code for Simple follows. The DesignerAttribute is shown in bold.
Imports System Imports System.Web.UI Imports System.Web.UI.WebControls Imports System.ComponentModel Namespace CustomControls <Designer("CustomControls.Design.SimpleDesigner, CustomControls.Design")> _ Public Class Simple Inherits WebControl Private _text As String Public Property [Text]() As String Get Return _text End Get Set _text = value End Set End Property Protected Overrides Sub RenderContents(writer As HtmlTextWriter) writer.Write([Text]) End Sub End Class End Namespace [C#] using System; using System.Web.UI; using System.Web.UI.WebControls; using System.ComponentModel; namespace CustomControls { [ Designer("CustomControls.Design.SimpleDesigner, CustomControls.Design") ] public class Simple : WebControl { private string text; public string Text { get { return text; } set { text = value; } } protected override void RenderContents(HtmlTextWriter writer) { writer.Write(Text); } } }
See Also
Design-Time Support for Web Forms | Web Forms Templated Data-Bound Control Designer Sample | Implementing a Web Forms Data-Bound Control Designer | Implementing a Web Forms Template Editor