Controls and Attributes Specific to Mobile Devices





Controls and Attributes Specific to Mobile Devices

As you saw at the start of this chapter, most of the ASP.NET server controls within version 2.0 of the .NET Framework can modify their output to suit different types of devices. So the techniques for using the controls that you saw in this and earlier chapters are identical when building pages targeted at mobile devices. However, several controls are specific to mobile devices—in particular, devices that have built-in phone capabilities. These controls consist of

  • The ContentPager control, which works as part of the underlying page architecture to divide pages into separate sections for small-screen and mobile devices

  • The PhoneLink control, which can be used in phone-enabled devices to initiate a phone call to a specified number

  • The SoftKeyLabel attribute, which is added to most of the controls to allow the developer to provide better soft-key support for mobile devices such as cellular phones

The MultiView and View controls were also originally designed to provide better small-screen device support, though they are often used in pages targeted at other types of browsers as well.


We'll look at each of these controls and attributes next to see what they do and how they are used. Also remember that some of the standard ASP.NET 2.0 controls from the WebControls namespace are specifically designed to better support mobile and WML-based devices such as cellular phones, in addition to the other new features they offer aimed at traditional client devices.

  • The new DynamicImage control will automatically convert images into the correct .wbmp format for cellular phones.

  • The Table, GridView, FormView, and DataGrid controls now automatically provide two different modes for viewing the content when sent to a mobile device: summary view and details view.

The ContentPager Control

Although the ContentPager control can be used in pages that target any type of browser or other client device, it is generally most useful for small-screen devices. These devices, particularly mobile phones, have extremely limited memory capacity and a slow bandwidth connection, so it is good practice to minimize the amount of content sent to the device for each "screen" (or page) displayed.

One way to minimize the content when there is a lot of information to display is to separate it into individual pages and provide Next and Previous buttons so that the user can navigate from one page to the next. However, this often involves considerable extra coding. In ASP.NET 2.0, the new ContentPager control can handle all the issues of creating the appearance of separate pages from a single source page.

The ContentPager control is placed within an ASP.NET page and its ControlToPaginate property set to the id of a container control on the page (which must have the runat="server" attribute). A common approach is to use the ContentPager control to paginate the contents of a <form>. In Listing 10.38, the <form> contains eight <div> controls. Each <div> contains one or more child controls.

Using a ContentPager Control with a <form>

...

<form  runat="server">



  <div runat="server">

    <asp:Label Text="Name:" runat="server" />

    <asp:Textbox  runat="server" />

  </div>

  <div runat="server">

    <asp:Label Text="Phone:" runat="server" />

    <asp:Textbox  runat="server" />

  </div>

  <div runat="server">

    <asp:Label Text="Email:" runat="server" />

    <asp:Textbox  runat="server" />

  </div>

  <div runat="server">

    <asp:Label Text="Address:" runat="server" />

    <asp:Textbox  runat="server" />

  </div>

  <div runat="server">

    <asp:Label Text="City:" runat="server" />

    <asp:Textbox  runat="server" />

  </div>

  <div runat="server">

    <asp:Label Text="State:" runat="server" />

    <asp:Textbox  runat="server" />

  </div>

  <div runat="server">

    <asp:Label Text="Zip:" runat="server" />

    <asp:Textbox  runat="server" />

  </div>

  <div runat="server">

   <asp:Button Text="Submit" runat="server" />

  </div>

  <asp:ContentPager  ControlToPaginate="MyForm"

                    ItemsPerPage="3" runat="server" />



</form>

...


After the code for the Submit button comes the declaration of the ContentPager control. The ControlToPaginate attribute specifies the <form> as the container control, whose content (the controls that are direct children of the container being paginated) will be divided into separate pages. The number of controls that will appear on each page is controlled by the ItemsPerPage property, here set to 3 using the ItemsPerPage attribute.

That's all you need to do to provide pagination of the output. In a browser and in a mobile device, the output now consists of three separate screens, with the Next and Previous buttons displayed automatically at the appropriate times. Figure shows the results in a mobile device emulator, and Figure shows the same page viewed in Internet Explorer.

19. The ContentPager control viewed in a mobile device emulator

graphics/10fig19.gif


20. The ContentPager control viewed in Internet Explorer

graphics/10fig20.gif


We see three screens because ItemsPerPage specifies the maximum number of top-level controls, within the pageable control, that are to be displayed for each screen or page. The <div> controls wrap the individual Label, TextBox, and Button controls so that they are not individually paged. Therefore, we get three Label controls and three TextBox controls for screens 1 and 2, and a Label, TextBox, and Button for screen 3.

You can also put more than one ContentPager control on a page if you wish. This might be useful if you want the Next and Previous links to appear at the top and bottom of the list—you just insert them into the page at the points you want their output to appear. Note that you must set their ItemsPerPage attributes to the same value.

Displaying Numeric Navigation Links

Alternatively, you can force the ContentPager control to display a list of all the available page numbers as hyperlinks so that users can jump directly to any one of them. All that's required is to add the Mode attribute with the value NumericPages:






<asp:ContentPager  ... Mode="NumericPages" />


Figure shows how this looks in Internet Explorer, and the result is much the same in a mobile device. As you can see from the screenshot, the page numbers show the "proper" values, indexed from 1.

21. Displaying the page numbers as hyperlinks

graphics/10fig21.gif


To control how many page numbers are displayed in this mode, change the PageButtonCount property from its default of 10. The usual format of three dots after the last page number shown (or before the first one) signifies that there are more pages available:

0 1 2 3 4 5 6 ...

or

... 7 8 9 10 11 12


You can also set the Mode property at runtime to a value from the PagerButtons enumeration. The values available are NextPrevious, NextPreviousFirstLast, Numeric, and NumericFirstLast (which displays the text links First and Last with the individual page number links between them). You can also change the text of the links by setting the FirstPageText, PreviousPageText, NextPageText, and LastPageText attributes or properties to the required String values, or use your own images by setting the FirstImageUrl, PreviousImageUrl, NextImageUrl, and LastImageUrl attributes or properties. And, of course, you can style the output of the ContentPager control by using the PageStyle, ButtonStyle, and CurrentPageStyle properties.

Displaying Page Numbers

The ContentPager control exposes properties named CurrentPage and PageCount so you can easily indicate to users where they are in the set of pages by displaying these values. (The PageCount property is read-only, but you can set the CurrentPage property in code to force a specific page to be displayed.) The example in Listing 10.39 uses the ContentPager control to page the output from a DataList control. The ContentPager points to the DataList by using the ControlToPaginate="MyList" attribute and specifies there will be five items per page. Text links will be displayed, including the First and Last links. Finally, the OnPaginated attribute is included, specifying that the event handler named ShowPage will be executed when the ContentPager paginates the content of its associated control (Paginated is the only event exposed by the ContentPager control).

Paging a DataList Control with a ContentPager Control

<asp:DataList  runat="server">

  <ItemTemplate><%# Container.DataItem %></ItemTemplate>

</asp:DataList>



<asp:ContentPager  runat="server"

     ControlToPaginate="MyList" ItemsPerPage="5"

     Mode="NextPreviousFirstLast"

     OnPaginated="ShowPage" />



<asp:Label  EnableViewState="False" runat="server" />


Listing 10.40 shows the server-side code in this example page. The Page_Load event handler is responsible for populating the DataList with 21 entries when the page first loads. The ShowPage event handler, also shown in Listing 10.40, is responsible for displaying the page number and total number of pages as Page x of x. It does this by querying the CurrentPage and PageCount properties of the ContentPager control.

However, notice that the pages are numbered from 0—we add 1 to the value of the CurrentPage property in the code in Listing 10.40 so that it displays the page numbers as 1, 2, and 3 (which tends to be more intuitive for users). The screenshot in Figure shows the result.

Populating the DataList and Handling the Paginated Event

Sub Page_Load()

  If Not Page.IsPostback Then

    Dim aValue As New ArrayList()

    Dim iLoop As Integer

    For iLoop = 0 To 20

      aValue.Add("Item number " & iLoop.ToString())

    Next

    MyList.DataSource = aValue

    MyList.DataBind()

  End If

End Sub



Sub ShowPage(sender As Object, e As EventArgs)

  lblPageNum.Text = "Page " & MyPager.CurrentPage + 1 _

                  & " of " & MyPager.PageCount

End Sub


22. Displaying the page number and page count

graphics/10fig22.gif


Custom Paging

You can also choose to abandon the built-in pagination features and instead create build routines and UIs to suit your own specific requirements using templates. This technique does require more effort but allows you to exert full control over the process. The ContentPager control accepts a <PagerTemplate> declaration and can be wired up to separate controls in the template that will activate the Next and Back operations. Any control that exposes the CommandName property (e.g., Button, LinkButton, or ImageButton) is an ideal candidate. Listing 10.41 shows an example of the technique.

Custom Paging with a Pager Template

<asp:ContentPager ... runat="server">

  <PagerTemplate>

    <asp:Button Text="Previous" runat="server"

                CommandName="Previous" />

    <asp:Button Text="Next" runat="server"

                CommandName="Next" />

  </PagerTemplate>

</asp:ContentPager>


Simply set the CommandName attributes of the buttons to the same values as the NextPageCommandName and PreviousPageCommandName properties of the ContentPager control, and they will automatically cause the postback that moves to the next or previous page. The default values for the NextPageCommandName and PreviousPageCommandName properties of the ContentPager control are "Next" and "Previous", respectively, but you can change the values if you need to wire the buttons to different instances of the ContentPager control.

Page Weightings

So far, all the examples we've shown set a specific value for the ItemsPerPage property of the ContentPager control. This is fine if each item takes up roughly the same amount of vertical space on the page. However, if they don't, the lengths of the pages will vary even when each page contains the same number of items.

To get around this, the ContentPager control can use weightings to determine where the page breaks should occur. Page weightings are automatically used if you don't specify a value for the ItemsPerPage attribute when declaring the ContentPager control and don't set the ItemsPerPage property at runtime.

If the controls used within the container control implement the IPaginationInfo or IItemPaginationInfo interfaces, they can be assigned specific weightings for their Weight property. Otherwise, the ContentPager control uses the number of contained controls for each top-level item to work out the weightings. Then, taking into account the value of the container control's MaximumWeight property, the ContentPager control can calculate where to place the page breaks.

Keeping Child Controls Together

The IPaginationInfo interface exposes a property named PaginateChildren. When this is set to True (the default varies depending on the control type), the pagination process will break up the pages between the child controls of a top-level item. When set to False, all child controls are kept together for each top-level item in the container control that is being paginated. The Panel control is probably the most suitable server control to act as the parent container in this case. For plain HTML controls, the <div> control, as shown previously, also keeps child controls together.

The PhoneLink Control

One useful technique in voice-enabled devices such as mobile phones is to provide a link that dials a specified number when activated. A PhoneLink control to achieve this is part of the MMIT, and an equivalent is now part of the core control set in ASP.NET 2.0.

The PhoneLink control has a property named PhoneNumber, which specifies the number to be dialed when activated. It also supports the display and formatting properties that are standard for the controls that inherit from WebControl, plus the SoftKeyLabel attribute that we discuss in more detail in the next subsection.






<asp:PhoneLink  runat="server" SoftKeyLabel="Dial"

               PhoneNumber="123-456-7890" />


In a device that does not support voice calls, the control will usually just render the phone number in the page as text within an HTML anchor element:






<a  class="Normal">123-456-7890</a>


However, in a voice-enabled device, the output is a hyperlink that specifies the protocol wtai:, which initiates a voice call. Notice that the number in the href attribute below is prefixed with a special URL as well, which is used by the phone to make the connection, and the number has all non-numeric formatting characters removed:






<a href="wtai://wp/mc;1234567890">123-456-7890</a>


The result in a mobile device emulator is shown in Figure.

23. The PhoneLink control in a mobile device emulator

graphics/10fig23.gif


The SoftKeyLabel Attribute

Some of the interactive controls in the ASP.NET 2.0 WebControls namespace (mainly link and button controls) have the SoftKeyLabel attribute. This can be set programmatically or declaratively through the SoftKeyLabel attribute. The value is a String displayed by many mobile devices that have soft-key buttons (usually located just below the screen). It provides a useful hint to users about which button to press to activate or interact with the control.

As an example, the code in Listing 10.42 creates a page containing a HyperLink and a PhoneLink control. Both of these controls carry a definition of the SoftKeyLabel attribute.

Using the SoftKeyLabel Attribute

<%@ Page Language="VB" %>

<html>

<head>

  <style>

    .Heading {font-family:Arial; font-size:xsmall; font-weight:bold}

    .Normal {font-family:Arial; font-size:xsmall}

  </style>

</head>

<body>

  <form runat="server">



    <asp:HyperLink cssClass="Normal"  runat="server"

      Text="Next Page" NavigateUrl="nextpage.aspx"

      SoftKeyLabel="Next" />



    <br />



    <asp:PhoneLink cssClass="Normal"  runat="server"

      PhoneNumber="123-456-7890" SoftKeyLabel="Dial" />



  </form>

</body>

</html>


When viewed in a cellular phone, the value of the SoftKeyLabel is displayed above the soft-key button as each control receives the focus, making it easy to see what each one does. You saw this demonstrated in Figure when we discussed the PhoneLink control.


     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows