|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer|
Architectural Overview of Adaptive Control Behavior
Adaptive control behavior is control behavior that is customized for target devices. ASP.NET 2.0 provides an adaptive architecture that allows key life cycle stages of a control to be intercepted and substituted with custom behavior. By default, the ASP.NET page framework maps a single instance of an adapter to each control for each request. In most cases, this default mapping is flexible enough to meet most developer needs. In specialized cases, a custom adapter can be derived and mapped to a control to meet additional requirements for control behavior on a given device or family of devices.
A common example of adaptive control behavior is adaptive rendering wherein an ASP.NET Web page is rendered specific to the browser or markup. This is especially useful for writing applications that support browsers that use different markup languages. There are several ways that you can control the adaptive rendering of a Web page in ASP.NET—from specifying the default XHTML rendering of your application to providing a customobject. Providing a custom ControlAdapter object is an advanced task and is not required in most user scenarios.
You can control adaptive rendering in the following ways:
Configure your application to render multiple markups.
Use theor class to customize control tags and attributes.
Create a customclass to render output.
Use declarative device markup or browser filtering to affect how control properties are set based on device filter definitions.
Provide a custom control adapter that lets you substitute an adapter life cycle method over the default life cycle method for a control.
Besides adaptive rendering, other control behavior that could be adapted or specified according to a target device includes the following:
Processing postback data.
Managing view state.
Preventing a custom control from being adapted.
ASP.NET Page and Control Rendering
In the default rendering of ASP.NET Web page, an instance of theclass is created and the method is called recursively by using the parameter that is set to the instance of the HtmlTextWriter class. Each control in the page control hierarchy appends its markup to the end of the HtmlTextWriter object. The content of the resulting HtmlTextWriter is what is rendered to the resulting browser.
When rendering HTML 3.2 content to clients, ASP.NET automatically uses theclass. To determine the type of TextWriter object to use, the ASP.NET page framework queries the property of the object.
By default, when you are working with browsers that support HTML 4.0 or later, ASP.NET pages and controls render markup that complies with the XHTML 1.0 Transitional standard. To specify whether ASP.NET renders markup that complies with XHTML standards, configure thein the Web.config file for your application. For more information about ASP.NET and XHTML, see . For more information about the page life cycle, see .
Using a Custom TextWriter Object
By default, ASP.NET uses the appropriate TextWriter object for the requesting device. When you need more control over the TextWriter, you can use an existing class that inherits from the HtmlTextWriter class or you can create a custom text writer.
The XhtmlTextWriter and ChtmlTextWriter classes are two classes in the ASP.NET page framework that inherit from the HtmlTextWriter and Html32TextWriter classes, respectively. The XhtmlTextWriter and ChtmlTextWriter classes provide additional adaptive rendering capabilities. For example:
The XhtmlTextWriter class is useful for rendering XHTML markup to mobile devices and provides methods for customizing attributes of the rendered XHTML elements.
The ChtmlTextWriter class is useful for rendering cHTML or compact HTML to devices with limited memory and CPU power, together with small display screens, limited formatting capabilities, and a limited number of input options, such as a cellular telephone touch pad.
If you create a custom text writer or if you want to specify a particular text writer to render output for a specific device, you must map the text writer to the device that is using the markupTextWriterType attribute of the controlAdapters element in a .browser file for the application.
Device filtering lets you declaratively customize the output rendering aspects of a Web server control property. You can apply filtering to control properties, custom attributes, and templates. You can also use device filtering on some attributes for theand directives. If multiple device filters are specified for a property or an attribute, the most specific filter takes precedence.
Device filter definitions that are used to filter output are based on the definition of browser types, as defined in your application. The default browser definition files are in the %SystemRoot%\Microsoft.NET\Framework\versionNumber\CONFIG\Browsers directory. Browser definition files that are specified in the App_Browsers folder for the application are merged with the default definition files.
For more information about device filtering, see. For more information about the .browser file format, see .
For customizing the behavior for a page or control, ASP.NET 2.0 lets you specify a ControlAdapter object that adapts or modifies behavior at key points in the life cycle of the control. At each stage in the life cycle, where a call to a life cycle method is made, the ASP.NET page framework checks to see if there is an associated adapter for the control and calls on the adapter's associated method instead of the control's method. In many cases, the adapter method may simply defer back to the control's method. An exception to this behavior are adapters for state management in that the adaptive behavior is additive to the control's state.
Situations where you would want to override the behavior for a control with a control adapter include the following:
To provide target-specific processing during a specific stage of the control life cycle.
For example, you can use themethod of the ControlAdapter class to perform initialization tasks that are specific to the control that the adapter is attached to and specific to the target device that the control is rendered to.
To customize target-specific rendering.
For example, you can use theand methods to generate target-specific markup.
The WebControlAdapter and PageAdapter Controls
The ControlAdapter class is an abstract class that defines the basic functionality for all adapters. It serves as the base class for theand classes.
The WebControlAdapter class is the starting point for rendering controls that adaptively inherit from theclass. Besides ControlAdapter class methods, the WebControlAdapter class adds several methods that are specific to rendering tags.
The abstract PageAdapter class is the starting point for rendering a Web page adaptively.
Additionally, the PageAdapter class defines properties and methods that enable adaptive rendering in the context of typical page-level tasks, such as caching or managing page-state persistence. For example, in addition to caching pages based on target-independent parameters, you might have to cache based on the type of the target browser. In this scenario, you would override theproperty of the PageAdapter class to return a list of the additional GET or POST parameters to control target-specific caching.
Similar to custom text writers, for custom control adapters to be recognized by the ASP.NET page framework, the custom control adapters must be defined in the controlAdapters element in the .browser file for the application. For more information about the .browser file format, see.
Design patterns for creating adapters include the following guidelines:
A control that inherits from theclass should have an adapter that inherits from the ControlAdapter class.
A control that inherits from the WebControl class should have an adapter that inherits from the WebControlAdapter class.
Developers creating custom controls that need to extend adapter functionality should create base class adapters for their controls.