Professional ASP.NET 1.0 Special Edition- P40 pps

</go>

</do>

Alternatively, and particularly on the Openwave Simulator, a <select> list may be generated with an <option>
element allowing the command to be called, in much the same way as we saw for <mobile:Link>.

Note that the
ImageUrl property, which determines an image to display on a device if that device supports graphics,
works in the same way as the equivalent property of the
<mobile:Image> control, with device-specific rendering
supported in the same way.


Example Usage

The following code contains some text that changes when the
Press button is pressed:

<mobile:Form runat="server" id="first" Title="First">

<mobile:Label runat="server" id="result">

Button not pressed.

</mobile:Label>

<mobile:Command runat="server" id="button1" Text="Press"

SoftkeyLabel="Press" OnClick="button1_OnClick"/>

</mobile:Form>

<script runat="server" Language="VB">

Sub button1_OnClick(sender As Object, e As System.EventArgs)

result.Text = "Button pressed!"

End Sub

</script>

The button appears on various devices as follows:
Pocket PC:

Nokia 7110 (also accessible through the Options softkey):

Openwave Simulator (softkey also generated):


<mobile:TextBox>

This control enables user input. The output in all cases will be a text box, although the functionality of the WML rendition
of this varies significantly between browsers (see below).

It is possible to change the type of textbox displayed using the
Numeric and Password attributes. If both of these are
false we get a plain text box, setting Numeric to true gives a number only textbox, and setting Password to True
renders a password mode text box, where asterisks are written to the screen to prevent unwanted reading of passwords.

However, I personally think that the
Password type only causes confusion on mobile devices, as it makes the already
awkward text input even harder (it's easy to lose your place) and- to be honest- who's likely to read your password over
your shoulder on a tiny LCD screen?


Attributes
Attribute Description
MaxLength
The maximum number of characters allowed in the text box.
Numeric
true or false. Whether the text box is numeric.
Password
true or false. Whether the text box acts in password mode.
Size
The size of the control in characters.
Text
The text to output to the browser.

Events
Event Description
OnTextChanged
Occurs when the user modifies the text in the text box (and a post back is triggered).

Code Generated

For HTML and WML browsers (again, the syntax is identical):

<input name="id" [type="password"]/>

Example Usage

The following code uses text input for a simple login page:

<mobile:Form runat="server" id="first">

Enter name

<mobile:TextBox runat="server" id="name"/>

Enter password:

<mobile:TextBox runat="server" id="password" Password="true"/>

<mobile:Link runat="server" NavigateUrl="#second" Text="Login"

SoftkeyLabel="Login"/>

</mobile:Form>

<mobile:Form runat="server" id="second" OnActivate="second_OnActivate">

<mobile:Label runat="server" id="result"/>

</mobile:Form>

<script runat="server" Language="VB">

Sub second_OnActivate(sender As Object, e As System.EventArgs)

if ((name.Text = "Karli") AND (password.Text = "Cheese")) then

result.Text = "Welcome Karli!"

Else

result.Text = "Sorry, " & name.Text & ", your password is not " _

& "recognized."

End If

End Sub

</script>

The first form takes a name and password; the second displays the login result. This result is calculated by
frmSecond_OnActivate(), which is called when the name and password are submitted (or, more accurately, when
frmSecond is activated). The simple algorithm used simply checks if the name is "Karli" and the password is "Cheese",
else it displays a failure message.

It is worth noting another fairly major difference between browsers here. Although the code generated for different WAP
devices is very similar the user experience can vary a great deal. The Nokia 7110 browser looks similar to the Pocket PC
interface:


Here, selecting a field in the Nokia simulator takes you to a separate data entry screen, and when you return the fields are
updated.

However, the Openwave Simulator interface only allows a single input field to be displayed at a time:

When text is entered and the OK softkey is selected the display moves on to the password entry field, and finally to the
Login link. The end effect is the same, but the routes there can vary.


<mobile:List>

This control allows for simple non-interactive lists of items in plain text, a list of commands, or a list of links. Whatever you
want to do with this control you can specify the items it contains using
<Item> elements within the control, or
programmatically (using the exposed
Items collection). A very simple list, used for display only, might therefore look like
this:

<mobile:List runat="server">

<Item Text="Richard Anderson"/>

<Item Text="Brian Francis"/>

<Item Text="Alex Homer"/>

<Item Text="Dave Sussman"/>

<Item Text="Karli Watson"/>

</mobile:List>

Each of the <Item> elements may also have a Value property, which specifies a destination when link lists are used. To

obtain a link list we simply set the
ItemsAsLinks property to true:

<mobile:List runat="server" ItemsAsLinks="true">

<Item Text="Richard Anderson" Value="

<Item Text="Brian Francis" Value="

<Item Text="Alex Homer" Value="

<Item Text="Dave Sussman" Value="

<Item Text="Karli Watson" Value="

</mobile:List>

Alternatively, we can specify an event handler to execute when an item is selected using OnItemCommand, although this
won't work properly if
ItemsAsLinks is true.

The control also supports standard ASP.NET data binding.


Attributes
Attribute Description
DataMember
When databinding, this attribute specifies the table of a
DataSet to use.
DataSource

When databinding, this attribute specifies the data source to use.
DataTextField
When databinding, this attribute specifies the field to use for item text values.
DataValueField
When databinding, this attribute specifies the field to use for item-value values.
Decoration
None, Bulleted, or Numbered- allows for extra formatting of item text by adding bullet marks or
numbering items.
ItemCount
The amount of items to display when using pagination, where a value of 0 means to choose this value
automatically.
ItemsAsLinks
True or False. Whether to render items as links.
ItemsPerPage
The number of items to display per page when using pagination, where a value of 0 means to use the
default value.

Events
Event Description
OnItemCommand
Occurs when an individual list item generates a command event. Note that this won't work if
ItemsAsLinks is true.
OnItemDataBind
Occurs when an item is databound.
OnLoadItems
Occurs when pagination is being used and the items to display are requested.

Code Generated

Obviously, this control can generate varied code. For simple lists the output will be plain text, with appropriate line breaks,

or formatted as a table. Link lists will generate code appropriate to the device, such as
<select> fields or anchors. For
example, the code above generates the following HTML on a Pocket PC:

<table>

<tr>

<td>

<a href=" Anderson</a>

</td>

</tr>

<tr>

<td>

<a href=" Francis</a>

</td>

</tr>

<tr>

<td>

<a href=" Homer</a>

</td>

</tr>

<tr>

<td>

<a href=" Sussman</a>

</td>

</tr>

<tr>

<td>

<a href=" Watson</a>

</td>

</tr>

</table>

The WML generated on a Nokia 7110 is as follows:

<a href=" Anderson</a>

<a href=" Francis</a>

<a href=" Homer</a>

<a href=" Sussman</a>

<a href=" Watson</a>

and the WML generated on Openwave browsers is along the lines of:

<do type="accept" label="Go">

<go href="example.aspx?__ufps=631274647595414160" method="post">

<postfield name="__VIEWSTATE"

value="aDxfX1A7QDw7MmI1YjhiMTgtYWROGExOTg1LDA7Pjs+" />

<postfield name="__EVENTTARGET" value="ctrl0" />

<postfield name="__EVENTARGUMENT" value="$(ctrl0)" />

</go>

</do>

<select name="ctrl0">

<option onpick=" Anderson</option>

<option onpick=" Francis</option>

<option onpick=" Homer</option>

<option onpick=" Sussman</option>

<option onpick=" Watson</option>

</select>

Each of these pieces of code is entirely appropriate for the target device.

If we are generating a list of commands then appropriate post back code will also be generated.


Example Usage

As a quick example of a command list, consider the following modified code:

<mobile:Form runat="server" id="first">

<mobile:List runat="server" id="List1"

OnItemCommand="List1_OnItemCommand">

<Item Text="Richard Anderson"

Value="

<Item Text="Brian Francis"

Value="

<Item Text="Alex Homer"

Value="

<Item Text="Dave Sussman"

Value="

<Item Text="Karli Watson"

Value="

</mobile:List>

</mobile:Form>

<mobile:Form runat="server" id="second">

Follow this link for <mobile:Label runat="server" id="name"/> homepage:

<mobile:Link runat="server" id="homepage" Text="Link"

SoftkeyLabel="Link"/>

</mobile:Form>

<script runat="server" Language="VB">

Sub List1_OnItemCommand(sender As Object, _

e As System.Web.UI.MobileControls.ListCommandEventArgs)

name.Text = e.ListItem.Text & "'s"

homepage.NavigateURL = e.ListItem.Value

ActiveForm = second

End Sub

</script>

When the user selects an item from the list they are redirected to the second card by the command event handler, which
also provides a link to the homepage specified in the item
value attributes.


Note that we set the
ActiveForm property to the id of the target form without enclosing the id in double quotes.

<mobile:SelectionList>

This control is similar to
<mobile:List>, but has a few important differences. First, it doesn't support pagination.
Second, multiple item selection is permitted, aided by the fact that selecting individual items doesn't necessarily trigger

a postback. Third, it maintains a list of what items are selected. Finally, the UI is different.

There are two methods of accessing selected items. For single selection lists we can look at the
Selection and
SelectedIndex properties of the control. However, for multiple selection lists we must examine the Selected property
of each item in the
Items collection of the control.


Attributes
Attribute Description
DataMember
When databinding this attribute specifies the table of a
DataSet to use.
DataSource
When databinding this attribute specifies the data source to use.
DataTextField
When databinding this attribute specifies the field to use for item text values.
DataValueField
When databinding this attribute specifies the field to use for item value values.
Rows
For HTML and cHTML devices this attribute gets or sets the number of rows displayed in the selection
list.
SelectType
DropDown (the default), ListBox, Radio, MultiSelectListBox, or CheckBox. Determines the
rendering style.
Title
Text used for selection list title in some WML devices.

Events

Event Description
OnItemDataBind
Occurs when an item is data bound.
OnSelectedIndexChanged
Occurs when a post back is performed and the selected items have changed.

Code Generated

The code generated for this control varies a great deal from HTML output, to cater for the various input methods, although
for WML it is always a
<select> / <option> list. As a postback isn't generated by default we also need to add a method
of doing this manually, such as a button or link.


Example Usage

The following code generates a multiple selection check box list and displays the items selected when a
<mobile:Command> control is manipulated:

<mobile:Form runat="server" id="first">

<mobile:SelectionList runat="Server" id="List1" runat="server"

SelectType="CheckBox" Title="Authors">

<Item Text="Richard Anderson" />

<Item Text="Brian Francis" />

<Item Text="Alex Homer" />

<Item Text="Dave Sussman" />

<Item Text="Karli Watson" />

</mobile:SelectionList>

<mobile:Command id="nextForm" runat="server" SoftkeyLabel="Next"

Text="Next" onClick="nextForm_click"/>

</mobile:Form>

<mobile:Form runat="server" id="second">

Selected:

<mobile:Label id="names" runat="server"/>

</mobile:Form>

<script runat="server" Language="VB">

Sub nextForm_click(sender As Object, e As System.EventArgs)

Dim selectionCount As New Integer()

Dim item As MobileListItem

selectionCount = 0

names.Text = ""

For Each item In List1.Items

If item.Selected Then

If selectionCount <> 0 Then

names.Text += ", "

End If

names.Text += item.Text

selectionCount += 1

End If

Next

If selectionCount = 0 Then

names.Text = "None"

End If

ActiveForm = second

End Sub

</script>

Remember that we can only use the Selection and SelectedIndex properties of List1 to get info on single selection
lists, hence the
For Each loop in the previous code to interrogate all items in the list.

On the Pocket PC this is rendered as follows:

On the Openwave simulator it looks like:

The Nokia 7110 interface is slightly trickier to use and involves more steps, but it still works. One advantage, though, is
that the Title attribute is recognized and displayued:


There is plenty more you can do with this control, so have a play!


<mobile:ObjectList>

This control enables more complex lists to be defined, where each item is the visual representation of an object. This
representation may vary significantly between browsers.

This object enables a lot more flexibility- even in its default usage it allows the user to view additional object information.
We can also define multiple fields to view and commands to execute for items, leading to interesting possibilities, as we
will see when we look at an example in a moment. Due to this additional functionality, and the difference in rendering
when compared to simple lists, no selection attributes exist and items can only be defined by data binding. However, we
still have access to the
Selection and SelectedIndex properties of a list, which becomes important once a command
is executed for an item, as it allows us to tell which item generated the command.

Attributes
Attribute Description
AutoGenerateFields
True or False- If True (the default value) then object properties are automatically converted
into extra fields for each
ObjectListItem object that the list contains.
BackCommandText
Text used for
Back link.
DataMember
When data binding to a
DataSet this attribute specifies the table to use.
DataSource
This attribute specifies the data source to use.
DefaultCommand
The default command to execute for an item.
DetailsCommandText
Text used for
Details link.
ItemCount
The amount of items to display when using pagination, where a value of 0 means to choose this
value automatically.
ItemsPerPage
The number of items to display per page when using pagination, where a value of 0 means to
use the default value.
LabelField
The field to use for primary display purposes.
MoreText

Text used for
More link.
TableFields
The fields to display in table view, as a series of identifiers separated by semicolons.

Events
Event Description
OnItemCommand
Occurs when an individual list item generates a command event.
OnItemDataBind
Occurs when an item is databound.
OnItemSelect
Occurs when an item is selected.
OnLoadItems
Occurs when pagination is being used and user requests more data.
OnShowItemCommands
Occurs when the defined commands for an item are rendered.

Code Generated

The generated code can be quite involved, so it is better to look at examples.


Example Usage

To illustrate this object, let's expand the author list from the last section such that information about each author is stored
in an object. First of all, we need to define an author class:

<script runat="server" Language="VB">

Public Class author

Private authorName, authorInitials, authorFavoritefood As String

Public Sub New(ByVal name As String, ByVal initials As String, _

ByVal favoritefood As String)

authorName = name

authorInitials = initials

authorFavoritefood = favoritefood

End Sub

Public ReadOnly Property name() As String

Get

Return authorName

End Get

End Property

Public ReadOnly Property initials() As String

Get

Return authorInitials

End Get

End Property

Public ReadOnly Property favoritefood() As String

Get

Return authorFavoritefood

End Get

End Property

End Class

We can then populate the list control, itemList, with an array of author objects. The easiest place to do this is in the
Page_Load() event handler (although we only need to do this once, so we can check to see if there is a postback going
on):

Public Sub Page_Load(o As Object, e As EventArgs)

If (IsPostBack = False) Then

Dim authors As New ArrayList

authors.Add(new author("Richard Anderson", "RJA", "Pizza"))

authors.Add(new author("Brian Francis", "BF", "Pasta"))

authors.Add(new author("Alex Homer", "AH", "Steak "))

authors.Add(new author("Dave Sussman", "DS", "Whisky"))

authors.Add(new author("Karli Watson", "KCW", "Fondue"))

lstItems.DataSource = authors

lstItems.DataBind()

End If

End Sub

</script>

The code for the form itself is then very simple. The only thing we need to add is a LabelField attribute, which specifies
which field to use for the primary list display:

<mobile:Form runat="server" id="frmFirst">

<mobile:ObjectList runat="server" id="lstItems" LabelField="name"/>

</mobile:Form>

The result of all this is more complex than you might expect. On the Pocket PC the following is generated:

Clicking on an author name now has the default effect for this control (we haven't implemented our own handler), which

is to show us additional information on the author using fields automatically created for us. Notice that the field names are
exactly the same as the class property names. This is because we have
AutoGenerateFields set to True- the default.
If we change this to
False we can specify how fields are rendered, or even if they are rendered at all. We do this by
adding
<Field> elements inside the control. Each of these elements specifies a field to add to the ObjectListItems in
the control. We specify these by what property they should represent (using the
DataField attribute), the display name
for the field (using the
Title attribute), and an id for accessing the field. We can also use the Visible attribute to
control whether a given field appears when we follow the automatically generated author name links:

<mobile:Form runat="server" id="first">

<mobile:ObjectList runat="server" id="lstItems"

AutoGenerateFields="False" LabelField="fName">

<Field Name="fName" Title="Author Name"

DataField="name" Visible="True"/>

<Field Name="fInitials" Title="Author Initials"

DataField="initials" Visible="True"/>

<Field Name="fFood" Title="Author's Favorite Food"

DataField="favoritefood" Visible="False"/>

</mobile:ObjectList>

</mobile:Form>

The above changes result in the following:

As well as adding fields we can also define commands for the items, using <Command> elements. Let's add two commands,
to query for a biography or a favorite food:

<mobile:Form runat="server" id="frmFirst">

<mobile:ObjectList runat="server" id="lstItems"

AutoGenerateFields="False" LabelField="name">

<Field id="fName" Title="Author Name" DataField="name"

Visible="True"/>

<Field id="fInitials" Title="Author Initials" DataField="initials"

Visible="True"/>

<Field id="fFood" Title="Author's Favorite Food"

DataField="favoritefood" Visible="False"/>

<Command Name="Bio" Text="Author biography"/>

<Command Name="Food" Text="Find out the author's favorite food!"/>

</mobile:ObjectList>

</mobile:Form>

This command appears as follows:

In order to hook up the commands (we have two now) we use the OnItemCommand event. First we specify a handler by
modifying the opening tag for the control:

<mobile:ObjectList runat="server" id="lstItems"

AutoGenerateFields="False" LabelField="fName"

OnItemCommand="lstItems_itemCommand">

Next we implement the handler. Here we'll simply use the item data to specify information for two new forms, shown
beneath the code that goes in the
<script> section of the page:

Public Sub lstItems_itemCommand(sender As Object, _

e As ObjectListCommandEventArgs)

Dim currentAuthor As author

If (e.CommandName = "Food") Then

foodLabel.Text = lstItems.Selection.Item("fName") & _

"'s favorite food is " & _

lstItems.Selection.Item("fFood") & "!"

ActiveForm = second

Else

bioLabel.Text = lstItems.Selection.Item("fName") & " biography "

ActiveForm = third

End If

End Sub

<mobile:Form runat="server" id="second">

<mobile:Label runat="server" id="foodLabel"/>

</mobile:Form>

<mobile:Form runat="server" id="third">

<mobile:Label runat="server" id="bioLabel"/>

</mobile:Form>

Clicking on an author name then yields the first screenshot below, and on a 'favorite food' link the second:

This is all very well, but how does it appear on a WAP device? Well, on the Openwave Simulator we see the following card
first:


When we select an author we get to see the available commands: