Mobile Text Writer Rendering Best Practices
During the rendering phase, all ASP.NET mobile device adapters write their output using a class that inherits from the MobileTextWriter base class. The actual class of the text writer can be specific to the target device; the page adapter instantiates and returns an appropriate writer. For example, for a device that requires cHTML markup, the ChtmlPageAdapter returns a ChtmlMobileTextWriter object from its CreateTextWriter method.
The MobileTextWriter class defines a set of common properties and methods for adapters. You can define additional helper members for a control adapter that are specific to the writer class for the adapter. Methods of the HtmlTextWriter base class, such as Write, WriteLine, and WriteBeginTag, are available because the MobileTextWriter class inherits from the HtmlTextWriter base class.
Strongly Typed Render Method
An adapter typically needs a text writer of a specific class. For example, the WmlPageAdapter needs to use a WmlMobileTextWriter object. The Render method of the IControlAdapter interface includes a parameter of type HtmlTextWriter. Therefore, the adapter should either override the Render method to make available the desired text writer class, or cast the writer to the required class.
The following example demonstrates overriding the Render method in a new adapter in the XHTML adapter set for a custom CarControl class. The name of this custom adapter is XhtmlCarControlAdapter, which follows established naming conventions for new adapters.
// Specialized XhtmlCarControlAdapter Render method
public void Render(XhtmlMobileTextWriter writer)
{
... [rendering code]
}
// Generic XhtmlCarControlAdapter Render method
public override void Render(HtmlTextWriter writer)
{
Render((XhtmlMobileTextWriter)writer);
}
Beginning and Ending a Response
Before writing a response, a page adapter must call certain methods in its Render method. The following is a typical sequence of actions for a page adapter:
Call the BeginResponse method of the writer.
Call the BeginFile method of the writer, passing in the page URL and the desired content type (MIME type) of the data. For example, an HTML page adapter would pass text/html as the content type.
Render the page (usually the active form).
Call the EndFile method of the writer.
Call the EndResponse method of the writer.
The following code example illustrates a simple Render methodfor an HTML page adapter.
public override void Render(MobileTextWriter writer)
{
writer.BeginResponse();
writer.BeginFile(Page.Request.Url.ToString(), "text/html");
Page.ActiveForm.RenderControl(writer);
writer.EndFile();
writer.EndResponse();
}
Output Encoding
The MobileTextWriter class provides helper methods to encode rendering. Encoding depends on the target device. For example, WML-based devices require dollar signs ($) to be encoded. The helper methods are as follows:
To write text encoded for a target device, your adapter can call the WriteEncodedText method of the writer.
To write a URL (including parameters) for a target device, your adapter can call the WriteEncodedUrl method of the writer.
To write a URL argument (the part of the URL that follows the query symbol [?] of the user agent string) for a target device, your adapter can call the WriteEncodedUrlParameter method of the writer.
Output Caching
ASP.NET Web pages include support for caching page output. A page can be cached by means of an @ OutputCache directive.
In mobile Web pages, the cached output must be set to vary according to the target device. For example, if a device running Microsoft Internet Explorer for the Pocket PC requests a page, the resulting output should be cached and returned only for other devices running Internet Explorer for the Pocket PC.
By default, the HTTP user agent string controls the variation of cached mobile Web pages. However, the output of other devices can be affected by additional properties. For example, a device with a single user agent string might have multiple screen-size settings, each of which can have different output. To allow for these variations, the page adapter can override the CacheVaryByHeaders property.
ASP.NET Web user controls also support an @ OutputCache directive that allows their output to be individually cached. This is called partial caching. However, user controls in mobile Web pages do not support this directive. Mobile Web pages do not support partial caching, because the output of a user control can be different depending on the contents of the rest of the page.
See Also
Concepts
Control and Adapter Interaction