<Choice> Element

  • 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 runat attributes. Properties that are set to objects, like DataSource properties of controls, cannot be set.
  • Any event handler property. The override event handler adds to any existing event handlers, but doesn't 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 select selection (otherwise choices appearing after the default choice will never be evaluated because the default choice will always be selected).

Device-Specific Attributes

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.

Mobile Controls Syntax

Required properties and code-featured elements are noted in boldface type.

<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 picked 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. Returns false if not.
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. 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 Web.config. If a method name is specified with the Filter property, then that method must match the prototype:

public bool methodName(System.Web.Mobile.MobileCapabilities capabilities,
   String optionalArgument)

For example, if the Filter property was set to myChoiceMethod, then 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 Web.config is checked.

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

Example

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

Device Template Support | Template Sets and Templated Controls