Select Builder
In this topic ...
Related Topics ...
How to Use the Attribute Setter Builder
How to use the Lookup Table Builder
The Select builder adds a <input type=select/> tag to one or more pages in the model. We can use a Select builder call whenever we need to present a user with a list of choices or options from which they will select one or more items.
Quick Tips
- Submit the form after a selection -- We can associate an Attribute Setter with a Select builder call to process any onChange events. For example, we can set the onChange event for a select box to submit the form by adding an Attribute Setter builder call to your model with the following input values:
- Page Location -- Set the Page Location to be the same Page Location value for the Select builder call.
- Attribute List -- Enter "onChange" for the Name. Enter "this.form.submit()" for the Value.
For more information, see "How to Use the Attribute Setter Builder."
Specifying Inputs
The Select builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor."
Input Name Description Name Enter a name for this builder call. The Designer displays this name in the Builder Call List. Page Location Use the Page Location input to specify the page or pages on which this builder call will act. See "Locating Control Builders on Pages" for detailed documentation about the Page Location input and page location syntax.
Select Data The source of the Select options to be displayed by the Select builder call. Possible sources include variables, inputs, method calls, and constant values. We can also enter a comma-delimited list of items. Here are some examples:
- Contents of an XML variable -- ${Variables/Products/Cameras}
- Output from a service call -- ${variables/serviceCallName_reply}
- Value of an input from a form -- ${Inputs/inputName}
- Comma-delimited list -- ListItem1, ListItem2, ListItem3
- Java collection - Specify a method or Java expression that returns an object that implements java.util.Collection or an Iterator for a Java collection. See "Specifying Lists," for more information.
In each of these cases (except for the comma-delimited list), the last item in the path should be the XML tag that "contains" the elements you want to display as options in the Select box.
You do not have to specify these paths by hand; we can use The Reference Chooser to navigate down to the appropriate element.
Since sources for Select lists are normally set to compound, multi-level structures such as service call outputs, it is crucial to select the proper level in that source.
For example, consider the following structure:
<THE_STRUCTURE>
<THE_LIST>
<THE_ITEMS>
<ITEM>
<NAME>Fred</NAME>
<AGE>22</AGE>
<SSN>111223333</SSN>
</ITEM>
<ITEM>
<NAME>Bob</NAME>
<AGE>35</AGE>
<SSN>222334444</SSN>
</ITEM>
</THE_ITEMS>
</THE_LIST>
</THE_STRUCTURE>This structure will be presented in a list of possible sources in the following ways (assuming it is stored in a variable):
Variables/THE_STRUCTURE
Variables/THE_STRUCTURE/THE_LIST
Variables/THE_STRUCTURE/THE_LIST/THE_ITEMS
Variables/THE_STRUCTURE/THE_LIST/THE_ITEMS/ITEM
Variables/THE_STRUCTURE/THE_LIST/THE_ITEMS/ITEM/NAME
Variables/THE_STRUCTURE/THE_LIST/THE_ITEMS/ITEM/AGE
Variables/THE_STRUCTURE/THE_LIST/THE_ITEMS/ITEM/SSNIn order to get the expected results, say, a list containing the various names, choose:
Variables/THE_STRUCTURE/THE_LIST/THE_ITEMS
as the Options source and specify ITEM/NAME as the value of the Text Key input.
Lookup Table Used This input replaces the Select Data input above if the model in which this Select builder is located also contains one or more Lookup Table builders. Use this input to choose the name of the Lookup Table builder call whose results you want to display with this Select builder call.
The Select builder call will display the results of the Lookup Table's builder's GetLookupTable method. The displayed content is determined by the Lookup Table builder call's "Value Tag" and "Label Tag " input settings.
Allow Multi Select Enable this check box if you want the user to be able to select more than one item from the list.
To access list items, use code similar to the following:
Iterator inputValues = webAppAccess.getRequestInputs().getInputValues(inputName);
while (inputValues.hasNext())
{
//do stuff..
}This code iterates through inputs with the same name in order to get to the values submitted by the multi select tag.
Selected Values The item you want to appear as the default selection in the list. The Selected Value specifies which item in the list should be automatically selected when the page containing the list is first displayed. The Selected Value can be specified as a constant value or as an indirect reference to a variable or method call.
To specify a specific element in an XML variable, use an indirect reference similar to the following:
${Variables/Artists/Artist[n]}
where [n] is an index pointing to the element you want to be selected by default. Indexing begins at 0.
To display a blank entry in the selection box, add a blank entry to the source list.
Retain original options Enable this checkbox if you want to retain the options listed for the original select box. Remove Duplicates Enable this checkbox if you want to remove duplicate options listed for the original select box. XML Data Source Elements Value Element If you specify an XML structure, enter the name of the element whose text value will be passed as the value for the selected option in the list. Label Element If you specify an XML structure, enter the name of the element whose text value will be listed as an option in the select list. HTML Attributes Size Enter a value to determine the number of options displayed to the user at one time. Example: 5
Class If you are using a Cascading Style Sheet (CSS) to set styles on the page, enter the name of the style class to use for this select box.