Standard Checkbox List Component

See Also

You can drag the Standard JavaServer Faces Checkbox List component  from the Palette's Standard category to the Visual Designer to create a table initially containing three checkboxes in single row.

• This component is a JavaServer Faces reference implementation that cannot use themes. The Checkbox Group component in the Basic category of the Palette does support themes and provides other features that improve ease of use.
   
  

A Checkbox List is a composite component that has the following elements:

• The enclosing component, checkboxList, manages the style and behavior of the list itself. In addition, when the user submits the page, the value property of this component is an object array containing the user's choices. You can bind this component's value property to an Object array and use that object to test what the user's choices were.
   
  
• The inside component, checkboxListSelectItems, is intended to be used to bind to a data provider that specifies the actual items in the list.
   
  
• A third, related component, checkboxListDefaultItems, contains an array of initial checkboxes for the list. This array is used to populate the list only if the list is not bound to a data provider. Each checkbox in this third component has a label with default text (item1, item2, item3).
   
  

After dragging the component to the Visual Designer, you can do a number of things with it:

• Select the Checkbox List component and drag it to another location on the page.
   
  
• Right-click the checkboxList component in the Outline window  and choose Property Bindings to bind its value property to an Object array that you have added to the session bean as a property. You can use this session bean property to evaluate what the user chose after the page is submitted. For more information, see the value property description below.
   
  
• Right-click the checkboxListSelectItems component in the Outline window and bind it to a data provider that will be used to populate the list. For more information, see the following tutorial on the Web at:
  Using Listbox Components
   
  
• Select the Checkbox List component on the page in the Visual Designer and edit its properties in the Checkbox List Properties window. These properties affect the overall style and behavior of the list. Some typical properties you might set are:
  • id. The name of the Checkbox List component. In the JSP file, this name is the value of the component's id attribute. In the page bean, this property's value is the name of the HtmlSelectManyCheckbox object.
     
    
  • layout. The orientation of the list. The default orientation is lineDirection: The list is laid out horizontally, left to right. If you choose pageDirection, the list is laid out vertically, from top to bottom.
     
    
  • value. The data that is sent when the page is submitted.
     
    The Checkbox List component can have more than one value, which has implications about what type of value you can use.
    • If you use a value binding expression, it must point to an array of objects or primitives. The individual elements in this array represent the currently selected values from the set of all possible options.
       
      
    • If you do not use a value binding expression, the object returned to you when you call checkboxList.getValue() is an object array.
       
      
    • There is no usable way to bind this component to database data, because the value will typically be represented by multiple rows in some detail table.
       
      

    One way to process the values chosen by the user is to bind this component to an Object array and check the array values when the user submits the page. For more information, see the tutorial that describes how to set up binding for a similar list component, "Using Listbox Components", which is on the Web at
    Using Listbox Components

    
     
    
  
   
  
• Right-click the Checkbox List component in the Visual Designer and choose one of several actions:
  • Edit Event Handler. Write code for one of the following event handlers.
    • validate. Opens the Java Editor with the cursor positioned in the checkbox list's validate method so you can insert code to validate the value of the checkbox list.
       
      
    • processValueChange. Opens the Java Editor with the cursor positioned in the checkbox list's processValueChange
       
      
    • 
       
      
    • 
       
      
    • 
       
      
    • 
       
      
    • 
       
      
    • 
       
      
    • 
       
      
    • 
       
      
    • 
       
      
    • method so you can insert code that executes when the value of this checkbox list changes (for example, the user checks two of the boxes and submits the form).
       
      
    
     
    
  • Bind to Data. Bind the component's value property to an object or to a data provider, as described in Bind to Data Dialog Box.
     
    
  • Property Bindings. Opens a dialog box that enables you to bind the properties of the component to other objects or properties that update this component's properties automatically.
     
    
  
   
  

See Also

Working With Components

Component Tasks: Quick Reference

Component Web Tutorials

Data Source Web Tutorials

About the Palette