List Builder

List Builder

In this topic ...

Quick Tips
Specifying Inputs
Storing the Source and Target in Variables
Processing the Input Values of the Target List
Example: Using the List Builder
Related Topics ...

Overview: Creating Forms

Use the List Builder to create a composite control that allows a user to build a list from a set of available items. The List Builder presents the user with two select lists, and a set of command buttons to operate on the items in the lists (Add, Remove, Add all, and Remove all). The available item list is called the "Source" list. The list that is created from items in the Source list is called the "Target" list. The List Builder lets you specify the orientation of the lists.
The List Builder generates multiple HTML components as a group. As a result, an internal name is given to the Source list. The "size" attribute value is set for both lists. Both lists are always multi-selectable. Other attribute settings of this Builder are only set to the list's HTML component's attributes.

Quick Tips

Multi-select list items -- We can select more than one item in the source and target lists by holding the CTRL key while selecting multiple options from the list.

Specifying Inputs

The List 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. Alternatively, we can type in the page location syntax directly.
See "Locating Control Builders on Pages" for detailed documentation about the Page Location input and page location syntax.

Orientation

Choose between positioning the two list boxes horizontally (side by side) or vertically (one above the other).
Source List Title Type a title for the source list or an indirect reference to the title. For example, ${Variables/SourceTitle}
where SourceTitle is the name of the variable of type String that stores the title of the source list.
Source List Options Specify data returned from a Function, Method, Service Call, or Variable. The List builder also accepts a reference to an object that implements java.util.Collection or an Iterator for a Java collection. See "Specifying Lists," for more information. We can also enter a comma-delimited list.
Here are some examples:

For a database query : ${Variables/ResultSetXml/RowSet}
For a service call: ${Variables/MyServiceCall_reply/Order/Items}
For a Variable containing XML: ${Variables/Products}
For a comma-delimited list: ListItem1,ListItem2,ListItem3
For a collection: ${Java/webAppAccess.getRequestInputs().getInputValues("myInput")}

In each of these cases (except for the comma-delimited list and collection), the last item in the path should be the XML tag that "contains" the elements you want to display as options in the List box.
Note that You do not have to specify these paths by hand; we can use the Reference Chooser, which is located to the left of the field.
XML Datasource Elements for Source List

Source Value Element

If you entered an indirect reference in the Source List Option field to a source list defined in XML hierarchy, specify which element is used for the values. If you did not enter an indirect reference in the Source List Option field, any value entered in the Source Value Element field is ignored.
Do one of the following:

Enter a name for the tag.

Enter an indirect references for the tag. The value would be stored in a variable of type String.

For more information about the source value element, see "Storing the Source and Target in Variables."

Source Label Element

If you entered an indirect reference in the Source List Option field to a source list defined in XML hierarchy, specify which element is used for the label. Values assigned to this element appear in the source list. If you did not enter an indirect reference in the Source List Option, any value entered here is ignored.
Do one of the following:

Enter a name for the source label element.

Enter an indirect references for the source label element. The value would be stored in a variable of type String.

For more information about the source label element, see "Storing the Source and Target in Variables."

Target List Title

Type a title for the target list or an indirect reference to the title. For example,
${Variables/TargetTitle}
where TargetTitle is the name of the variable of type String that stores the title of the target list

Target List Options

To pre-populate the Target List with options, specify data returned from a function, method, service call, or variable. This data will be in XML. We can also specify a comma-delimited list.
After the user has made initial selections, the Target List will contain this input when it is subsequently displayed.
XML Datasource Elements for Target List

Target Value Element

If you entered an indirect reference in the Target List Option field to a target list defined in XML hierarchy, specify which element is used for the values.
Do one of the following:

Enter a name for the tag.

Enter an indirect references for the tag. The value would be stored in a variable of type String.

For more information about the target value element, see "Storing the Source and Target in Variables."

Target Label Element

If you entered an indirect reference in the Target List Option field to a target list defined in XML hierarchy, specify which element is used for the label. Values assigned to this element appear in the source list. If you did not enter an indirect reference in the Target List Option, any value entered here is ignored.
Do one of the following:

Enter a name for the target label element.

Enter an indirect references for the target label element. The value would be stored in a variable of type String.

For more information about the target label element, see "Storing the Source and Target in Variables."
User Interface Overrides

Base Page URL

Use this input if you want to substitute custom HTML for the basic structure of the list.
The Base Page URL indicates an HTML file that the builder will import at regen time and insert at the specified page location to provide the structure and layout of the UI generated by the builder.
This HTML will be modified by the List builder after being inserted into the target page to hook the UI elements to their behavior (e.g., filling the lists with data, creating "onclick" event handlers on the Add/Remove buttons to do the adding/removing, etc.)
By default, if no value is given for this input, the builder uses the HTML in either /factory/pages/list_builder_horizontal.html or /factory/pages/list_builder_vertical.html, depending on the selected orientation. Click here for additional information.

"Add" Button Text

Actual, or indirect reference to, text to be used for this button.

"Remove" Button Text

Actual, or indirect reference to, text to be used for this button.

"Add All" Button Text

Actual, or indirect reference to, text to be used for this button.

"Remove All Button Text

Actual, or indirect reference to, text to be used for this button.

Storing the Source and Target in Variables

We can store the source and targets in variables of type XML. The source would be stored in one variable and the target would be stored in another. When you store the source, store it in XML format.
After you create the variable, make sure you specify the elements for the value in the Source Value Element or Target Value Element field in the builder call editor of the List Builder. Likewise, the elements for the labels appearing in the list should be assigned to the Source Label Element or Target Label Element field in the builder call editor of the List Builder.
The following example could be used for the source or target:
<Pets>
  <Pet><name>Cat</name><id>1</id></Pet>
  <Pet><name>Dog</name><id>2</id></Pet>
  <Pet><name>Fish</name><id>3</id></Pet>
  <Pet><name>Reptile</name><id>4</id></Pet>
  <Pet><name>Bird</name><id>5</id></Pet>
</Pets>
where

name is the value entered in the Source Label Element or Target Label Element field
id is the value entered in the Source Value Element or Target Value Element field

In the example above, the values of the name element are displayed in the list and the values of the id element are the values passed.

Processing the Input Values of the Target List

We can retrieve the values submitted by the List Builder by using webAppAccess.getRequestInputs().getInputValues("builder_call_name") equal to a variable of type Iterator. This returns an Iterator object. See http://java.sun.com for more information about the Iterator object. The following code sample retrieves the values submitted by the List Builder and then loops through the Iterator and builds a String. This String is then assigned to a variable which can be used to display the results.
For example:
Iterator i = webAppAccess.getRequestInputs().getInputValues("ListBuilderplaceholder");

String results = "";
while (i.hasNext())
  {
    results += i.next();
    results += "<br>";
  }
webAppAccess.getVariables().setString("target_list_display", results);
where

ListBuilderplaceholder is the span tag assigned to the List Builder
results is the variable used to display the results
target_list_display is the variable is used to hold the values at runtime

An Example of Using the List Builder

Let's assume you are creating a survey for your customers. As part of this survey, you want them to select their hobbies. You could use the List Builder to create a list. The following is an example of one technique for doing this.

In the model for the survey, make sure you have a method called main that calls up the page. If you selected Main_and_Page as the model type when you created the model, the method to call up the first page would have been added automatically in the Action List Builder.
Make sure a span tag has been created for a List Builder and Button Builder, as shown below:

<html>
<head><title>What are your hobbies?</title></head>
<body><form>
<div align="center" style="font:12pt Arial;font-weight: bold;color: #336699;">Please select your hobbies:</div>
<div align="center">
<span name="ListBuilderplaceholder"/><br>
<span name="buttonplaceholder"/><br>
</div>
</form></body></html>

Add a List Builder call to the model, and do the following:

Select the page from Step 2 and a placeholder for the List Builder... ListBuilderplaceholder
In the Source List Title field, enter a title for the source list... Hobbies
In the Source List Options, enter a list for the list of options... Aerobics,Astronomy,Cooking,Reading,Running,Singing,Swimming

In the Target List Title field, enter a target for the title list... Your Hobbies
The menu can be displayed vertically or horizontally. From the Orientation menu, select horizontal. This item determines the orientation of the menu. The menu can be displayed vertically or horizontally with the default buttons in a row.
Leave the rest of the fields blank.

Add a Page builder call to the model. This page is used to display the items the user selected for the target list. Make sure it contains a span tag for the Text field...

<html><body><form>
<div align="center" style="font:12pt Arial;font-weight: bold;color: #336699;">
  You selected the following hobbies:
  <br>
  <font style="font:10pt Arial">
  <span name="displayText"/><br>
</div>
</form></body></html>

Add a Button Builder call to the model, and do the following:

Select the page from Step 2 and the placeholder for the Button Builder, such as Buttonplaceholder.
In the Label field, type a label for the button... Display Results
From the Action Type drop-down menu, select Submit form and invoke action.
In the Action field, type the name of the page created in Step 4... page2

Add a Variable Builder call to the model of type String. This variable can be left blank, because it is used to store the target list at run time. Let's call the Variable Builder target_list_display.

Add a Text Builder call to the model. Assign it to the page you created in Step 4. The results from the target list will be displayed in the location of the Text Builder's span tag. In the Default Text field, enter an indirect reference to the variable create in Step 6, for example: ${Variables/target_list_display}

Make sure the option, Allow HTML formatting of text, is selected.

Add a Method Builder call or a Linked Java Builder call. The Builder should contain the code you want to manipulate the values in the target list.

The code below tells the Factory to go through the list of target values and print them.
For example:
{
  Iterator i = webAppAccess.getRequestInputs().getInputValues("ListBuilderplaceholder");
  String results = "";
  while (i.hasNext())
  {
    results += i.next();
    results += "<br>";
  }
  webAppAccess.getVariables().setString("target_list_display", results);
}
where

ListBuilderplaceholder is the span tag assigned to the List Builder (created in Step 2)
results is the variable used to display the results
target_list_display is the Builder call name of the Variable Builder created in Step 6

The Text Builder interprets the value of the results variable as HTML. Thus, the HTML break tag (<br>) was used to print each item on its own line, instead of \n, which would have been ignored by the Web browser.

Add an Event Handler Builder call to the model. When the page created in Step 4 loads, the event handler triggers the method that contains the action you want.

In the Name field, specify a builder call name for the Event Handler Builder.
From the Event Name select list, choose the OnPageLoad event for the page created in Step 4.
In the Action field, use the pick list to select the method created in Step 8.

When the page created in Step 4 loads, the event handler triggers the method that processes the List Builder values.

Run the model. Make some selections in the list builder and click the "Display Results" button. The second page should appear and it should display the values selected in the List Builder.

Instead of using a loop in the method to obtain the values, a Repeated Region Builder could have been used. This technique lets you use fewer builders to achieve the same result. The following steps explain how you would modify the example above so you could use the Repeated Region Builder:

Remove the Variable, Event Handler, and Method builders from the model you created in the previous section.
Add a span tag for the Repeated Region Builder to page2, as shown below:

<html><body><form>
<div align="center" style="font:12pt Arial;font-weight: bold;color: #336699;">
  You selected the following hobbies:
  <br>
  <font style="font:10pt Arial">
  <span name="repeatregionplaceholder">
  <span name="displayText"/><br>
</div>
</form></body></html>

where

repeatregionplaceholder is the span tag for the Repeated Region Builder
displayText is the span tag for the Text Builder
Add the Repeated Region Builder call to the model, and do the following:

In the Name field, name the Repeated Region Builder.
Assign the Repeated Region Builder to the span tag you created in Step 2.
In the Source Data Field, enter the following code:

${Java/webAppAccess.getRequestInputs().getInputValues("ListBuilderplaceholder")}
where ListBuilderplaceholder is the span tag assigned to the List Builder

In the Loop Variable enter the variable name target_list_display. If you enter a different name, modify the Default Text field in the Text Builder so that it points to the correct variable.

Run the model. Make some selections in the list builder and click the "Display Results" button. The second page should display the values selected in the List Builder.

Using UI Overrides for Internationalization

The "User Interface Overrides" allow you to specify text for each of the buttons generated by the List builder. We can use an indirect reference or enter button text directly . There is also an input in this section ("Base Page URL") that lets you substitute custom HTML for the basic structure of the list.
The two default HTML pages (in factory/pages: list_builder_horizontal.html and list_builder_vertical.html) have named elements and styles, and builders can target these to make more subtle overrides without having to swap out the base HTML.
In most cases, we can fine tune the appearance of the List Builder-generated UI either by providing a CSS stylesheet (the classes listBuilderOuterTable, listBuilderTitle or listBuilderSelect are used in the default HTML) or by targeting the named elements (prefixed by "list") with other builders, such as Attribute Setter.
If we need to make a more drastic visual change, we can supply your own HTML to serve as a base. This HTML must have elements with the same names as are present in the default HTML files, and must retain the JavaScript reference included in these files. The easiest way to construct a custom HTML base page is to copy either the horizontal or vertical default HTML page, and make the desired modifications.
We can also use images as buttons in three ways:

Use Image builders to override the buttons, targeting the "listAddButton", "listRemoveButton", "listAddAllButton" and "listRemoveAllButton" spans
Use images instead of the buttons in a custom base HTML page
Target Image Button builders at the button elements like Image above, and use a "do-nothing" script as the action (e.g., void 0)

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. Alternatively, we can type in the page location syntax directly. See "Locating Control Builders on Pages" for detailed documentation about the Page Location input and page location syntax.
Orientation	Choose between positioning the two list boxes horizontally (side by side) or vertically (one above the other).
Source List Title	Type a title for the source list or an indirect reference to the title. For example, `${Variables/SourceTitle}` where `SourceTitle` is the name of the variable of type String that stores the title of the source list.
Source List Options	Specify data returned from a Function, Method, Service Call, or Variable. The List builder also accepts a reference to an object that implements java.util.Collection or an Iterator for a Java collection. See "Specifying Lists," for more information. We can also enter a comma-delimited list. Here are some examples: For a database query : ${Variables/ResultSetXml/RowSet} For a service call: ${Variables/MyServiceCall_reply/Order/Items} For a Variable containing XML: `${Variables/Products}` For a comma-delimited list: ListItem1,ListItem2,ListItem3 For a collection: ${Java/webAppAccess.getRequestInputs().getInputValues("myInput")} In each of these cases (except for the comma-delimited list and collection), the last item in the path should be the XML tag that "contains" the elements you want to display as options in the List box. Note that You do not have to specify these paths by hand; we can use the Reference Chooser, which is located to the left of the field.
XML Datasource Elements for Source List
Source Value Element	If you entered an indirect reference in the Source List Option field to a source list defined in XML hierarchy, specify which element is used for the values. If you did not enter an indirect reference in the Source List Option field, any value entered in the Source Value Element field is ignored. Do one of the following: Enter a name for the tag. Enter an indirect references for the tag. The value would be stored in a variable of type String. For more information about the source value element, see "Storing the Source and Target in Variables."
Source Label Element	If you entered an indirect reference in the Source List Option field to a source list defined in XML hierarchy, specify which element is used for the label. Values assigned to this element appear in the source list. If you did not enter an indirect reference in the Source List Option, any value entered here is ignored. Do one of the following: Enter a name for the source label element. Enter an indirect references for the source label element. The value would be stored in a variable of type String. For more information about the source label element, see "Storing the Source and Target in Variables."
Target List Title	Type a title for the target list or an indirect reference to the title. For example, ${Variables/TargetTitle} where TargetTitle is the name of the variable of type String that stores the title of the target list
Target List Options	To pre-populate the Target List with options, specify data returned from a function, method, service call, or variable. This data will be in XML. We can also specify a comma-delimited list. After the user has made initial selections, the Target List will contain this input when it is subsequently displayed.
XML Datasource Elements for Target List
Target Value Element	If you entered an indirect reference in the Target List Option field to a target list defined in XML hierarchy, specify which element is used for the values. Do one of the following: Enter a name for the tag. Enter an indirect references for the tag. The value would be stored in a variable of type String. For more information about the target value element, see "Storing the Source and Target in Variables."
Target Label Element	If you entered an indirect reference in the Target List Option field to a target list defined in XML hierarchy, specify which element is used for the label. Values assigned to this element appear in the source list. If you did not enter an indirect reference in the Target List Option, any value entered here is ignored. Do one of the following: Enter a name for the target label element. Enter an indirect references for the target label element. The value would be stored in a variable of type String. For more information about the target label element, see "Storing the Source and Target in Variables."
User Interface Overrides
Base Page URL	Use this input if you want to substitute custom HTML for the basic structure of the list. The Base Page URL indicates an HTML file that the builder will import at regen time and insert at the specified page location to provide the structure and layout of the UI generated by the builder. This HTML will be modified by the List builder after being inserted into the target page to hook the UI elements to their behavior (e.g., filling the lists with data, creating "onclick" event handlers on the Add/Remove buttons to do the adding/removing, etc.) By default, if no value is given for this input, the builder uses the HTML in either /factory/pages/list_builder_horizontal.html or /factory/pages/list_builder_vertical.html, depending on the selected orientation. Click here for additional information.
"Add" Button Text	Actual, or indirect reference to, text to be used for this button.
"Remove" Button Text	Actual, or indirect reference to, text to be used for this button.
"Add All" Button Text	Actual, or indirect reference to, text to be used for this button.
"Remove All Button Text	Actual, or indirect reference to, text to be used for this button.