Building Microsoft ASP.NET Applications for Mobile Devices, Second Edition [Electronic resources] نسخه متنی

Chapter 19.) To find the precise values that are assigned to MobileCapabilities object properties for a particular device, you could search these files. However, an easier method is to write a simple test application that writes MobileCapabilities properties to the screen, and call the application from the device that you are investigating.

Using Properties of the MobileCapabilities Class

The MobileCapabilities class has many properties, several of which are primarily of interest to developers writing custom controls. For a complete reference to all the properties of the MobileCapabilities class, refer to the online documentation for the ASP.NET mobile controls or MSDN. Table 9-1 describes the properties you'll most likely use with device filters.

The Request property of the MobilePage class exposes a System.Web.HttpRequest object, which is constructed on every client request. The Browser property of the HttpRequest object exposes the MobileCapabilities object for the current request. Consequently, you can test properties of the MobileCapabilities object in code, as shown here:

MobileCapabilities capabilities = (MobileCapabilities)Request.Browser;
if (capabilities.ScreenPixelsWidth > 120)
{
// Code for larger screens
}
else
{
// Code for smaller screens
}

In Microsoft Visual Basic .NET, use the CType function to cast the Request.Browser property to the correct type:

Dim capabilities As MobileCapabilities
capabilities = CType(Request.Browser, MobileCapabilities)

Defining Device Filters

To use DeviceSpecific/Choice constructs within your mobile Web Forms page, you must define device filters to test properties of the MobileCapabilities object. You define device filters in your application's Web.config file, in the <deviceFilters> section. Each <filter> element defines a device filter. Here's the syntax you use to define device filters:

<system.web>
<deviceFilters>
<filter
name="filterName"
compare="capabilityName" 
argument="comparisonString"/>
<filter
name="filterName"
type="className"
method="methodName"/>
</deviceFilters>
</system.web>

As you can see, two forms of the <filter> child element exist. The first form is a comparison evaluator, which compares a string to a property of the MobileCapabilities object for simple equality. The attributes have the following meaning:

nameThe name of the device filter. Note that device filter names are case sensitive. For example, isHTML and IsHTML denote two different device filters.

compareThe property of the MobileCapabilities object to test.

argumentThe comparison string.

The second form is an evaluator delegate, which references a custom evaluator that you must write and place in a .NET assembly to which your application contains a reference. The attributes have the following meanings:

nameThe name of the device filter. Note that device filter names are case sensitive.

typeThe class name and assembly name where the custom evaluator is defined—for example: mynamespace.myclass, myassemblyname.

methodThe name of the static method that performs the capability evaluation.

Defining simple comparison evaluator filtersComparison evaluators don't require any additional code; you can define the evaluation entirely in the <deviceFilter> element. For example, to add a device filter that tests whether a device supports HTML version 3.2, you add the following code to Web.config:

<system.web>
<deviceFilters>
<filter name="isHTML32" 
compare="PreferredRenderingType" 
argument="html32">
</filter>
</deviceFilters>
</system.web>

This code defines a device filter named isHTML32, which tests the PreferredRenderingType property of the MobileCapabilities object for equality with html32. You use this filter within a DeviceSpecific/Choice construct. You can also use a comparison evaluator in code, using the HasCapability method of the MobileCapabilities object, as the following code demonstrates. Be aware that you don't use the second parameter of the HasCapability method with comparison evaluators.

MobileCapablities cap = (MobileCapabilities)Request.Browser;
if ((cap.HasCapability ("isHTML32", null))
{
// Do something.
}

Defining custom evaluator delegate filtersIf you want a device filter that performs a more sophisticated evaluation than simply testing a property of the MobileCapabilities object for a particular value, you can write an evaluator delegate. You write the evaluation logic in a static method (Shared in Visual basic .NET) that you create in an assembly that's accessible to your application.

The evaluator method takes the following form:

public static bool MethodName
(System.Web.Mobile.MobileCapabilities capabilities, String param)

The second parameter is optional, and you can use it as additional input to your capability evaluator method.

In the Web.config file, you can reference evaluator delegate filters using the second form of the <filter> element. For example, this is how you create a device filter named isMMEonSony that uses a custom capability evaluator method named MMEandSony in the MyClass class within the namespace MyNameSpace in the MyEvaluators.dll assembly:

<system.web>
<deviceFilters>
<filter name="isMMEonSony"
type="MyNameSpace.MyClass, MyEvaluators.dll"
method="MMEandSony">
</filter>
</deviceFilters>
</system.web>

This configuration sets the type attribute to the fully qualified name of the class: namespace.method, assembly. The method attribute names the actual method that the runtime will call.

Using an evaluator delegate from a DeviceSpecific/Choice construct is no different from using a simple comparison evaluator, as this next code snippet illustrates:

<mobile:Form id="Form1" runat="server">
<mobile:Label id="Label1" runat="server"
Text="Client is NOT MME on Sony">
<DeviceSpecific>
<Choice Text="Client is MME on Sony" 
Filter="isMMEonSony">
</Choice>
</DeviceSpecific>
</mobile:Label>
</mobile:Form>

You can also employ the MobileCapabilities.HasCapability method to use an evaluator delegate within code. Doing so enables you to use the extra parameter of the custom evaluator method, which you can't do when using this kind of evaluator in a DeviceSpecific/Choice construct. Here's the syntax:

if (((MobileCapabilities)Request.Browser).HasCapability(
"isMMEonSony", 
"Some Useful Client Information"))
{
// Do something.
}

A good way to use the second parameter is to pass information known about the client device that the properties of the MobileCapabilities object don't specify. The System.Web.HttpRequest object that's accessed through the Page.Request property contains properties for other information that the client device passes to your application in HTTP headers. For example, Request.UserLanguages returns a string array containing the preferred content languages. If you write an evaluator delegate named PrefersFrench, you can call it from your code, passing the first item in the UserLanguages array associated with this client. The following code demonstrates this technique:

if (((MobileCapabilities)Request.Browser).HasCapability (
"PrefersFrench", 
Request.UserLanguages[0]))
{
// Display content in French.
}

Example of an evaluator delegate filterThe example application in this section targets HTML browsers on devices with larger screens, such as the Pocket PC, and HTML browsers on devices with small screens, such as i-mode devices or phones with Microsoft Mobile Explorer. The application also targets WML browsers on small and larger screen devices, such as the Ericsson R380. The application uses custom evaluators to select the most appropriate graphics file to send to the requesting device. Each graphic has four versions: a small GIF, a large GIF, a small WBMP, and a large WBMP. The application must categorize each device that accesses it according to its image file requirements. In doing so, the application requires four device filters:

UsesLargeGIFTrue if the device supports GIF files and has a larger screen

UsesSmallGIFTrue if the device supports GIF files and has a smaller screen

UsesLargeWBMPTrue if the device supports a Wireless Application Protocol (WAP) bitmap file and has a larger screen

UsesSmallWBMPTrue if the device supports WAP graphics and has a smaller screen

The code to implement these capability evaluators uses two properties of the MobileCapabilities object: PreferredImageMime and ScreenPixelsWidth. To create the assembly for these evaluators, open Visual Studio .NET and follow these steps to create a new project:

In the New Project window, select Class Library as the project type. Type a suitable project name, such as MyEvaluators, and then click OK.

The Visual Studio .NET IDE opens the code for the class module. Delete the constructor Class1; you don't need this method because the class will contain only static methods. Give the class declaration a more meaningful name, such as CustomEvals.

The methods you define take a MobileCapabilities object as a parameter. You must add a reference to the new project so that the appropriate assemblies containing the MobileCapabilities class are accessible. Right-click References in Solution Explorer, and then click Add Reference. Select the .NET pane, locate the ASP.NET mobile controls assembly (System.Web.Mobile.dll) in the list, and double-click to select it.

As the MobileCapabilities object descends from the System.Web.HttpBrowserCapabilities object, which is found in the System.Web .NET assembly, you must also add a reference to that assembly. Locate System.Web.dll in the list and double-click it to select that assembly too. Click OK to close the window.

At the top of the class module, add the statement using System.Web.Mobile; so that you don't need to enter the full class definition for the MobileCapabilities class when you use it in your code. Now define the methods so that the module mirrors the one in Listing 9-1.

Listing 9-1: Source file CustomEvals.cs in sample MyEvaluators

using System;
using System.Web.Mobile;
namespace MSPress.MobWeb.MyEvaluators
{
/// <summary>
/// Custom Device Capability Evaluators
/// </summary>
public class CustomEvals
{
public static bool UseSmallGif(
MobileCapabilities caps, 
String notused)
{
bool retval = false;
if (caps.PreferredImageMime == "image/gif" && 
(caps.ScreenPixelsWidth < 100))
retval = true;
return retval;
}
public static bool UseLargeGif(
MobileCapabilities caps, 
String notused)
{
bool retval = false;
if (caps.PreferredImageMime == "image/gif" && 
!(caps.ScreenPixelsWidth < 100))
retval = true;
return retval;
}
public static bool UseSmallWBMP(
MobileCapabilities caps, 
String notused)
{
bool retval = false;
if (caps.PreferredImageMime == "image/vnd.wap.wbmp" && 
(caps.ScreenPixelsWidth < 100))
retval = true;
return retval;
}
public static bool UseLargeWBMP(
MobileCapabilities caps, 
String notused)
{
bool retval = false;
if (caps.PreferredImageMime == "image/vnd.wap.wbmp" && 
!(caps.ScreenPixelsWidth < 100))
retval = true;
return retval;
}
}
}

Compiling this code sample creates an assembly named MyEvaluators.dll, located in the /bin/debug directory of your project. To use these evaluators in a project, create a new project in Visual Studio .NET, like so:

Create a new project of type ASP.NET Mobile Web Application.

To use the new capability evaluators, you must add a reference to the assembly containing them to the project. Right-click References in Solution Explorer as you did before, but this time click Browse in the Add Reference window. Browse to the MyEvaluators.dll assembly that you just created, and click Open to select it. After you click OK, the MyEvaluators assembly is added to your project references, as Figure 9-1 shows.

Figure 9-1: MyEvaluators in the References window of a new Visual Studio .NET project

Now open Web.config, and enter device filter definitions to access the custom capability evaluator methods. Enter these definitions after the device filters supplied by Visual Studio .NET, as shown here:

<deviceFilters>
 
<filter name="UseLargeGIF"
type="MyEvaluators.CustomEvals,MyEvaluators"
method="UseLargeGif" />
<filter name="UseSmallGIF"
type="MyEvaluators.CustomEvals,MyEvaluators"
method="UseSmallGif" />
<filter name="UseLargeWBMP"
type="MyEvaluators.CustomEvals,MyEvaluators"
method="UseLargeWBMP" />
<filter name="UseSmallWBMP"
type="MyEvaluators.CustomEvals,MyEvaluators"
method="UseSmallWBMP" />
</deviceFilters>

The final step is to reference the device filters from within DeviceSpecific/Choice constructs in the mobile Web Forms page. In this example, you don't use the UseLargeGIF evaluator method because it's the default choice that applies if none of the other device filters returns true, as this code illustrates:

<mobile:Form id="Form1" runat="server">
<mobile:Image id="Image1" runat="server">
<DeviceSpecific>
<Choice Filter="UseLargeWBMP" ImageUrl="LargePic.wbmp"
AlternateText="Large WBMP">
</Choice>
<Choice Filter="UseSmallWBMP" ImageUrl="SmallPic.wbmp"
AlternateText="Small WBMP">
</Choice>
<Choice Filter="UseSmallGIF" ImageUrl="SmallPic.gif"
AlternateText="Small GIF">
</Choice>
<Choice ImageURL="LargePic.gif"
AlternateText="Large GIF">
</Choice>
</DeviceSpecific>
</mobile:Image>
</mobile:Form>

You can find this application in the sample ExampleUsingCustomEvaluators in the companion material on the book's Web site.

Defining Device Filters Using Visual Studio .NET Tools

The syntax for DeviceSpecific/Choice constructs and device filters described up to now in this chapter assumes that you're typing the syntax directly into the mobile page using the HTML view in Visual Studio .NET or editing the Web.config file directly. However, the Mobile Internet Designer provides graphical tools for defining device filters and DeviceSpecific/Choice constructs that you can use instead of editing the source files directly.

Creating and applying device filtersYou can access the Applied Device Filters dialog box by clicking on any mobile control in a form to select it and then clicking the ellipsis (…) button in the (Applied Device Filters) property shown in the Properties window. This tool's primary purpose is to apply device filters to the control whose properties you're editing. However, this editor also allows you to define new device filters. Any new device filter definitions you create apply to the whole application and are available for use with any control. The runtime stores these new device filters in the application's Web.config file.

Figure 9-2 shows how the Applied Device Filters dialog box will look.

Figure 9-2: Using the Applied Device Filters dialog box

The Available Device Filters drop-down list displays all existing device filters that you haven't yet applied to the control whose properties you're editing. The Applied Device Filters list at the bottom of the dialog box shows the filters that you've applied to the control.

To create new device filters, click the Edit button. The Device Filter Editor dialog box will appear as shown in Figure 9-3. In this dialog box, you'll see a list of existing device filters. When you select a comparison evaluator item in the list, the attributes of the filter will be displayed in the Compare box and the Argument text box.

Figure 9-3: Equality comparison in the Device Filter Editor

To add a new comparison evaluator, follow these steps:

Click the New Device Filter button.

Type the name of your evaluator in the new list entry.

Select Equality Comparison as the Type choice.

In the Compare box, type or choose the property of the MobileCapabilities class that you want to compare with the value in the Argument text box.

Enter the Argument value. The comparison evaluator will return true when the specified property of a MobileCapabilities object equals this value.

The procedure to create a new evaluator delegate is the same, except instead of typing the comparison property and argument, you type values for the type of class that contains your evaluator and the name of the actual evaluator method. For the UseLargeGIF evaluator described earlier in this section, you'd type MyEvaluators.CustomEvals,MyEvaluators for the type and UseLargeGif for the method. After you've defined all the device filters you need for your application, apply them to each control on which you want to implement property overrides. Any new device filters you've defined will appear in the Available Device Filters drop-down list.

Applying a Device Filter to a ControlIn the Applied Device Filters dialog, select the device filter you want to apply to a control, and click Add To List to move the filter to the Applied Device Filters list box. Then use the up and down arrows to set the required order of evaluation. The device filter named (Default) is the default choice and will always return true. Therefore, (Default) should go at the bottom of your list. If you don't have a default choice, the properties that you specify directly in the control will provide the default settings when no <Choice> elements return True. Figure 9-4 shows the applied device filters for a Label control. This figure specifies that three device filters should apply to this control. The <Choice> elements will be evaluated in this order: isHTML32, isWML11, (Default).

Figure 9-4: Device filters applied to a control prior to defining property overrides