WML Adapter Set

The WML adapter set consists of classes that can be used to render ASP.NET mobile Web Forms pages on clients that support WML v1.1 or WML v1.2. Some methods and properties might not be included in this documentation. To view the source code, see Device Adapter Code.

The following table lists the core classes included in the WML adapter set.

The Openwave Up.Browser browsers use a different page adapter and text writer. The adapter set supporting these browsers uses the core classes listed in the following table.

Selection

The WML adapter set is selected if the PreferredRenderingType property of the MobileCapabilities class returns wml11 or wml12.

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:

1. Calls BeginResponse and BeginFile methods for the writer. Content type is text/vnd.wap.wml.
2. Writes out an opening <wml> tag.
3. Renders the active form.
4. Renders linked forms as part of the same WML deck, if possible.
5. Writes out a closing </wml> tag.
6. Calls EndFile and EndResponse methods.

The form adapter performs the following steps:

1. Sets the writer to analysis mode.
2. Calls the writer's BeginForm method.
3. Renders form contents. The results are not sent to the device, but are analyzed by the writer.
4. Calls the writer's EndForm method.
5. Sets the writer to live mode.
6. Calls the writer's BeginForm method.
7. Renders form contents.
8. 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 by using the paragraph formatting from a given style.
• TheEnterFormat and ExitFormat methods allow an adapter to emit markup to begin and end a block by 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 reference documentation on the WmlMobileTextWriter class.

Additionally, the WmlControlAdapter base class provides a number of higher-level methods, as shown in the following table. Each of these methods uses the writer methods previously mentioned for rendering.

Rendering Menus in User Interfaces (UIs)

On some WML-based devices, a form that consists of multiple links or anchors can be better rendered as a menu of items, by using a Select/Option construct (<select> and <option> tags), with automatically generated keypad navigation user interface (UI). The Openwave Up.Browser browsers are 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 in a Select/Option construct.

If the RendersWmlSelectsAsMenuCards property of the MobileCapabilities class is set to true, the device can render <select> tag constructs as menu cards, rather than as a combo box.

CanCombineFormsInDeck 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 Accepts

When a rendered form includes UI to submit the form results back to the server, some WML-based devices require that the UI for the specified device must be in the form of a <do> object at the start of the form. The Openwave Up.Browser browsers are an example of such a device.

When a device requires that the UI use a <do> object, the form adapter checks whether any of the controls on the form require submit UI, and whether any of the controls actually 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 a 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> construct as an inline button rather than as a softkey.

Secondary UI

The WML adapter set supports a concept called secondary UI. Secondary UI is used by controls that must show additional screens of a user interface, in the same way as a dialog box in a Windows-based application. To use secondary UI, a control adapter performs the following steps:

1. In response to some user interaction (usually in the overridable HandlePostBackEvent method), the control adapter sets the secondary UI mode to some internally known constant, by setting the SecondaryUIMode property of the WmlControlAdapter base class.
2. In rendering, the control checks whether it is in secondary UI mode, and uses that mode to render the appropriate secondary UI.
3. 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 ExitSecondaryMode method of the WmlControlAdapter base class.

Additional Capabilities

WML devices also expose additional capabilities that can be used to alter rendering. These capabilities are accessible through the HasCapability method of the MobileCapabilities class.

See Also

For more information, see the Device Capabilities Table.