List

Overview

Since 3.1

The ace:list component is a powerful method of displaying data, providing a dynamically alterable list of the information given to it, to be controlled either by dragging or via the ace:listControl component.

See the ICEfaces Showcase Live Demo of this component, complete with source code.

Getting Started

<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
<h:body class="ice-skin-rime">
    <h:form>
        <ace:list value="#{listBean.itemList}" selections="#{listBean.selections}" selectionMode="multiple"/>
    </h:form>
</h:body>
</html>

Attributes

TagLib Documentation
This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available here.

value: An array of data that you wish to use for the list components. Each entry in the array will get its own cell in the list.

selections: A set (typically started empty) to contain the list of values that have been selected.

selectionMode: How the list allows selection of elements. 'single' allows one element to be selected at once, 'multiple' enables shift/control key presses to select more than one at a time. Anything else defaults to 'null' and does not allow any selections whatsoever.

dragging: Boolean value that specifies whether to enable dragging elements within the list. Defaults to true.

Client Behavior Events

Name	Description
select	Fired when an item is clicked & selected in the List.
deselect	Fired when an item is clicked & deselected in the List.
move	Fired when an item is moved within the List.
migrate	Fired when an item is migrated to this List.

Javascript API

ICEfaces 3.x

The client side component object is exposed through the global variable name specified in the widgetVar attribute.

ICEfaces 4+

The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use.

var widget = ice.ace.instance('frm:componentId);

The ice.ace.instance function requires the full client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use prependId="false" in the enclosing form (e.g. <h:form prependId="false">).

This component doesn't have a client-side API made specifically to be used by application developers. However, the component's internal methods and variables can be accessed in this way, including the underlying jQuery object and objects from underlying Javascript libraries (if applicable), and can be used for whatever purpose a developer might have in mind.

Other Tips

Note that the remove button always makes a request to the server, whether an ajax event is used or not. This is done in order to keep the list contents consistent. A confirmation dialog is displayed before sending the request.

CSS Classes

The following markup represents the basic HTML structure of the component and the CSS classes it uses.

<!-- Root container -->
<div class="[user defined classes] ui-widget-content ui-corner-all if-list-dl-cnt ui-widget" style="[user defined styles]">
	<!-- Header -->
	<div class="ui-state-default if-list-nctrl-head">
		Dual List Header
	</div>
	<div class="if-list-nctrls">
		<!-- Move all left button -->
		<span class="if-list-ctrl-spcr">
			<span class="if-list-nctrl-alll ui-state-default ui-corner-all if-list-nctrl">
				<span class="ui-icon ui-icon-arrowstop-1-w"></span>
			</span>
		</span>
		<!-- Move left button -->
		<span class="if-list-ctrl-spcr">
			<span class="if-list-nctrl-lft ui-state-default ui-corner-all if-list-nctrl">
				<span class="ui-icon ui-icon-arrow-1-w"></span>
			</span>
		</span>
		<!-- Move right button -->
		<span class="if-list-ctrl-spcr">
			<span class="if-list-nctrl-rgt ui-state-default ui-corner-all if-list-nctrl">
				<span class="ui-icon ui-icon-arrow-1-e"></span>
			</span>
		</span>
		<!-- Move all right button -->
		<span class="if-list-ctrl-spcr">
			<span class="if-list-nctrl-allr ui-state-default ui-corner-all if-list-nctrl">
				<span class="ui-icon ui-icon-arrowstop-1-e"></span>
			</span>
		</span>
	</div>
	<div class="if-list-dl">
		<!-- Left list -->
		<span class="if-list-dl-1">
			<div>
				<div class="subList <user defined classes> if-list ui-widget ui-widget-content ui-corner-all" style="<user defined styles>">
					<ul class="if-list-body dg-textGroup ui-sortable">
						<li class="if-list-item ui-state-default if-pntr">List item label</li>
					</ul>
				</div>
			</div>
		</span>
		<!-- Right list -->
		<span class="if-list-dl-2">
			<div>
				<div class="subList <user defined classes> if-list ui-widget ui-widget-content ui-corner-all" style="<user defined styles>">
					<ul class="if-list-body dg-textGroup ui-sortable">
						<li class="if-list-item ui-state-default if-pntr">List item label</li>
					</ul>
				</div>
			</div>
		</span>
	</div>
	<!-- Footer -->
	<div class="ui-widget-content if-list-nctrl-foot">
		Dual List Footer
	</div>
</div>