Binding a JSF single-select control to a variable

Binding a JSF single-select control, such as a combo box or group of radio buttons, to an EGL variable is more complicated than binding an input or output control because you must use two EGL variables: one for the options in the control and one for the selected value.

In general, you need to create an array that represents the options in the control, as well as a single variable to hold the value of the selected option. The simplest way to do this is by defining an array of strings and populating the array with the options for the control. See "Using an array of STRING as the selection options." Alternatively, you can use an array of records as the options for the control by specifying fields in the record as the option that is displayed in the control and as the value for the selection. See "Using an array of records as the selection options."

Using an array of STRING as the selection options

  1. In a JSF Handler, create an array of strings to hold the options for the single-select control:
    selectionOptions string[4];
  2. Assign values to the array. You can assign values dynamically or simply assign literal values to the array:
    selectionOptions string[4]
       {"First choice", "Second choice",
        "Third choice", "Fourth choice"};
  3. Create a string variable to hold the selected option:
    selectedChoice string;
  4. Indicate that the single variable receives the option selected from the list of options by adding the SelectedValueItem property to the list of options:
    selectionOptions string[4]
       {"First choice", "Second choice",
        "Third choice", "Fourth choice",
        SelectedValueItem = selectedChoice};
  5. Save and generate the JSF Handler.
  6. On the page that is associated with the JSF Handler, drag the variable that represents the list of options (in this case, selectionOptions) from the Page Data view onto the page. The Insert List Control window opens.
  7. In the Insert List Control window, click Displaying an existing record.
  8. Under Control Type, select the type of single-select JSF control to put on the page.

    You can choose from Combobox (also called a list box or drop-down box), List Box - single select, or Radio Button Group. In each case, the options will be added dynamically depending on the number of elements in the list of options at run time.

  9. Click Finish. The control is added to your page and it is automatically bound to the variables in the JSF Handler.

You can check which variables the JSF control is bound to by clicking the control to select it and then opening the Properties view. In the Properties view, the Value field represents the variable that will receive the value of the selected option, and the table of variables at the right side of the view lists the variable or variables that are used to provide the options for the control.

This is a complete example of a JSF Handler that uses a single-select control in this way:
handler singleSelect type JSFHandler
    {view = "singleSelect.jsp"} 

    selectionOptions  string[4]
       {"First choice","Second choice",
        "Third choice","Fourth choice", 
        SelectedValueItem = selectedChoice};
        
    selectedChoice    string;

    outputMessage     string;
    
    function getChoice()
        outputMessage = "You chose: " 
            + selectedChoice;
    end
end
This example assumes that you have dragged the selectionOptions variable onto the page and created a combo box, list box, or radio button group based on this variable. You will also need to bind the outputMessage variable to an output control and the getChoice function to a button on the page. When you click the button, the output control displays the text of the option you selected in the JSF single-select control.

Using an array of records as the selection options

The method of using an array of strings as the selection options is simple, but it might not be the most convenient method. You might need to retrieve the options from an array of records, or you might need to use one value for the option and pass a different value to the selection result variable. In this case, use the @SelectionList record property to indicate which fields in the record should be used for the option and which should be used for the value of the selection.

To use an array of records as the selection options:

  1. In a Record part, use @SelectionList to specify which field in the record should be the selection option (the labelItem) and which field should be the value of the option (the valueItem:
    record optionsRec type BasicRecord
       {@SelectionList {labelItem = displayOption, 
                        valueItem = optionValue}}
        displayOption  string;
        optionValue    string;
    end
    The record can contain other fields, but you must select two of these fields to be the label and the value.
  2. In the JSF Handler, create an array that is based on this Record part:
    selectionOptions optionsRec[3];
  3. Assign values to the array. You can assign values dynamically or simply assign literal values to the array. You might want to use the onPreRenderFunction to set values for this array:
    function onPreRender()
        selectionOptions[1].displayOption = "Option one";
        selectionOptions[1].optionValue = "first option";
        selectionOptions[2].displayOption = "Option two";
        selectionOptions[2].optionValue = "second option";
        selectionOptions[3].displayOption = "Option three";
        selectionOptions[3].optionValue = "third option";
    end
  4. Create a single variable to receive the selected option:
    selectedChoice string;
    The type of this variable must match the type of the field marked as valueItem in the Record part.
  5. Indicate that the single variable will receive the option that is selected from the list of options by adding the SelectedValueItem property to the list of options:
    selectionOptions optionsRec[3]
       {selectedValueItem = selectedChoice};
  6. Save and generate the JSF Handler.
  7. On the page that is associated with the JSF Handler, drag the variable that represents the list of selection options (in this case, selectionOptions from the Page Data view onto the page. The Insert List Control window opens.
  8. In the Insert List Control window, click Displaying an existing record.
  9. Under Control Type, select the type of single-select JSF control to put on the page.

    You can choose from Combobox (also called a list or drop-down box), List Box - single select, or Radio Button Group. In each case, the options will be added dynamically depending on the number of elements in the list of selection options at run time.

  10. Click Finish. The control is added to your page and it is automatically bound to the variables in the JSF Handler.

You can check which variables the JSF control is bound to by clicking the control to select it and then opening the Properties view. In the Properties view, the Value field represents the variable that will receive the value of the selected option, and the table of variables at the right side of the view lists the variable or variables that are used to provide the options for the control.

This is a complete example of a JSF Handler that uses a single-select control in this way:
handler singleSelect type JSFHandler
   {view = "singleSelect.jsp", 
    onPreRenderFunction = onPreRender} 

    selectionOptions optionsRec[3]
       {selectedValueItem = selectedChoice};
        
    selectedChoice    string;

    outputMessage     string;
    
    function onPreRender()
        selectionOptions[1].displayOption = "Option one";
        selectionOptions[1].optionValue = "first option";
        selectionOptions[2].displayOption = "Option two";
        selectionOptions[2].optionValue = "second option";
        selectionOptions[3].displayOption = "Option three";
        selectionOptions[3].optionValue = "third option";
    end
    
    function getChoice()
        outputMessage = "You chose: " 
            + selectedChoice;
    end
end

record optionsRec type BasicRecord
   {@SelectionList {labelItem = displayOption, 
                    valueItem = optionValue}}
    displayOption  string;
    optionValue    string;
end
This example assumes that you have dragged the selectionOptions variable onto the page and created a combo box, list box, or radio button group that is based on this variable. You also need to bind the outputMessage variable to an output control and the getChoice function to a button on the page. When you click the button, the output control displays the text of the option that you selected in the JSF single-select control.

Feedback