listToList JavaServer Page tag

Use the listToList JSP tag to define the appearance and behavior of a list-to-list control on a section, flow action, harness, or other HTML form. At runtime, the list-to-list control allows a user to interactively select multiple items from a source list and add them to a target list. After the form is submitted, the items on the target list become pages in a Page List property on the clipboard.

For example, a meeting may involve a dozen people from a department that has 100 employees.

In many situations, you can use the simpler list-to-list control to reference the standard ListToList control rather than hand-coding a non-autogenerated section that contains this JSP tag. However, the JSP tag offers many additional parameters and capabilities not available in the control.

Terminology

This diagram identifies the run time elements of the listToList tag:

ListToList

Complete syntax

In the syntax presentation below:

JSP delimiters <pega:...> and </pega:...> mark the start and end of the tag.
Items in square brackets are optional.
Vertical bar characters | separate choices.
Replace any text in italics with your choice of value of that type.

The <pega:include..> tag, which incorporates the HTML fragment named ListtoList_Variables, is required.

<pega:listToList
	[firstTitle="Source"]
	[secondTitle="Target"]
	[showMoveallAction = "none"|button"|caption"|"both"]
	[showMoveAction = "none"|button"|caption"|"both"]
	[showRemoveAction = "none"|button"|caption"|"both"]
	[showRemoveallAction = "none"|button"|caption"|"both"]
	[showMoveupdownAction = "none"|button"|caption"|"both"]
	[showSortingAction = "none"|button"|caption"|"both"]
	[style="styles"]
	[visible="true"|false"]
	[readOnly="true"|"false"]
	sourceProperty="page.property"
	targetProperty="page.property"
	[maximumItemsInTarget=”nnn”]
	[copyAllItems="true"|"false"]
	[displayProperty="property"]
	[displayImageProperty="property"]>
	[<pega:properties-mapping>
	<pega:property-mapping from="label" to="pyLabel"/>
	...
	</pega:properties-mapping>]
	</pega:listToList>
	<pega:include name="ListToList_Variables" type="Rule-HTML-Fragment" 
/>

The sourceProperty and targetProperty attributes are required. You can use literal constants, references to parameter values (param.name) and the special notation $SAVE(save variable) for values.

Attribute	Value
`firstTitle`	Optional. Caption to appear above the source list.
`secondTitle`	Optional. Caption to appear above the target list.
`showMoveallAction`	Optional. Select `none`, `button`, `caption`, or `both` to control whether the Move All function is available. If omitted, default is `button`.
`showMoveAction`	Optional. Select `none`, `button`, `caption`, or `both` to control whether the Move function is available. If omitted, default is `button`.
`showRemoveAction`	Optional. Select `none`, `button`, `caption`, or `both` to control whether the Remove function is available. If omitted, default is `button`.
`showRemoveallAction`	Optional. Select `none`, `button`, `caption`, or `both` to control whether the Remove All function is available. If omitted, default is `button`.
`showMoveupdownAction`	Optional. Select `none`, `button`, `caption`, or `both` to control whether the Move up and Move down functions is available. If omitted, default is `button`.
`showSortingAction`	Optional. Select `none`, `button`, `caption`, or `both` to control whether the sorting function is available. If omitted, default is `button`.
`width`	Optional. Width in pixels of the <TABLE...> element that contains the control. If omitted, the default is 600 px.
`height`	Optional. Height of the source list and target lists. If omitted, the default is 200px.
`style`	Optional.CSS style applied to the entire table, overriding other CSS styles. May contain border, margin, padding and background-color tags. Default is "".
`visible`	Optional. Entire control is hidden if " `false` ". Default is " `true` ".
`readOnly`	Optional. All control elements disabled if " `true` ". Default is " `false` ".
`sourceProperty`	Identify the page and property name of the source `Page List` property. If you omit the page name, the current primary page is assumed.
`targetProperty`	Identify the page and property name of the target `Page List` property. If you omit the page name, the current primary page is assumed.
`maximumItemsInTarget`	Optional. Enter a positive integer to limit the maximum number of items in the target list. If omitted, the default maximum is 200.
`copyAllItems`	If " `true` ", all properties on the embedded pages of the selected source items are copied into the embedded pages of the target property. If " `false` ", only those properties defined through the <pega:properties-mapping> tag are copied, possibly under different names. See properties-mapping JSP tag.

Example

This example JSP tag includes styles and a property mapping:

<pega:save name="ReadOnly" value="false" />
	<pega:save name="FirstName" value="Source" />
	<pega:save name="SecondName" value="Target" />
	<pega:save name="ShowMoveallAction" value="none" />
	<pega:listToList
		firstTitle="$save(FirstName)"
		secondTitle="$save(SecondName)"
		showMoveallAction = "$save(ShowMoveallAction)"
		showMoveAction = "button"
		showRemoveAction = "caption"
		showRemoveallAction = "both"
		style="background-color:#EEEECC;border:2px solid #AA0000;"
		visible="true"
		readOnly="$save(ReadOnly)"
		maximumItemsInTarget="40"
		sourceProperty="pyWorkPage.SourcePage.pyLines" targetProperty="pyWorkPage.TargetPage.pyLines"
		copyAllItems="false"
		displayProperty=".label"
		displayImageProperty=".image">
		<pega:properties-mapping>
		<pega:property-mapping from=".label" to=".pyLabel"/>
		<pega:property-mapping from=".image" to="img"/>
		<pega:property-mapping from="value" to=".price"/>
		<pega:property-mapping from="elegancy" to=".awkward"/>
		</pega:properties-mapping>
	</pega:listToList>
<p:include name="ListToList_Variables" type="Rule-HTML-Fragment" />

A listToList JSP tag must appear within an HTML <FORM element> and must be registered by a call to the standard JavaScript function registerOnBeforeSubmit (), which ensures a callback when the form is submitted. This registration happens automatically when the control at runtime is within a harness-generated user form.

To test a listToList tag in a standalone HTML rule (rather than in the runtime context of a harness), follow this example:

<html>
	<script>
	var callBack, listToListObj;
	function registerOnBeforeSubmit(aCallBack, obj)
	{
	callBack = aCallBack;
	listToListObj = obj;
	}

function do_submit()
	{
	var success = callBack(listToListObj);
	if (success == false)
		return false; //don't submit the data.
	}
	</script>
	<h3>ListToList widget</h3>
	<pega:include name="DesktopWrapperInclude" />
	<pega:include name="WorkformStyles" />
	<pega:include name="ListToList_Variables" type="Rule-HTML-Fragment" />
	<body>
		<form onSubmit="do_submit()" method="post"
		action="<p:url value="[email protected]" >
		<p:option name="primary" /></p:url>" >
		<pega:listToList sourceProperty="operpage.pxResults" targetProperty="testpage.pageList"/>
		<input type='submit' value='Go' >
		</form>
	</body>
</html>

JavaServer Page tags