<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>
| Property | Description |
|---|---|
| Specifies the device filter to evaluate. If this property is omitted, the choice is selected by default. | |
| Returns the overridden properties defined for a choice. Changing this collection after overridden properties have been processed (in OnDeviceCustomize will have no effect. | |
| Returns true if the <Choice> element has any templates defined; otherwise, returns false. | |
| Returns the template set defined for a <Choice> element. | |
| 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>