List Cell Layout

Purpose

This component can be used to create and manage the list cell layout for a specified list view.

Exported Features

cf2:ui.ListCellLayout

Imported Features

n/a

Markup

This component is provided by the ui:list-cell-layout element.

List Cell Layout Factory API

A layout factory implements the List Cell Layout Factory API and is responsible for creating the layout instance when requested by the selected list view. A single factory can create multiple layout instances. The List Cell Layout Factory API provides the following methods:

createLayout(info)

Returns the layout instance that will manage the layout for the invoking list view. The list view invokes this method during its starting phase.

Parameter	Description	Type
info	The information used to create the layout. It can contain the following properties:

Parameter	Description	Type
view	The invoking list view.	ListView
renderItem	A function provided by the list view to the layout.	Function
createCell	A function provided to allow the layout to create cell elements.	Function
updateWindow	A function provided to allow update the window properties.	Function
inner	A function provided to get the inner element of the list view.	Function

As part of the information passed to the createLayout() method the following functions are provided. Please note that the functions are bound to the invoking instance of the list view.

renderItem(info)

Renders the item into a cell, possibly reusing the supplied presentation.

Parameter	Description	Type
info	The information needed to render the item into a specific cell.

Parameter	Description	Type
cell	The cell into which the item presentation will be added.	ListViewCell
index	The index of the item within the model.	Integer
presentation	The current presentation of an item. If the value of the parameter is not null, then it will already have been rendered into the cell. The purpose of this parameter is to enable reuse of the presentation to improve efficiency. If the presentation can be reused, then it is modified and returned; otherwise it can simply be ignored.	Presentation

createCell()

Creates a cell and returns it.

updateWindow(info)

Updates the window properties.

Parameter	Description	Type
info	The information needed to update the window properties.

Parameter	Description	Type
first	The index of the first item in the window.	Integer
last	The index of the last item in the window.	Integer
count	The number of items in the window.	Integer

inner()

Gets the DOM element that is the parent of the cells.

A cell is a Map with the following two properties: outer and inner. The outer property represents the outer DOM element for the cell. This element can be used to position the cell within the list view. The inner property represents the inner DOM element for the cell. The list view will add the presentation of the items as a child of this element. Please note that the inner and outer elements may sometimes be the same.

Component class - List Cell Layout Factory API

The List Cell Layout Factory interface class defines a type and any component that implements this interface must declare that it implements the ui:ListCellLayoutFactoryAPI type.

<cx:component-class xmlns:cf2="http://www.volantis.com/xmlns/2009/07/cf2"
  xmlns:cx="http://www.volantis.com/xmlns/2010/07/cf2/cx"
  xmlns:ui="http://www.volantis.com/xmlns/2009/07/cf2/ui"
  name="ui:ListCellLayoutFactoryAPI"
  defines="all">
</cx:component-class>

List Cell Layout API

A layout instance defines the layout of items within a list view. It manages the creation, positioning and styling of cells, along with rendering of item presentation into the cell. Please note that the creation and rendering are actually performed by callbacks provided by the list view. It also updates the layout in response to changes in the underlying model which are detected by the list view and passed through to the layout, and in response to changes in the window. In addition, it provides feedback to the list view about the window of currently displayed items. Each layout instance must implement the List Cell Layout API and is intended to be used by a single list view. The List Cell Layout API provides the following methods:

move(info)

Moves the window by the specified number of items. The method returns the position and the size of the window after the move as a ListItemWindow.

Parameter	Description	Type
info	The information used to calculate the new position of the window and to move it. The info parameter can contain the following information:

Parameter	Description	Type
delta	Positive values move the window forward in the model, while negative values move the window backwards. The value of '0' has no effect.	Integer
atomic	If this parameter is set to 'false', then the window is moved as far as possible up to the specified item. If this parameter is set to 'true' and the window cannot move as requested, then it does not move at all.	Boolean

canMove(info)

Checks to see whether the window can be moved by the specified number of items. The method returns the position and the size of the window after the move as a ListItemWindow.

Parameter	Description	Type
info	The information used to check whether the window can be moved as requested. The info parameter can contain the following information:

Parameter	Description	Type
delta	Positive values move the window forward in the model, while negative values move the window backwards. The value of '0' has no effect.	Integer
atomic	If this parameter is set to 'false', then the window is moved as far as possible up to the specified item. If this parameter is set to 'true' and the window cannot move as requested, then it does not move at all.	Boolean

update(info)

Updates the items affected by the event or window change. The method returns the window being displayed as a ListItemWindow.

Parameter	Description	Type
info	The information used to update the window. The info parameter can contain the following information:

Parameter	Description	Type
delta	Positive values move the window forward in the model, while negative values move the window backwards. The value of '0' has no effect.	Integer
atomic	If this parameter is set to 'false', then the window is moved as far as possible up to the specified item. If this parameter is set to 'true' and the window cannot move as requested, then it does not move at all.	Boolean
event	The event that triggered the update. This may be null, if it was caused by changes to the window rather than the underlying model.	Event

The following information is provided to the layout whenever the window needs recalculating.

A ListItemWindow contains the following properties:

Properties

The following table lists the observable properties associated with this component.

Events

If the layout changes the window itself, i.e. other than as a result of calls from the list view, e.g. because its own state has changed, or for those layouts that are sensitive to it because the size of the list view box has changed, then the list cell layout fires a cf2:listItemWindowChanged event.

cf2:listItemWindowChanged

Property	Description	Type
target	The list cell layout that fired the event.	ListCellLayout
oldWindow	The old list view window.	ListItemWindow
newWindow	The new list view window.	ListItemWindow

Related topics

• List View
• List Model API
• List Item Renderer API
• User interface components
• ui:list-view