META-INF.maven-faces-plugin.components.trinidad.Iterator.xml Maven / Gradle / Ivy

Go to download
<?xml version="1.0" encoding="utf-8"?>
<!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
	   
-->
<faces-config version="2.0" xmlns="http://java.sun.com/xml/ns/javaee"
              xmlns:tr="http://myfaces.apache.org/trinidad"
              xmlns:xi="http://www.w3.org/2001/XInclude"
              xmlns:mfp="http://myfaces.apache.org/maven-faces-plugin"
              xmlns:fmd="http://java.sun.com/xml/ns/javaee/faces/design-time-metadata">
  <component>
    <description><![CDATA[UIXIterator is a component that performs iteration
over its child components.  It is like a UIXTable without any chrome.
While functionally similar to a forEach tag, an iterator is a component
that does its processing during rendering, while forEach runs during
the assembly of the component tree, and doesn't leave behind a component in the
heirarchy. ]]></description>
    <icon>
      <!-- small-icon>/org/apache/myfaces/trinidadinternal/metadata/icons/iterator.png</small-icon -->
    </icon>
    <component-type>org.apache.myfaces.trinidad.Iterator</component-type>
    <component-class>org.apache.myfaces.trinidad.component.UIXIterator</component-class>
    <property>
      <description><![CDATA[<html>
 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:
          <ul>
            <li>"model" - returns the CollectionModel for this component.</li>
            <li>"index" - returns the zero based row index.</li>
            <li>"hierarchicalIndex" - returns an array containing zero based row index.</li>
            <li>"hierarchicalLabel" - returns a string label representing 1 based index of this row.</li>
            <li>"rowKey" - returns the current rowKey in the collection.</li>
            <li>"current" - returns the current row in the collection.</li>
          </ul></html>]]>
      </description>
      <property-name>varStatus</property-name>
      <property-class>java.lang.String</property-class>
      <property-extension>
        <mfp:property-metadata/>
        <fmd:property-metadata>
          <fmd:preferred>true</fmd:preferred>
          <fmd:value-expression>PROHIBITED</fmd:value-expression>
        </fmd:property-metadata>
      </property-extension>
    </property>
    <property>
      <description><![CDATA[the data model being used by this component.
The specific model class is
        <code>org.apache.myfaces.trinidad.model.CollectionModel</code>.

        You may also use other model instances, e.g.,  
        <code>java.util.List</code>  ,
        array, and  <code>javax.faces.model.DataModel</code>.
        This component will automatically convert the instance
        into a <code>CollectionModel</code>.]]>
      </description>
      <property-name>value</property-name>
      <property-class>java.lang.Object</property-class>
      <property-extension>
        <mfp:property-metadata/>
        <fmd:property-metadata>
          <fmd:preferred>true</fmd:preferred>
        </fmd:property-metadata>
      </property-extension>
    </property>
    <property>
      <description><![CDATA[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.]]>
      </description>
      <property-name>rows</property-name>
      <property-class>int</property-class>
      <default-value>25</default-value>
      <property-extension>
        <mfp:property-metadata/>
        <fmd:property-metadata>
          <fmd:preferred>true</fmd:preferred>
        </fmd:property-metadata>
      </property-extension>
    </property>
    <property>
      <description><![CDATA[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.]]>
      </description>
      <property-name>first</property-name>
      <property-class>int</property-class>
      <default-value>0</default-value>
    </property>
    <component-extension>
      <mfp:component-family>org.apache.myfaces.trinidad.Iterator</mfp:component-family>
      <mfp:component-supertype>org.apache.myfaces.trinidad.CollectionBase</mfp:component-supertype>
      <mfp:component-superclass>UIXCollection</mfp:component-superclass>
      <mfp:tag-name>tr:iterator</mfp:tag-name>
      <mfp:tag-class>org.apache.myfaces.trinidadinternal.taglib.UIXIteratorTag</mfp:tag-class>
      <mfp:long-description><![CDATA[<p>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 &quot;first&quot; attribute,
 for as many indices as specified by the &quot;rows&quot; attribute.
 If &quot;rows&quot; returns 0, then the iteration continues until 
 there are no more elements in the underlying data.
 </p>
 <p> 
  While the &lt;tr:forEach&gt;
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 &quot;var&quot; variable on an &lt;tr:table&gt;), because
a forEach tag runs during
The &lt;tr:iterator&gt; tag was created to
address these issues.
</p>
<p>
To list all, the benefits of UIXIterator over forEach:
<ul>
<li>Access to component-managed EL variables</li>
<li>Full support for CollectionModel and DataModel</li>
<li>Does not require creating multiple copies of children,
so more memory efficient</li>
<li>Much better at dealing with adding and deleting children,
at least when used with a CollectionModel with a good
implementation of getRowKey()</li>
<li>Supports "binding", and all other forms of JSF component
manipulation</li>
</ul>
and the negative aspects:
<ul>
<li>Leaves behind a component in the hierarchy, which causes
problems with components like panelFormLayout that try to handle each child
individually.</li>
<li>Because there's only one of each child, the same limitations
on "binding", etc., as apply inside a table also apply to iterator.</li>
</ul>
</p>
<p>By default, it processes up to 25 rows. Use the rows attribute to alter this behavior.</p>
]]>
      </mfp:long-description>
      <mfp:author>Arjuna Wijeyekoon</mfp:author>
    </component-extension>
  </component>
</faces-config>