ObjectList Control

Provides a feature-rich view of a list of data objects. The ObjectList control inherits much of its behavior, including support for templated rendering by using device template sets, and internal pagination, from the List control. For more information, see the Template Sets and Templated Controls or Pagination documentation. The ObjectList control differs from the List control in the following ways.

This table compares the features of the ObjectList and List controls. However, it is important to understand that although both of these controls support custom pagination and templating, the SelectionList class does not support pagination.

For more information about using the ObjectList control, see the Designing and Rendering Concepts for Mobile Controls documentation.

Mobile Controls Syntax

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

<mobile:ObjectList
   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}"

   AutoGenerateFields="{True|false}"
   BackCommandText="backCommandText"
   CommandStyle="commandStyle"
   DataMember="dataMember"
   DetailsCommandText="detailsCommandText"
   ItemCount="itemCount"
   LabelField="dataTextField"
   LabelStyle="labelStyle"
   MoreText="moreText"
   OnItemDataBind="onItemDataBindHandler"
   OnItemCommand="onItemCommandHandler"
   OnItemSelect="onItemSelectHandler"
   OnLoadItems="onLoadItemsHandler"
   OnShowItemCommands="onShowItemCommandsHandler"
   TableFields="tableFields">
Place DeviceSpecific/Choice construct here. (optional)
   <DeviceSpecific>
      <Choice>
        Add choice attributes here.
     </Choice>
   </DeviceSpecific>
Place explicitly declared Fields here. (optional)
   <Field 
      id="id"
      Title="titleText" 
      DataField="value"
      FormatString="formatString" 
      Visible="{True|False}"/>
   </Field>
Place explicitly declared Commands here. (optional)
   <Command Name="CommandName" Text="CommandText" />
</mobile:ObjectList>

Static fields and commands can be declared as item child elements.

Containment Rules

The following controls can contain an ObjectList control.

An ObjectList control can contain the following controls.

Device Templates

For information about specifying templates for the ObjectList control, see the Device-Specific Rendering documentation. The following table contains a list of templates that you can use with the ObjectList control.

Note   Only the ItemsDetails template affects the commands/details view. If you want to apply a template to all views, you must specify an ItemsDetails view for the commands/details view and one of the other templates for the list view.

Device-Specific Behavior - HTML

On HTML devices, the object list is initially rendered as a table, with each list item (object) represented by a link. By default, this link is a value associated with the first column in the dataset. If the LabelField Property is set, the link is a value associated with the field specified by this property. It is possible to change this behavior so that the initial list item is simply a label and a further "More" link" displayed. By clicking "More", the user can view more details about a particular object in an object list. For example, the user can see a table that lists each field title and value, along with all the commands associated with the item.

If the TableFields property is set, and the device is appropriate for showing a table view, each list item is instead represented by a table row, with each specified table field in a column, followed by an optional link labeled "More". The item label (or the first column of the item in table view) can itself be rendered as a hyperlink.

The decisions on what links to show, and how to process them, depends on whether additional item fields can be shown, and whether a default command is defined.

The following table summarizes this behavior.

The preceding table uses the following column headings:

• Commands Defined indicates whether commands are defined in the object list. An asterisk (*) means that no commands other than the default command are defined.
• Default Command indicates whether a default command has been defined by setting the DefaultCommand property.
• Additional Fields specifies whether there are additional fields defined in the object list that are not shown in the list view.

The details view, if one is shown, has a table that lists each field title and value, along with all the commands associated with the item, and a link labeled "Back" to return to the list view.

Device-Specific Behavior - WML

On WML devices, the object list is initially rendered as a select list, with each item represented by its label. By selecting the item, the user can view a menu of commands for the item, including a link labeled "Details". By clicking "Details", the user can view each field title and value.

Example

The following example uses an ObjectList control to render a list of grocery store items. The user can view details about individual items, and has access to commands such as Reserve and Buy.

<%@ 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">

Public Class GroceryItem
   private _department, _item, _status As String

   Public Sub New( department As String, item As String, status As String)
      _department = department
      _item = item
      _status = status
   End Sub

   Public ReadOnly Property Department as String
      Get
         Return _department
      End Get
   End Property
   Public ReadOnly Property Item as String
      Get
         Return _item
      End Get
   End Property
   Public ReadOnly Property Status as String
      Get
         Return _status
      End Get
   End Property
End Class

Public Sub Page_Load(o As Object, e As EventArgs)
   If Not IsPostBack Then
      Dim arr As New ArrayList()
      arr.Add (New GroceryItem ("Bakery", "French Rolls", "On Sale"))
      arr.Add (New GroceryItem ("Dairy", "Eggnog", "Half price"))
      arr.Add (New GroceryItem ("Produce", "Apples", "A dollar a bushel"))

      List1.DefaultCommand = "Default"
      List1.MoreText       = "Click for Details"
      List1.DataSource = arr
      List1.DataBind
   End If
End Sub

Public Sub List1_Click(sender As Object, e As ObjectListCommandEventArgs)
   If e.CommandName = "Reserve" Then
      ActiveForm = Form2
   ElseIf e.CommandName = "Buy"
      ActiveForm = Form3
   Else
      ActiveForm = Form4
   End If
End Sub

</script>

<mobile:Form id="Form1" runat="server" BackColor="LightBlue">
   <mobile:ObjectList id="List1" runat="server"
         LabelField="item"
         OnItemCommand="List1_Click">
      <Command Name="Reserve" Text="Reserve"/>
      <Command Name="Buy" Text="Buy"/>
   </mobile:ObjectList>
</mobile:Form>

<mobile:Form id="Form2" runat="server" BackColor="LightBlue">
   <mobile:Label id="ResLabel" runat="server"
        text="Sale item reservation system coming soon!" />
   <mobile:Link id="ResLink" NavigateURL="#Form1" runat="server" text="Return" />
</mobile:Form>

<mobile:Form id="Form3" runat="server" BackColor="LightBlue">
   <mobile:Label id="BuyLabel" runat="server"
        text="Online purchasing system coming soon!" />
   <mobile:Link id="BuyLink" NavigateURL="#Form1" runat="server" text="Return" />
</mobile:Form>

<mobile:Form id="Form4" runat="server" BackColor="LightBlue">
   <mobile:Label id="DefLabel" runat="server"
        text="Detailed descriptions of the items will be here soon!" />
   <mobile:Link id="DefLink" NavigateURL="#Form1" runat="server" text="Return" />
</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">

class GroceryItem
{
   private String _department, _item, _status;

   public GroceryItem(string department, string item, string status)
   { 
      _department = department;
      _item = item;
      _status = status;
   }

   public String Department { get { return _department; } }
   public String Item { get { return _item; } }
   public String Status { get { return _status; } }
}

public void Page_Load(Object o, EventArgs e)
{
   if (!IsPostBack)
   {
      ArrayList arr = new ArrayList();
      arr.Add (new GroceryItem ("Bakery", "French Rolls", "On Sale"));
      arr.Add (new GroceryItem ("Dairy", "Eggnog", "Half price"));
      arr.Add (new GroceryItem ("Produce", "Apples", "A dollar a bushel"));

      List1.DefaultCommand = "Default";
      List1.MoreText       = "Click for Details";
      List1.DataSource = arr;
      List1.DataBind ();
   }
}

public void List1_Click(Object sender, ObjectListCommandEventArgs e)
{
   if (e.CommandName == "Reserve")
   {
      ActiveForm = Form2;
   }
   else if (e.CommandName == "Buy")
   {
      ActiveForm = Form3;
   }
   else
   {
      ActiveForm = Form4;
   }
}

</script>

<mobile:Form id="Form1" runat="server" BackColor="LightBlue">
   <mobile:ObjectList id="List1" runat="server"
         LabelField="item"
         OnItemCommand="List1_Click">
      <Command Name="Reserve" Text="Reserve"/>
      <Command Name="Buy" Text="Buy"/>
   </mobile:ObjectList>
</mobile:Form>

<mobile:Form id="Form2" runat="server" BackColor="LightBlue">
   <mobile:Label id="ResLabel" runat="server"
        text="Sale item reservation system coming soon!" />
   <mobile:Link id="ResLink" NavigateURL="#Form1" runat="server" text="Return" />
</mobile:Form>

<mobile:Form id="Form3" runat="server" BackColor="LightBlue">
   <mobile:Label id="BuyLabel" runat="server"
        text="Online purchasing system coming soon!" />
   <mobile:Link id="BuyLink" NavigateURL="#Form1" runat="server" text="Return" />
</mobile:Form>

<mobile:Form id="Form4" runat="server" BackColor="LightBlue">
   <mobile:Label id="DefLabel" runat="server"
        text="Detailed descriptions of the items will be here soon!" />
   <mobile:Link id="DefLink" NavigateURL="#Form1" runat="server" text="Return" />
</mobile:Form>

Example Output

The first form displays the three items, with a link for additional information:

When you click "Click for Details" for the Eggnog entry, you get the following screen:

See Also

ObjectList Class | ObjectList Class Members | List Control | Control Reference