<Choice> Element (.NET Framework Developer's Guide ) 

Provides a single choice among a set of choices in a <DeviceSpecific>/<Choice> construct. During rendering, one of the choices within a <DeviceSpecific> element is selected based on characteristics of the target device.

A <Choice> element can include any number of templates. If a <Choice> element includes templates, it can be used as a template set. For details, see Template Sets and Templated Controls.

The <Choice> element can also include properties that override properties of the parent control or style. The following types of properties can be overridden:

• Any property that can be declaratively set to a literal value, except for the ID and runat attributes. Properties that are set to objects, such as DataSource properties of controls, cannot be set.

• Any event handler property. The override event handler adds to any existing event handlers, but does not replace them.

• Any custom attribute. Any property that is not recognized is stored as a custom attribute, if the page allows custom attributes to be defined for controls.

  Note

  The default choice should always be the last choice in a device selection (otherwise choices appearing after the default choice will never be evaluated, because the default choice will always be selected). You can declare any number of additional attributes within a <Choice> element. This provides a way to set properties of the containing control on a device-specific basis. When a <Choice> element is selected for a control, each of these additional attributes is used to override the corresponding property of the containing control.

<Choice Filter="deviceFilterName"
    Other attributes here.>
        templates
</Choice>

Properties

Property	Description
Filter	Specifies the device filter to evaluate. If this property is omitted, the choice is selected by default.
Contents	Returns the overridden properties defined for a choice. Changing this collection after overridden properties have been processed (in OnDeviceCustomize will have no effect.
HasTemplates	Returns true if the <Choice> element has any templates defined; otherwise, returns false.
Templates	Returns the template set defined for a <Choice> element.
Xmlns	Used by the designer to determine the type of markup inside templates of a <Choice> element. Not intended for general developer use.

The filter name must be the name of a method on the page or in 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 have the following signature:

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 evaluating the <Choice> element, a check is made to determine whether a method of the appropriate signature exists on the page. If not, the <deviceFilters> section of the Web.config file is checked.

For more information about device filter evaluation, see Device-Specific Rendering and the documentation for the Filter property.

For a detailed example, see the Filter property.

<DeviceSpecific>
  <Choice Filter = "isHTML32">
    <HeaderTemplate>
      <mobile:Image runat=server ImageUrl="defaul1.gif" />
    </HeaderTemplate>
  </Choice>
  <Choice Filter="prefersWBMP">
    <HeaderTemplate>
      <mobile:Image runat="server" ImageUrl="default1.wbmp" />
        Wbmp Image<br />
    </HeaderTemplate>
  </Choice>
</DeviceSpecific>

See Also

Reference

<deviceFilters>

Concepts

Device-Specific Rendering
Device Template Support
Template Sets and Templated Controls