ListView.ItemCommand Event (System.Web.UI.WebControls)

ItemCommand Event

Collapse All

Language Filter

.NET Framework Class Library

ListView..::.ItemCommand Event

Updated: November 2007

Occurs when a button in a ListView control is clicked.

Namespace: System.Web.UI.WebControls
Assembly: System.Web.Extensions (in System.Web.Extensions.dll)

Syntax

Visual Basic (Declaration)

Public Event ItemCommand As EventHandler(Of ListViewCommandEventArgs)

Visual Basic (Usage)

Dim instance As ListView
Dim handler As EventHandler(Of ListViewCommandEventArgs)

AddHandler instance.ItemCommand, handler

public event EventHandler<ListViewCommandEventArgs> ItemCommand

Visual C++

public:
 event EventHandler<ListViewCommandEventArgs^>^ ItemCommand {
    void add (EventHandler<ListViewCommandEventArgs^>^ value);
    void remove (EventHandler<ListViewCommandEventArgs^>^ value);
}

/** @event */
public void add_ItemCommand (EventHandler<ListViewCommandEventArgs> value)
/** @event */
public void remove_ItemCommand (EventHandler<ListViewCommandEventArgs> value)

JScript

JScript does not support events.

ASP.NET

<asp:ListView OnItemCommand="EventHandler" />

Remarks

The ItemCommand event is raised when a button in the ListView control is clicked. This enables you to perform a custom routine whenever this event occurs.

Buttons in a ListView control can also invoke built-in functionality of the control. The following table lists values that you can use with the CommandName property of a button in order to invoke built-in functionality.

CommandName value	Description
"Cancel"	Cancels an edit or insert operation. Raises the ItemCanceling event.
"Delete"	Deletes the current record from the data source. Raises the ItemDeleted and ItemDeleting events.
"Select"	Sets the SelectedIndex property to the DisplayIndex property value for the item. Renders the SelectedItemTemplate template for the item. Raises the SelectedIndexChanging and SelectedIndexChanged events.
"Edit"	Puts the item in edit mode. Renders the EditItemTemplate template for the item. Raises the ItemEditing event.
"Insert"	Inserts the bound values from the InsertItemTemplate template into the data source. Raises the ItemInserting and ItemInserted events.
"Update"	Updates the current record in the data source with the bound values from the EditItemTemplate template. Raises the ItemUpdating and ItemUpdated events.
"Sort"	Sorts the columns listed in the CommandArgument property of the button. Raises the Sorting and Sorted events.

The ItemCommand event is also raised when a button that is listed in the previous table is clicked. However, it is recommended that you use the events listed in the table. The ItemCommand event is usually used to handle custom operations.

A ListViewCommandEventArgs object is passed to the event handler, which enables you to determine the command name and command argument of the button that was clicked. To determine the command name, use the CommandEventArgs..::.CommandName property. To determine the command argument, use the CommandEventArgs..::.CommandArgument property. To access the control that raised the event, use the ListViewCommandEventArgs..::.CommandSource property.

For more information about how to handle events, see Consuming Events.

Examples

The following example shows how to create an ItemCommand event handler.

Visual Basic

<%@ Page language="VB" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">
  Protected Sub EmployeesListView_OnItemCommand(ByVal sender As Object, _
  ByVal e As ListViewCommandEventArgs)

    If String.Equals(e.CommandName, "AddToList") Then

      ' Verify that the employee ID is not already in the list. If not, add the
      ' employee to the list.
      Dim dataItem As ListViewDataItem = CType(e.Item, ListViewDataItem)
      Dim employeeID As String = _
        EmployeesListView.DataKeys(dataItem.DisplayIndex).Value.ToString()

      If SelectedEmployeesListBox.Items.FindByValue(employeeID) Is Nothing Then
        Dim item As ListItem = _
          New ListItem(e.CommandArgument.ToString(), employeeID)
        SelectedEmployeesListBox.Items.Add(item)
      End If

    End If

  End Sub
</script>

<html  >
<head id="Head2" runat="server">
    <title>Employee List</title>
  </head>
  <body>
    <form id="form1" runat="server">
      <asp:ListView runat="server" 
        ID="EmployeesListView"
        OnItemCommand="EmployeesListView_OnItemCommand"
        DataSourceID="EmployeesDataSource" 
        DataKeyNames="EmployeeID">
        <LayoutTemplate>
          <table runat="server" id="tblEmployees" 
                 cellspacing="0" cellpadding="1" width="440px" border="1">
            <tr id="itemPlaceholder" runat="server"></tr>
          </table>
          <asp:DataPager ID="EmployeesDataPager" runat="server" PageSize="10">
            <Fields>
              <asp:NumericPagerField />
            </Fields>
          </asp:DataPager>
        </LayoutTemplate>
        <ItemTemplate>
          <tr runat="server">
            <td>
              <asp:Label runat="server" ID="NameLabel" 
                Text='<%#Eval("LastName") & ", " & Eval("FirstName") %>' />
            </td>
            <td style="width:80px">
              <asp:LinkButton runat="server" 
                ID="SelectEmployeeButton" 
                Text="Add To List" 
                CommandName="AddToList" 
                CommandArgument='<%#Eval("LastName") & ", " & Eval("FirstName") %>' />
            </td>
          </tr>
        </ItemTemplate>
      </asp:ListView>

      <br /><br />
      <b>Selected Employees:</b><br />
      <asp:ListBox runat="server" ID="SelectedEmployeesListBox" Rows="10" Width="300px" />

      <!-- This example uses Microsoft SQL Server and connects      -->
      <!-- to the AdventureWorks sample database. Use an ASP.NET    -->
      <!-- expression to retrieve the connection string value       -->
      <!-- from the Web.config file.                                -->       
      <asp:SqlDataSource ID="EmployeesDataSource" runat="server" 
        ConnectionString="<%$ ConnectionStrings:AdventureWorks_DataConnectionString %>"
        SelectCommand="SELECT [EmployeeID], [FirstName], [LastName]
                       FROM HumanResources.vEmployee
                       ORDER BY [LastName], [FirstName], [EmployeeID]">
      </asp:SqlDataSource>
    </form>
  </body>
</html>

<%@ Page language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">
  protected void EmployeesListView_OnItemCommand(object sender, ListViewCommandEventArgs e)
  {
    if (String.Equals(e.CommandName, "AddToList"))
    {
      // Verify that the employee ID is not already in the list. If not, add the
      // employee to the list.
      ListViewDataItem dataItem = (ListViewDataItem)e.Item;
      string employeeID = 
        EmployeesListView.DataKeys[dataItem.DisplayIndex].Value.ToString();

      if (SelectedEmployeesListBox.Items.FindByValue(employeeID) == null)
      {
        ListItem item = new ListItem(e.CommandArgument.ToString(), employeeID);
        SelectedEmployeesListBox.Items.Add(item);
      }
    }
  }
</script>

<html  >
<head id="Head1" runat="server">
    <title>Employee List</title>
  </head>
  <body>
    <form id="form1" runat="server">
      <asp:ListView runat="server" 
        ID="EmployeesListView"
        OnItemCommand="EmployeesListView_OnItemCommand"
        DataSourceID="EmployeesDataSource" 
        DataKeyNames="EmployeeID">
        <LayoutTemplate>
          <table runat="server" id="tblEmployees" 
                 cellspacing="0" cellpadding="1" width="440px" border="1">
            <tr id="itemPlaceholder" runat="server"></tr>
          </table>
          <asp:DataPager ID="EmployeesDataPager" runat="server" PageSize="10">
            <Fields>
              <asp:NumericPagerField />
            </Fields>
          </asp:DataPager>
        </LayoutTemplate>
        <ItemTemplate>
          <tr runat="server">
            <td>
              <asp:Label runat="server" ID="NameLabel" 
                Text='<%#Eval("LastName") + ", " + Eval("FirstName") %>' />
            </td>
            <td style="width:80px">
              <asp:LinkButton runat="server" 
                ID="SelectEmployeeButton" 
                Text="Add To List" 
                CommandName="AddToList" 
                CommandArgument='<%#Eval("LastName") + ", " + Eval("FirstName") %>' />
            </td>
          </tr>
        </ItemTemplate>
      </asp:ListView>

      <br /><br />
      <b>Selected Employees:</b><br />
      <asp:ListBox runat="server" ID="SelectedEmployeesListBox" Rows="10" Width="300px" />

      <!-- This example uses Microsoft SQL Server and connects      -->
      <!-- to the AdventureWorks sample database. Use an ASP.NET    -->
      <!-- expression to retrieve the connection string value       -->
      <!-- from the Web.config file.                                -->       
      <asp:SqlDataSource ID="EmployeesDataSource" runat="server" 
        ConnectionString="<%$ ConnectionStrings:AdventureWorks_DataConnectionString %>"
        SelectCommand="SELECT [EmployeeID], [FirstName], [LastName]
                       FROM HumanResources.vEmployee
                       ORDER BY [LastName], [FirstName], [EmployeeID]">
      </asp:SqlDataSource>
    </form>
  </body>
</html>

Platforms

Windows Vista, Windows XP SP2, Windows Server 2003

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information