Share via

ObjectList Control

  • Article

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.

Features ObjectList control List control
Data bound Strictly data bound. The only way to add items to an object list in a control is by binding the list to a data source. Supports adding items statically, programmatically, and through data binding.
Multiple-property view Allows you to view multiple properties, or fields, associated with each item. Depending on device characteristics, the control can be rendered as a table that displays more than one property of each object, or UI can be provided to allow the user to view additional properties of an object. Displays one property of each item.
Multiple item commands Allows you to associate multiple commands with each item. The set of commands for an item can be either shared among all items or unique to the item. Supports a default command for each item.
Internal pagination and templating Supported; however, if you are viewing an object with a lot of information, use a list with a separate form for item details. Supported.

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.

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

An ObjectList control can contain the following controls.

Control Comments
System.Web.UI.MobileControls.DeviceSpecific 0 or 1 DeviceSpecific controls can be contained in an ObjectList control.
System.Web.UI.MobileControls.ObjectList.Field Any number of Field controls can be contained in an ObjectList control.
System.Web.UI.MobileControls.ObjectList.Command Any number of Command controls can be contained in an ObjectList control.

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.

Template Description
AlternatingItemTemplate This template renders even-numbered items in a list view of an ObjectList object.
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.
ItemDetailsTemplate This template replaces the rendering of the commands/details view for an ObjectList object.
ItemTemplate The item template is rendered for each list item.
SeparatorTemplate The separator template separates items from each other.

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.

Commands defined Default command Additional fields Behavior
No No No Rendered content is static.
No No Yes Items are shown as hyperlinks. Clicking one shows item details.
No(*) Yes No Items are shown as hyperlinks. Clicking one raises a default command.
No(*) Yes Yes Items are shown as hyperlinks. Clicking one raises a default command.
More links are shown. Clicking one shows item details.
Yes No Yes or No Items are shown as hyperlinks. Clicking one shows item details.
Yes No Yes Items are shown as hyperlinks. Clicking one shows item details.
Yes Yes Yes or No Items are shown as hyperlinks. Clicking one raises a default command. More links are shown. Clicking one shows item details.

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