Mobile Text Writer Rendering Best Practices
During the rendering phase, all ASP.NET mobile device adapters write their output through an object called a text writer. A text writer object is created from the TextWriter base class.
The mobile TextWriter object is created from a class that inherits from the MobileTextWriter base class. The actual class of the TextWriter object can be specific to the target device; it is the responsibility of the adapter to create and return an appropriate writer. The adapter has a CreateTextWriter method, which is called by the ASP.NET mobile controls to obtain a writer.
The MobileTextWriter class defines a set of common properties and methods that adapters use. You can also define additional helper members that are specific to the writer class for the adapters to use. Methods of the HtmlTextWriter base class, such as Write, WriteLine, and WriteBeginTag, are available for use because the MobileTextWriter class inherits from the HtmlTextWriter base class.
Strongly Typed Render Method
An adapter typically requires that the writer is of a specific class, but the Render method of the IControlAdapter interface includes a parameter that is of the general HtmlTextWriter class. Therefore, the adapter must cast the writer to the specific class.
To aid in this, the adapter base class for a device must override the Render method and call a specialized Render method that it provides the writer of the specific class. Individual adapters can then override this base class to return the correct writer. The following example demonstrates overriding the Render method.
[C#]
// IControlAdapter.Render implementaton.
public override void Render(HtmlTextWriter writer)
{
// The specialized writer class is the MobileTextWriter class.
Render((MobileTextWriter)writer);
}
// Render is a specialized method that can be overridden by control adapters.
protected virtual void Render(MobileTextWriter writer)
{
// Base implementation only renders child methods.
RenderChildren(writer);
}
Beginning and Ending a Response
Before writing a response, you must call certain methods for the TextWriter object. Because the page is the top-level control that is rendered, it is appropriate for a page adapter to call these 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 (Multipurpose Internet Mail Extensions, or MIME) type of the data. For example, an HTML page adapter would pass in 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 example illustrates a simple Render method for an HTML page adapter.
[C#]
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 also provides helper methods to encode rendering. Encoding depends on the target device; for example, WML-based devices require any 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 Forms pages include automatic support for caching page output. A page can be cached by means of an @ OutputCache directive.
In mobile Web Forms pages, the cached output must 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 Forms pages. However, other devices can have their output 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 Forms user controls also support an OutputCache directive that allows their output to be individually cached. This is known as partial caching. However, user controls in mobile Web Forms pages do not contain this directive. Mobile Web Forms 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.