ControlAdapter Class

Customizes rendering for the derived control to which the adapter is attached, to modify the default markup or behavior for specific browsers, and is the base class from which all control adapters inherit.

Syntax

public abstract class ControlAdapter

Remarks

Control adapters are components that override certain System.Web.UI.Control class methods and events in its execution lifecycle to allow browser or markup-specific handling. The .NET Framework maps a single derived control adapter to a System.Web.UI.Control object for each client request.

An adapter modifies a control for a specific browser or class of browsers or acts as an arbitrary filter on some capability. Typically the adapter is defined by the markup language that the browser uses (for example, XHTML or HTML 3.2). Much of the adaptability in rendering behavior can be encapsulated in the specialized classes that derive from the System.Web.UI.HtmlTextWriter class. Therefore, it is likely that a single adapter can be used for a number of browser class behaviors or that inclusion of the adaptability in the System.Web.UI.HtmlTextWriter classes could make the use of a control adapter unnecessary.

An adapter for a control class applies to all controls that inherit from that class, unless more specialized adapters are present. For example, an adapter for the System.Web.UI.WebControls.BaseValidator class can be used for all Validator objects.

Adapters typically do not inherit directly from the System.Web.UI.Adapters.ControlAdapter class, but from one of the target-specific adapter base classes that provide additional functionality specific to the control type and target browser or the particular rendering required.

Controls themselves do not necessarily require an adapter. If controls are extended through composition, generally the child control adapters are sufficient.

Each control has explicit mappings to adapters through the .browser definition files. Thus, any access to the System.Web.UI.Control.Adapter property uses the System.Web.HttpBrowserCapabilities object extracted from the browser definition files to perform the lookup for the mapping of the adapter to control.

During processing, the .NET Framework intercepts calls to the overridable methods of a control that could be target-specific. If a control adapter is attached, the .NET Framework calls the associated adapter methods.

The adapter performs rendering for the control through the ControlAdapter.Render(System.Web.UI.HtmlTextWriter) method. If overridden, ControlAdapter.Render(System.Web.UI.HtmlTextWriter) potentially should not call the base class implementation because that performs a call back on the System.Web.UI.Control.Render(System.Web.UI.HtmlTextWriter) method. This might cause the rendering to occur twice, once by the adapter and once by the control.

The ControlAdapter.Render(System.Web.UI.HtmlTextWriter) base method calls back on the System.Web.UI.Control.Render(System.Web.UI.HtmlTextWriter) method of the control. Thus, if you override ControlAdapter.Render(System.Web.UI.HtmlTextWriter), you should not call the base class implementation unless the rendering you implement is in addition to that provided by System.Web.UI.Control.Render(System.Web.UI.HtmlTextWriter) of the control.

You must ensure that the .NET Framework performs interception for adapters of the child controls. You can do this by calling the ControlAdapter.RenderChildren(System.Web.UI.HtmlTextWriter) base method, which calls the System.Web.UI.Control.RenderChildren(System.Web.UI.HtmlTextWriter) method of the control, from your ControlAdapter.Render(System.Web.UI.HtmlTextWriter) override.

To maintain its own state information, a control adapter can override the ControlAdapter.SaveAdapterControlState, ControlAdapter.LoadAdapterControlState(object), ControlAdapter.SaveAdapterViewState, and ControlAdapter.LoadAdapterViewState(object) methods. ControlAdapter.SaveAdapterControlState, ControlAdapter.SaveAdapterViewState, ControlAdapter.LoadAdapterControlState(object), and ControlAdapter.LoadAdapterViewState(object) are called when the private control and view states are saved and loaded, respectively.

The ControlAdapter.OnInit(EventArgs), ControlAdapter.OnLoad(EventArgs), ControlAdapter.OnPreRender(EventArgs), and ControlAdapter.OnUnload(EventArgs) base methods call back on the corresponding System.Web.UI.Control class methods. Thus, any of these System.Web.UI.Adapters.ControlAdapter methods that are overridden must call their base methods; otherwise, the event associated with the System.Web.UI.Control class method will not be raised.

Controls and adapters optionally implement the System.Web.UI.IPostBackDataHandler and System.Web.UI.IPostBackEventHandler interfaces. The .NET Framework determines whether an adapter exists and whether the adapter implements these interfaces. If it does, the adapter should override the System.Web.UI.IPostBackDataHandler.LoadPostData(string, System.Collections.Specialized.NameValueCollection), System.Web.UI.IPostBackDataHandler.RaisePostDataChangedEvent, and System.Web.UI.IPostBackEventHandler.RaisePostBackEvent(string) methods, as necessary. If the postback data is not recognized in the adapter, it must call back on the control to process it. Subsequent event handlers also must call back on the control.

Requirements

Namespace: System.Web.UI.Adapters
Assembly: System.Web (in System.Web.dll)
Assembly Versions: 2.0.0.0
Since: .NET 2.0