WML Adapter Set
The WML adapter set consists of classes that can be used to render ASP.NET mobile Web pages on clients that support WML v1.1 or WML v1.2. Some methods and properties might not be included in this documentation. The following table lists the core classes that are included in the WML adapter set.
Adapter set for WML Devices |
Core adapter class namespace |
|---|---|
ControlAdapter abstract base class |
|
HtmlFormAdapter class |
|
PageAdapter abstract class |
|
MobileTextWriter class |
An Openwave UP.Browser uses a different page adapter and text writer. The following table lists the core classes that are used by the adapter set supporting these browsers.
Adapter set for UP.Browsers |
Core adapter class namespace |
|---|---|
ControlAdapter abstract base class |
|
HtmlFormAdapter class |
|
PageAdapter abstract class |
|
MobileTextWriter class |
Note
With UP.Browser 4.1 or UP.Browser 3.2, the Redirect method always behaves as if the value of the SupportsRedirectWithCookie property of the HttpBrowserCapabilities object is false, unless the Cookieless property in the SessionState section of Web.config has been explicitly set to true.
In ASP.NET 1.1, the options for this setting were true or false, but with ASP.NET 2.0, the choices are expanded, and AutoDetect is now the default setting. If your Web application has the cookieless attribute of the <sessionState> section in Web.config set to a Boolean value, the Redirect method will work as expected for these browsers.
Selection
The WML adapter set is selected if the PreferredRenderingType property of the MobileCapabilities class returns PreferredRenderingTypeWml11 or PreferredRenderingTypeWml12.
Adaptive Rendering
The WML adapter set is capable of adapting significantly to the various capabilities of WML-based cell phones. Hence, the adapter set actually calls the Render method twice for each form and its child controls. In the first pass, the writer is in analysis mode and uses all calls made to it to analyze form output. In the second pass, the form is actually rendered.
Avoid creating adapters that distinguish between passes. If absolutely necessary, you can write an adapter that can access the current mode by checking the AnalyzeMode property of the WmlMobileTextWriter class.
Default Rendering
The following steps show the default renderings of page and form adapter classes in the WML adapter set.
The page adapter performs the following steps:
Calls the BeginResponse and BeginFile methods for the writer. Content type is text/vnd.wap.wml.
Writes out an opening <wml> tag.
Renders the active form.
Renders linked forms as part of the same WML deck, if possible.
Writes out a closing </wml> tag.
Calls the EndFile and EndResponse methods.
The form adapter performs the following steps:
Sets the writer to analysis mode.
Calls the writer's BeginForm method.
Renders form contents. The results are not sent to the device, but are analyzed by the writer.
Calls the writer's EndForm method.
Sets the writer to live mode.
Calls the writer's BeginForm method.
Renders form contents.
Calls the writer's EndForm method.
Using Styles
The WmlMobileTextWriter class provides a number of helper methods that aid you in using style information to render content:
The EnterLayout and ExitLayout methods allow an adapter to emit markup to begin and end a block using the paragraph formatting from a given style.
The EnterFormat and ExitFormat methods allow an adapter to emit markup to begin and end a block using the character formatting from a given style.
The ResetFormattingState method allows an adapter to reset the formatting state to the default state.
Adaptive Rendering Methods
The WmlMobileTextWriter class provides a number of high-level methods for rendering, as shown in the following table.
WML adapters must use these methods to render content because the writer can automatically adapt the output optimally based on capabilities of the target device.
For details about each of these methods, see the documentation for the WmlMobileTextWriter class.
Writer method |
Description |
|---|---|
Renders a text element. |
|
Renders an image element. |
|
Renders a text input box element. |
|
Renders a hyperlink element. Call the RenderText or RenderImage method to render text or an image inside the hyperlink. |
|
Renders a postback element. Call the RenderText or RenderImage method to render text or an image inside the postback. |
|
Renders a selection list element. Calls the RenderSelectOption method to render each option in the selection list. |
|
Adds a variable and an initial value to render with the form. When a WML device renders the form, it initializes the variable to the specified initial value. |
Additionally, the WmlControlAdapter base class provides a number of higher-level methods, as shown in the following table. Each of these methods renders using the writer methods listed previously.
Adapter method |
Description |
|---|---|
Renders a link. The adapter automatically determines how to render the link, rendering links to forms on the same page as postbacks, and rendering other links as hyperlinks. Call the RenderText or RenderImage method on the writer to render text or an image inside the link. |
|
Renders a link with inner text. |
|
Renders a postback event with the control as a target. |
Rendering Menus
On some WML-based devices, a form that consists of multiple links or anchors are better rendered as a menu of items using <select> and <option> elements, with an automatically generated keypad navigation user interface (UI). An Openwave UP.Browser is an example of such a device.
The WML form adapter can render a form as a menu if the form consists of zero or more controls that render as static text, followed by one or more controls that can render <select> and <option> elements.
If the RendersWmlSelectsAsMenuCards property of the MobileCapabilities class is set to true, the device can render <select> elements as menu cards rather than as a combo box.
The CanCombineFormsInDeck property is set to true if the browser can handle decks that contain multiple forms as separate cards. The adapter can output multiple forms from the same page as cards of a single deck.
Rendering Form Accept Controls
When a rendered form includes UI to submit the form back to the server, some WML-based devices require that the UI for the specified device be a <do> element at the start of the form. An Openwave UP.Browser is an example of such a device.
When a device requires that the UI use a <do> element, the form adapter checks whether any of the controls on the form require submit UI, and whether any of the controls provide such UI. To determine this, the form adapter queries the adapters of each of the controls on the form.
Rendering for Softkeys
Some controls render UI that can be mapped to a softkey on a WML-based device. The RendersWmlDoAcceptsInline property of the MobileCapabilities class is set to true if the device renders a WML <do> element as an inline button rather than as a softkey.
Secondary UI
The WML adapter set supports secondary UI, which is used by controls to show additional screens of the user interface. To use secondary UI, a control adapter performs the following steps:
In response to some user interaction (usually in the overridable HandlePostBackEvent method), the control adapter specifies secondary UI mode by setting the SecondaryUIMode property of the WmlControlAdapter base class.
In rendering, the control checks whether it is in secondary UI mode, if so, renders the appropriate secondary UI.
In response to user interaction from the secondary UI, the control adapter might change the secondary UI mode to another value, or it might exit secondary UI mode by calling the ExitSecondaryUIMode method of the WmlControlAdapter base class.
Additional Capabilities
WML devices expose additional capabilities that can be used to alter rendering. These capabilities are accessible through the HasCapability method of the MobileCapabilities class.