List Control

  • Article

Renders a list of items to a mobile device. This control supports templated rendering through device template sets, and it supports internal pagination. For more information, see the Template Sets and Templated Controls or Pagination documentation.

Static and Interactive Modes

You can set this control to operate in the following modes:

  • Static mode - The control behaves like a static list. Static list items can be declared as item child elements.
  • Interactive mode - The control renders items as interactive elements.

The behavior of these modes is based on the presence of an event handler. When an event handler is not present, the control is set to static mode. When an event handler is present, the control is set to interactive mode, in which each item is an interactive element that generates an event when clicked.

Mobile Controls Syntax

Required properties, defaults, and code-featured elements are noted in bold type.

<mobile:List
   runat="server"
   id="id"
   Font-Name="fontName"
   Font-Size="{NotSet|Normal|Small|Large}"
   Font-Bold="{NotSet|False|True}"
   Font-Italic="{NotSet|False|True}"
   ForeColor="foregroundColor"
   BackColor="backgroundColor"
   Alignment="{NotSet|Left|Center|Right}"
   StyleReference="styleReference"
   Wrapping="{NotSet|Wrap|NoWrap}"

   DataMember="dataMember"
   DataTextField="dataTextField"
   DataValueField="dataValueField"
   Decoration="{None|Bulleted|Numbered}"
   ItemsAsLinks="{False|True}"
   ItemCount="itemCount"
   OnItemDataBind="onItemDataBindHandler"
   OnItemCommand="onItemCommandHandler"
   OnLoadItems="loadItemsHandler">

Place DeviceSpecific/Choice construct here. (optional)
   <DeviceSpecific>
      <Choice Add choice here>
      </Choice>
   </DeviceSpecific>

Place statically declared list items here. (optional)
   <Item Text="Text" Value="Value" />

</mobile:List>

Containment Rules

The following controls can contain a List control.

Control Comments
System.Web.UI.MobileControls.Form Can contain any number of List controls.
System.Web.UI.MobileControls.Panel Can contain any number of List controls.

A List control can contain the following controls.

Control Comments
System.Web.UI.MobileControls.DeviceSpecific 0 or 1 DeviceSpecific controls can be contained in an List control.
System.Web.UI.MobileControls.Item Any number of Item controls can be contained in an Image control.

Device Templates

Template Description
HeaderTemplate The header template is rendered at the beginning of the list. In paginated mode, the header is rendered on each page.
FooterTemplate The footer template is rendered at the end of the list. In paginated mode, the footer is rendered on each page.
ItemTemplate The item template is rendered for each list item.
AlternatingItemTemplate If defined, an alternating item template is rendered instead of the item template for even items. For example, the second item is an alternating template, as is the fourth item, as is every subsequent even-numbered item.
SeparatorTemplate The separator template is rendered between two items.

Device-Specific Behavior

Device language Description of behavior
HTML The list rendering for HTML depends on the style that is set in the Decoration property:
  • If the Decoration property's value is set to None, each item is displayed as is (without a style).
  • If the Decoration property's value is set to Bulleted, the items are rendered as <li> items (list item) in a <ul> list (bulleted list).
  • If the Decoration property's value is set to Numbered, the items are rendered as <li> items in an <ol> list (numbered list).

If there is an ItemCommand event defined, the item text is enclosed in a hyperlink.

With a control that is templated, the control renders the list as defined solely by the templates.
WML For static lists in WML, a list is rendered as a series of static lines.

For interactive lists in WML on devices that use Openwave technology, the list is rendered as a <select> construct, allowing the user to use numeric keys to click or select items. Other UI elements on a card can be merged into this select block.

For interactive lists on other WML devices, the list is rendered as a series of anchors.

With a control that is templated, the control renders the list as defined solely by the templates.

Example

The following example displays a list of fruit. When you select a fruit, the control displays its price.

<%@ Page Inherits= "System.Web.UI.MobileControls.MobilePage"
    Language="VB" %>
<%@ Register TagPrefix="mobile"
    Namespace="System.Web.UI.MobileControls"
    Assembly="System.Web.Mobile" %>

<script language="vb" runat="server">
protected Sub List_Click(source As Object, e As ListCommandEventArgs)
   Dim selectedFruit as String
   selectedFruit = "You selected " + e.ListItem.Text + _
      " at " + e.ListItem.Value + " per pound."
   PriceLabel.Text = selectedFruit
   ActiveForm = Price
End Sub
</script>

<mobile:Form id="ShowProduce" runat="server" BackColor="Green">
   <mobile:Label runat="server" id="label1">Pick a Fruit!</mobile:Label>
   <mobile:List runat="server" id="ListProduce" 
     OnItemCommand="List_Click" >
      <item Text="Apples" Value="20 cents" />
      <item Text="Apricots" Value="80 cents" />
      <item Text="Bananas" Value="79 cents" />
      <item Text="Grapes" Value="50 cents" />
      <item Text="Oranges" Value="30 cents" />
      <item Text="Peaches" Value="10 cents" /> 
      <item Text="Pears" Value="70 cents" />
      <item Text="Plums" Value="99 cents" />
   </mobile:List>
</mobile:Form>
<mobile:Form id="Price" runat = "server">
   <mobile:Label runat="server" id="PriceLabel"/>
</mobile:Form>
[C#]
<%@ Page Inherits= "System.Web.UI.MobileControls.MobilePage"
    Language="C#" %>
<%@ Register TagPrefix="mobile"
    Namespace="System.Web.UI.MobileControls"
    Assembly="System.Web.Mobile" %>

<script language="c#" runat="server">
protected void List_Click(Object source, ListCommandEventArgs e)
{
   String selectedFruit = "You selected " + e.ListItem.Text +
      " at " + e.ListItem.Value + " per pound.";
   PriceLabel.Text = selectedFruit;
   ActiveForm = Price;
}
</script>

<mobile:Form id="ShowProduce" runat="server" BackColor="Green">
   <mobile:Label runat="server" id="label1">Pick a Fruit!</mobile:Label>
   <mobile:List runat="server" id="ListProduce" 
     OnItemCommand="List_Click" >
      <item Text="Apples" Value="20 cents" />
      <item Text="Apricots" Value="80 cents" />
      <item Text="Bananas" Value="79 cents" />
      <item Text="Grapes" Value="50 cents" />
      <item Text="Oranges" Value="30 cents" />
      <item Text="Peaches" Value="10 cents" /> 
      <item Text="Pears" Value="70 cents" />
      <item Text="Plums" Value="99 cents" />
   </mobile:List>
</mobile:Form>
<mobile:Form id="Price" runat = "server">
   <mobile:Label runat="server" id="PriceLabel"/>
</mobile:Form>

See Also

List Class | List Class Members | Control Reference