Device-Specific Rendering
Although ASP.NET mobile Web pages can render to a variety of devices automatically, they also provide ways for you to specify content specific to a device or a class of devices. This means that mobile Web pages allow you to customize a page to take advantage of particular features of a device. For example, a common requirement is to render items differently on different devices. ASP.NET handles much of the implicit formatting appropriate for rendering on a variety of device types. However, if needed, you can have ASP.NET render a label using one string on one device and a different string on another device.
To manage such scenarios, you include code in the application to set the properties of the controls depending on the results of device capabilities queries. To customize a mobile Web page for specific types of devices, you define a set of device filters for the page and then specify the filter for each type of device using a <DeviceSpecific><Choice> construct.
Note
The default Visual Studio mobile configuration file contains a variety of predefined device filters. ASP.NET 2.0 does not automatically generate mobile device filters by default. However, if you migrate your Web application from a previous version of ASP.NET to ASP.NET version 2.0, your device filters will be maintained in the Web.config file.
Using the Filter Property
Use the Filter property to evaluate device filters against device capabilities, or to set specific filters.
The filter name must be the name of a method on the page or associated .ascx file, or the name of a valid device filter defined in the <deviceFilters> element of the Web.config file. If a method name is specified with the Filter property, that method must match the following prototype:
public bool methodName(
System.Web.Mobile.MobileCapabilities capabilities,
String optionalArgument);
For example, if the Filter property is set to myChoiceMethod, a method with the following signature must exist.
public bool myChoiceMethod(
System.Web.Mobile.MobileCapabilities capabilities,
String optionalArgument
);
When ASP.NET evaluates the Choice element, it checks whether a method of the appropriate signature exists in the page or user control. If it does not exist, ASP.NET checks the <deviceFilters> element of the Web.config file.
Using Device Filters to Extend the MobileCapabilities Class
By adding your own device filters to the Web.config file, you can extend the MobileCapabilities class. Configuring the device filters provides an evaluation mechanism for two types of filters: a comparison-based filter and an evaluator-delegate-based filter.
Comparison-Based Filters
The comparison-based filter makes basic comparisons, generally based on a Boolean argument. For this type of filter, you provide the name of a capability and the value that you want the filter to compare. At run time, the evaluator succeeds if the capability value and the value that you provide are equal. The compared Boolean properties are case-insensitive, so true and True are equivalent. Other compared properties are case-sensitive.
Evaluator-Delegate-Based Filters
For more complex evaluation, you can specify an evaluator-delegate-based filter by providing the class and method name of a method. At run time, the method that you provide is called to test the evaluator. You must write and compile your own method to test the evaluator. Alternatively, you can define a method in your page or user control, and then reference it directly from the filter attribute, as described previously.
Web.config File Syntax
When specifying device filters in the Web.config file, you add them to the <system.web> section. To view the syntax, see <deviceFilters>. The syntax applies to both types of filters. In the following example, the first filter shows the comparison-based filter, and the second filter shows the evaluator-delegate-based filter:
<system.web>
<deviceFilters>
<filter
name="capability"
compare="capabilityName"
argument="argument" />
<filter
name="capability"
type="className"
method="methodName" />
</deviceFilters>
</system.web>
The MobileCapabilities object evaluates these filters at run time. Each device filter specifies an evaluation condition based on capabilities of the device. The sets of devices targeted by device filters are usually not discrete; for example, many devices can match both the IsColor and IsPDAfilter attributes.
Note
Device filter names are case-sensitive.
Within the <DeviceSpecific><Choice> construct, you specify the values for these filters. For example, the following code accesses the IsColor filter attribute defined in the Web.config file.
<DeviceSpecific>
<Choice Filter="IsColor" ImageUrl="colorImg.gif" />
</DeviceSpecific>
Using the Device-Specific/Choice Construct
The <DeviceSpecific><Choice> construct is the core construct for inserting device-specific markup in a page. To add device-specific markup for a control, you add the <DeviceSpecific> element as a child of the control. A control may contain only one <DeviceSpecific> element.
The <DeviceSpecific> element and the <Choice> element enable you to specify a set of values from which ASP.NET chooses, based on characteristics of the requesting device. The values of the choices are strings.
The <DeviceSpecific> element is an outer container for holding a number of choices, as shown in the following example:
<mobile:Image runat=server ImageURL="bw.gif">
<DeviceSpecific>
<Choice Filter="isColor" ImageURL="colorImg.gif"
AlternateText="This device cannot display the image." />
<Choice Filter="isWML11" ImageURL="myImage.wbmp" />
<Choice ImageURL="monoImage.gif" />
</DeviceSpecific>
</mobile:Image>
Filters such as isColor must have corresponding entries in the Web.config file or must exist as methods on the page or user control, as described previously.
Using the Choice Element
Choices are placed inside a <DeviceSpecific> element, and represent device characteristic/value pairs, where the device characteristic is drawn from a number of sources. Choices are evaluated in the order that they appear in the DeviceSpecific/Choice construct.
Although a control can contain only one <DeviceSpecific> element, you can add any number of <Choice> elements within a <DeviceSpecific> element. Each <Choice> element can contain the following:
A filter name, which specifies the device filter to evaluate. If the filter name is omitted, the choice is selected by default.
Additional properties that override properties of the parent control.
Template definitions for the control.
ASP.NET selects the <Choice> element to use by going through each choice in order and evaluating the filter specified by the filter name. If the filter matches the current target device (by evaluating to true), that choice is selected. The control then applies any property overrides specified in the choice, and can use any templates defined in rendering.