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

  • Article

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 runatattributes. 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.

Description

For a detailed example, see the Filter property.

Code

<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