Downlevel Rendering

It is possible that some browsers that do not support HTML 4.0 will access a page that uses your control. As a control author, you do not have to do much work to support this scenario. The page framework provides a mechanism that automatically takes responsibility for rendering the appropriate content to various types of browsers and to various versions of the same browser.

There are two versions of the HtmlTextWriter class: HtmlTextWriter , which renders HTML 4.0, and Html32TextWriter , which derives from HtmlText ­Writer and renders HTML 3.2. HtmlTextWriter is extensible, meaning that it can be customized to target a specific browser. The following list describes some of the significant conversions and approximations performed by Html32TextWriter to convert tags, attributes, and CSS style attributes into their most appropriate downlevel HTML 3.2 equivalent:

• Renders the font-family , font- size , and color CSS attributes as attributes on a <font> tag instead of rendering a style attribute on the element's tag.

• Renders the font-weight CSS attribute as opening and closing <b> tags around content.

• Renders the font-style CSS attribute as opening and closing <i> tags around content.

• Renders the text-decoration CSS attribute as opening and closing <u> or <strike> tags.

• Propagates the font information specified on a table into the table cell and renders it as a <font> tag around the content (because specifying <font> around the table itself has no effect on its content).

• Renders a <div> as an equivalent table.

• Renders the border-color CSS attribute as a bordercolor attribute for an enclosing table.

• Renders the background-color CSS attribute as a bgcolor attribute for a <table> or <td> .

A Web application specifies the HtmlTextWriter to be used for a given browser via the tagwriter attribute in the browserCaps section of the web.config or machine.config configuration file. As a control author, you are not responsible for the settings in the configuration file. The following example shows the clientTarget section and a part of the browserCaps section of the machine.config file that installs with the .NET Framework:

 <configuration> <system.web> <clientTarget> <addalias="ie5"  userAgent="Mozilla/4.0(compatible;MSIE5.5;WindowsNT4.0)"/> <addalias="ie4"  userAgent="Mozilla/4.0(compatible;MSIE4.0;WindowsNT4.0)"/> <addalias="uplevel"  userAgent="Mozilla/4.0(compatible;MSIE4.0;WindowsNT4.0)"/> <addalias="downlevel" userAgent="Unknown"/> </clientTarget> <browserCaps> <resulttype="System.Web.HttpBrowserCapabilities"/> <usevar="HTTP_USER_AGENT"/> browser=Unknown version=0.0 majorversion=0 minorversion=0 frames=false tables=false cookies=false backgroundsounds=false vbscript=false javascript=false javaapplets=false activexcontrols=false win16=false win32=false beta=false ak=false sk=false aol=false crawler=false cdf=false gold=false authenticodeupdate=false  tagwriter=System.Web.UI.Html32TextWriter  ecmascriptversion=0.0 msdomversion=0.0 w3cdomversion=0.0 platform=Unknown clrVersion=0.0 css1=false css2=false xml=false ... </browserCaps> </system.web> </configuration> 

When a page receives a Web request, it detects the browser type by using the HTTP_USER_AGENT server variable and creates the HtmlTextWriter specified in the web.config file for that browser type. The correct HtmlTextWriter object is thus automatically passed into the rendering methods of your control. However, your control benefits from the automatic tag conversion capability provided by the HtmlTextWriter object only if it uses the HtmlTextWriterTag enumeration to render tags. If you render tags as strings, they are rendered by the HtmlTextWriter instance without any additional processing and your control cannot utilize the uplevel/downlevel-rendering architecture that is built into the page framework.

A page developer can also specify the target browser via the ClientTarget attribute in the Page directive. This attribute overrides automatic browser detection and results in creating the HtmlTextWriter that maps to the browser specified by the attribute value.

To test the downlevel or HTML 3.2 rendering capabilities of LoginUI , replace the Page directive at the top of LoginUITest.aspx (shown in Listing 8-6) with the following Page directive to force a downlevel rendering:

 <%@PageLanguage="C#" ClientTarget="downlevel" %> 

Access the page in your browser. If you view the source for the page, you should see HTML rendered by LoginUI that is similar to this:

 <tablecellspacing="1" id="LoginUI1" bgcolor="Gainsboro"> <tr> <td> <fontface="Verdana" size="2"> <b>LoginName:</b> </font> </td> <td> <fontface="Verdana" size="2"> <b><inputtype="Text" name="LoginUI1:UserName"  id="LoginUI1_UserName" value="" /></b> </font> </td> </tr> <tr> <td> <fontface="Verdana" size="2"> <b>Password:</b> </font> </td> <td> <fontface="Verdana" size="2"> <b><inputtype="Password" name="LoginUI1:Password"  id="LoginUI1_Password" value="" /></b> </font> </td> </tr> <tr> <tdcolspan="2" align="right"> <fontface="Verdana" size="2"> <b> <inputtype="Submit" name="LoginUI1"  id="LoginUI1" value="Submit" /> </b> </font> </td> </tr> </table> 

Notice that a style attribute is no longer generated on the <table> tag because HTML 3.2 browsers do not support CSS styles. Notice also that the <font> and <b> tags are propagated into the content within the table cells . We did not do any extra work in the implementation of the LoginUI control to enable downlevel rendering. The LoginUI control benefits from the automatic downlevel-rendering capability of Html32TextWriter because we invoked the rendering methods of HtmlTextWriter to write attributes, styles, and tags and because we used enumerations instead of strings when specifying tag names . If we had rendered the user interface by using raw HTML, LoginUI would not be able to automatically generate HTML 3.2.