Manipulating Lists

How to enable users to move selected items from one list to another on a page.

About this technique	Details
Category	HTML Client Techniques> Basic techniques
Description	You'll learn about: Adjusting an empty list's size Moving items to the selected list Moving items to the deselected list Displaying selected items as text in a dialog box
	You can run this technique code from: Database: Examples3_HTML Page: pgListManipulation.html NOTE   First make sure that database is running on your localhost SilverStream Server
Related reading	See the chapter on page basics in the Programmer's Guide

The example provides buttons to move highlighted items between the deselected-item list on the left and the selected-item list on the right. Another button displays the items from the selected-item list in an alert dialog box.

Adjusting an empty list's size   

The following code shows how to add a temporary item to the Selected list if no items have been selected. This allows the list to be displayed in its regular size, as if there were items in it. This method runs immediately after the page is first loaded, as well as at the beginning of each page request.

  protected void pageRequestBegin(AgiHttpServletRequest req, AgiHttpServletResponse res) throws Exception 
  { 
     // If the 'right' list has no rows, we need to add a temporary row so that the 
     // width of the list looks ok. 
     if (right.getItemCount() == 0) 
        right.add("No employee selected", new Integer(-1)); 
  } 

Notes about the code

• Get the number of items in the right list, that is, the Selected list. The variable called right is an AgpList instance. The getItemCount() method returns the number of items in the Selected list.

• If there are no items, add a temporary item to the list by calling the add() method and supplying -1 as the value of the temporary item.

Moving items to the selected list   

The following code shows how to move one or more selected items in the left list to the Selected list. For each selected item, the code uses the (left) list's index to get the item, and (after it has added the item to the Selected list) delete the item from the left list.

  private void handle_btnSelect_pageActionPerformed(ActionEvent evt) throws Exception 
  { 
     // Add each selected employee to the 'right' list and remove them from 
     // the 'left' list. 
     int index = left.getSelectedIndex(); 
     while (index >= 0) 
     { 
        // We need to check to see if the 'No employee selected' entry is still 
        // in the 'right' list and, if it is, remove it. 
        int itemValue = ((Integer)right.getItemValue(0)).intValue(); 
        if (itemValue == -1) 
           right.remove(0); 
   
        String item = left.getItem(index); 
        itemValue = ((Integer)left.getItemValue(index)).intValue(); 
   
        right.add(item, new Integer(itemValue)); 
   
        left.remove(index); 
   
        index = left.getSelectedIndex(); 
     } 
  } 

Notes about the code

• If the temporary item is in the Selected (right) list, it should be the first item in the list. To verify its existence, get the value of the item at index=0 by calling getItemValue(0) on the list. Cast the returned value to an Integer and call intValue() on it to the value as an int.

• If the item's value is -1, this confirms that it is indeed the temporary item. Remove it by calling remove() and providing the item's index value, that is, 0 (indicating the first item).

• To add the selected item from the left list to the Selected list, first get the item by calling getItem() and supplying the index. Then get its value by calling getItemValue(), then casting it to an Integer, and finally calling intValue() on it.

• Add the item to the Selected list by calling add() and providing the item and its value, both of which were obtained in the previous step.

• Remove the item from the left list by calling remove().

• Get the index of the (now) first selected item by calling getSelectedIndex(). The while loop causes each of the selected items in the left list to be added to the Selected list and to be then removed from the left list. Once there are no more selected items in the left list, getSelectedIndex() returns -1 and the code execution breaks from the loop.

Moving items to the deselected list   

The following code gets the first selected item in the Selected list, then uses a while loop to add each to the left list then remove it from the Selected list. (The code is similar to that of moving items from the left list to the Selected list.) After removing all the selected items, it checks if there are any items left in the Selected list. If there are none, it adds a temporary item to it, identifying it by the value 0.

  private void handle_btnDeselect_pageActionPerformed(ActionEvent evt) throws Exception 
  { 
     // Remove the selected employees from the 'right' list and add 
     // them back to the 'left' list. 
     int index = right.getSelectedIndex(); 
     while (index >= 0) 
     { 
        String item = right.getItem(index); 
        int itemValue = ((Integer)right.getItemValue(index)).intValue(); 
         
        left.add(item, new Integer(itemValue)); 
        right.remove(index); 
         
        index = right.getSelectedIndex(); 
     } 
      
     // If the 'right' list now has no rows, we need to add a temporary row so that the 
     // width of the list looks ok. 
     if (right.getItemCount() == 0) 
        right.add("No employee selected", new Integer(-1)); 
  } 

Notes about the code

• Get the number of items in the Selected list by calling getItemCount() on the list.

• If the number of items is 0, add the temporary item by calling add() and supplying its value as -1.

Displaying selected items as text in a dialog box   

The following code loops through all the items in the Selected list and appends each item as a text string to a string buffer. It displays the text in an Alert dialog by calling agScriptHelper.alert().

  private void handle_btnDisplay_pageActionPerformed(ActionEvent evt) throws Exception 
  { 
     StringBuffer sb = new StringBuffer("You selected: "); 
      
     int i = right.getItemCount(); 
     if (i == 1) 
     { 
        if (((Integer)right.getItemValue(0)).intValue() == -1) 
        { 
           agScriptHelper.alert("You have not selected anyone!"); 
           return; 
        } 
     } 
     for (int j = 0; j < i; j++) 
     { 
        if (j > 0) 
           sb.append(", "); 
        sb.append(right.getItem(j)); 
     } 
     agScriptHelper.alert(sb.toString()); 
  } 

Notes about the code

• Create a string buffer to contain the string to display in the Alert dialog.

• Get the number of items in the Selected list.

• If there is only one item, that is, getItemCount() returns 1, and the value of that item is -1, indicating that it is the temporary item, open an Alert dialog displaying the error message.

• Call agScriptHelper.alert() to generate JavaScript code that opens an Alert dialog.

• To display the items as text in the Alert dialog, use a for loop to get each item in the Selected list and append it to the String Buffer. getItem() returns the text of the item whose index is specified. append() adds the text to the end of the String Buffer.

• After the loop has covered all items in the Selected list, call agScriptHelper.alert() to display the resulting concatenated items in the String Buffer.