Device-Specific Rendering

  • Article

Although ASP.NET mobile Web Forms pages can render to a variety of devices automatically, they also provide multiple means to specify content specific to a device or a class of devices. This means that mobile Web Forms pages allow the developer to customize a page to take advantage of particular features of a device. For example, a common implementation requirement is to explicitly render items differently on different devices. The ASP.NET handles a lot of implicit formatting appropriate for rendering on a variety of device types. However, the developer must make a specific effort to ensure that the ASP.NET allows one string to be specified as a label on one device and a different string to be specified as a label on another device.

To manage such scenarios, 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 Forms application for specific types of devices, define a set of device filters for the application, and then specify the filter for each type of device within a <DeviceSpecific><Choice> construct.

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, the associated .ascx file, or the name of a valid device filter defined in the <deviceFilters> section 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 on the page or user control. If it does not exist, the <deviceFilters> section of the Web.config file is checked.

Using Device Filters to Extend the MobileCapabilities Class

Device filters are added to the device filters configuration section of the Web.config file. By adding your own device filters to this configuration section, 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, often 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 considered to be equal. 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 configuration file, you add them to the System.Web section of the file. To view the syntax, see the <deviceFilters> element. The syntax specifies both types of filters. The first filter shows the comparison-based filter; the second filter shows the evaluator-delegate-based filter. The following code provides a view of the syntax that you would use.

<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 during 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 IsPDA filters.

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 defined in the Web.config file.

<DeviceSpecific>
    <Choice Filter="IsColor" ImageUrl="colorImg.gif"/>
</DeviceSpecific>

Using the Device-Specific/Choice Construct

A <DeviceSpecific> element is the outermost container for <Choice> elements. This 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 might contain only a single <DeviceSpecific> element.

  • The <DeviceSpecific> element and the <Choice> element allow you to specify a set of values from which ASP.NET chooses, based on characteristics of the incoming device. The values of the choices are strings.

The <DeviceSpecific> control is merely 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 requested 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 picked by default.
  • Additional properties that override properties of the parent control.
  • Template definitions for the control.

ASP.NET chooses which <Choice> element to use by going through each specified choice in order, and evaluating the filter specified by the filter name. If the filter matches the current target device (by evaluating to true), the choice is picked. The control then applies any property overrides specified in the choice, and can use any templates defined in rendering.