Project Documentation

Summary

Tag name: <tr:iterator>
UIComponent class: org.apache.myfaces.trinidad.component.UIXIterator
Component type: org.apache.myfaces.trinidad.Iterator

Naming container: Yes. When referring to children of this component ("partialTriggers", findComponent(), etc.), you must prefix the child's ID with this component's ID and a colon (':').

UIXIterator is a component that performs iteration over its child components. It is similar to UIXTable but has no chrome. Each child is repeatedly stamped as many times as necessary. Iteration is done starting at the index given by the "first" attribute, for as many indices as specified by the "rows" attribute. If "rows" returns 0, then the iteration continues until there are no more elements in the underlying data.

While the <tr:forEach> will be sufficient for most user's needs, it does not work with a JSF DataModel, or CollectionModel. It also cannot be bound to EL expressions that use component-managed EL variables (such as the "var" variable on an <tr:table>), because a forEach tag runs during The <tr:iterator> tag was created to address these issues.

To list all, the benefits of UIXIterator over forEach:

  • Access to component-managed EL variables
  • Full support for CollectionModel and DataModel
  • Does not require creating multiple copies of children, so more memory efficient
  • Much better at dealing with adding and deleting children, at least when used with a CollectionModel with a good implementation of getRowKey()
  • Supports "binding", and all other forms of JSF component manipulation
and the negative aspects:
  • Leaves behind a component in the hierarchy, which causes problems with components like panelFormLayout that try to handle each child individually.
  • Because there's only one of each child, the same limitations on "binding", etc., as apply inside a table also apply to iterator.

By default, it processes up to 25 rows. Use the rows attribute to alter this behavior.

Events

Type Phases Description
org.apache.myfaces.trinidad.event.AttributeChangeEventInvoke Application,
Apply Request Values
Event delivered to describe an attribute change. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change event might include the width of a column that supported client-side resizing.

Attributes

Name Type Supports EL? Description
attributeChangeListenerjavax.el.MethodExpressionOnly EL a method reference to an attribute change listener. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change events might include the width of a column that supported client-side resizing.
bindingorg.apache.myfaces.trinidad.component.UIXIteratorOnly EL an EL reference that will store the component instance on a bean. This can be used to give programmatic access to a component from a backing bean, or to move creation of the component to a backing bean.
firstintYes Default Value: 0

the index of the first row in the currently range of rows. This index is zero-based. This attribute is used to control which range of rows to display to the user.
idStringNo the identifier for the component. The identifier must follow a subset of the syntax allowed in HTML:
  • Must not be a zero-length String.
  • First character must be an ASCII letter (A-Za-z) or an underscore ('_').
  • Subsequent characters must be an ASCII letter or digit (A-Za-z0-9), an underscore ('_'), or a dash ('-').
renderedbooleanYes Default Value: true

whether the component is rendered. When set to false, no output will be delivered for this component (the component will not in any way be rendered, and cannot be made visible on the client). If you want to change a component's rendered attribute from false to true using PPR, set the partialTrigger attribute of its parent component so the parent refreshes and in turn will render this component.
rowsintYes Default Value: 25

the maximum number of rows to display in a single range of rows. Some ranges might have fewer than the number of rows specified by this attribute (eg: the last range might have an insufficient number of rows). To display all rows at once, set this attribute to 0. The default is 25.
valueObjectYes the data model being used by this component. The specific model class is org.apache.myfaces.trinidad.model.CollectionModel. You may also use other model instances, e.g., java.util.List , array, and javax.faces.model.DataModel. This component will automatically convert the instance into a CollectionModel.
varStringNo Name of the EL variable used to reference each element of this collection. Once this component has completed rendering, this variable is removed (or reverted back to its previous value).
varStatusStringNo Name of the EL variable used to reference the varStatus information. Once this component has completed rendering, this variable is removed (or reverted back to its previous value). The VarStatus provides contextual information about the state of the component to EL expressions. For components that iterate, varStatus also provides loop counter information. Please see the this component's documentation for the specific properties on the varStatus. The common properties on varStatus include:
  • "model" - returns the CollectionModel for this component.
  • "index" - returns the zero based row index.
  • "hierarchicalIndex" - returns an array containing zero based row index.
  • "hierarchicalLabel" - returns a string label representing 1 based index of this row.
  • "rowKey" - returns the current rowKey in the collection.
  • "current" - returns the current row in the collection.