Writing a Custom Adapter

One significant difference in behavior between the mobile controls and the Web controls is their treatment of custom attributes. By default, custom attributes are not allowed on mobile controls. In this section, we’ll talk about the reasons behind this limitation and its impact on your work. We’ll also walk through the writing and configuration of your own custom adapter.

If you specify an attribute on the server control that isn’t recognized by the control, a System.Exception is thrown during the Load event, stating “Cannot set custom attributes on mobile controls in this page.” Web controls, however, do allow custom attributes, and do not throw an exception when loaded. Custom attributes are simply passed through to the browser as an attribute of the primary HTML tag rendered for a control. It is important to recognize the difference when using custom attributes with Web controls because you’re probably used to setting extra style attributes, or you might be using the FOR attribute to leverage client-side script. With the mobile controls, this will not work without extra effort on your part because unrecognized attributes are prohibited by default.

Because the validated WML and XHTML markup used by mobile browsers mandates strict compliance to their schemas, simply passing through unknown attributes is not safe. And given the differences between client-side scripting and supported attributes, there isn’t a reasonable way to translate many tags. The primary HTML tag rendered for a particular Web control typically doesn’t vary based on the browser issuing the request; HTML processors in browsers simply ignore the attributes they do not know. However, with adapted output, the tag used to represent a server element can vary from markup language to markup language.

For example, consider accessKey attributes, which are customized shortcut keys for selecting links. Users can find them particularly useful for making selections because they don’t need a mouse. Listing 4-5 shows how to use the accessKey in your code. It is a simple page with links to http://www.microsoft.com
/mspress and http://www.asp.net. The accessKey attribute is specified so that when the user selects the specified shortcut key, the link is accessed. However, notice that when you try requesting the page, the accessKey attribute causes a run-time error.

Code Listing 4-5: accessKey.aspx

 <%@ Page Inherits="System.Web.UI.MobileControls.MobilePage" %>
<mobile:form runat="server">
    <mobile:link runat="server" 
        NavigateUrl="http://www.microsoft.com/mspress" 
        AccessKey="m" 
        Text="(m) MSpress" />
<mobile:link runat="server" 
         NavigateUrl="http://www.asp.net" 
         AccessKey="p"
         Text="(p) ASP.NET" />
</mobile:form> 

Using Custom Attributes

To take advantage of custom attributes, you must modify the configuration so that errors aren’t thrown when you use the attributes with mobile Controls. In addition, you must make use of the new server control attributes in custom adapter code, because without them, the default adapters will simply ignore the unknown attribute.

Listing 4-6 is a web.config file that overrides the machine.config default and prevents the run-time errors that usually occur when unrecognized attributes are encountered. When you set allowCustomAttributes to true on the mobileControls element, you no longer encounter the errors.

Code Listing 4-6: Allowing Custom Attributes Web.config

 <configuration>
    <system.web>
        <mobileControls
            allowCustomAttributes="true" />
    </system.web>
</configuration> 

Tip

The AllowCustomAttributes configuration setting does not cause custom attributes to be passed through to the client. It only allows them to be specified in the server page without causing an error on the server. This setting applies only to the mobile controls where unrecognized attributes on the server controls are treated as an error by default.

Request AccessKey.aspx (shown in Listing 4-5) again and notice that including custom attributes no longer creates an error condition. However, pressing ALT+M or ALT+P doesn’t move the focus as expected. To get the desired effect, you can create an adapter that will use the accessKey setting. In this example, we’ll provide a new adapter for generating HTML. We create a new class that inherits from the HtmlLinkAdapter and overrides the AddAttributes method. The AddAttributes method is called during the Render method to handle any supported attributes. We will simply write the accessKey attribute if it is present. In Listing 4-7, we create a new link adapter that inherits from the HtmlLinkAdapter. It overrides the AddAttributes method to include support for the access key.

Code Listing 4-7: MyHtmlLinkAdapter.cs

 using System;
using System.Web.UI;
using System.Web.UI.MobileControls.Adapters;
 
public class MyHtmlLinkAdapter : HtmlLinkAdapter {
  protected override void
    AddAttributes(HtmlMobileTextWriter writer) {
    string attributeValue =
      ((IAttributeAccessor)Control).GetAttribute("accessKey");
        if(attributeValue != null && attributeValue != String.Empty){
          writer.WriteAttribute("accessKey", attributeValue);
        }
    }
} 

There is no built-in project type for Adapters in Visual Studio .NET, so you can create an empty workspace and compile the file after adding references to System.Web.Mobile.dll and System.Web.dll. From the command prompt, compile with this:

csc /r:system.dll,system.web.mobile.dll
    /t:library MyHtmlLinkAdapter.cs 

The resulting dynamic-link library (DLL) will be called MyHtmlLinkAdapter.dll and should be placed in the bin directory of your test virtual root. Now request AccessKey.aspx and notice that there are no errors, the ALT+P key combination moves the focus to the ASP.NET link, and ALT+M shifts focus back to the MSPress link. Granted, this example doesn’t get us anything spectacular—it just restores the use of one custom attribute that would have been passed through in a non-adapted page anyway. But it does illustrate how we can enable and use custom attributes in our own adapters while preserving the relative safety of not passing any arbitrary attributes through to a variety of browsers.