META-INF.maven-faces-plugin.components.trinidad.Tree.xml Maven / Gradle / Ivy
<?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[Represents an interactive tree component.]]></description>
<icon>
<!-- small-icon>/org/apache/myfaces/trinidadinternal/metadata/icons/baseTree.png</small-icon -->
</icon>
<component-type>org.apache.myfaces.trinidad.Tree</component-type>
<component-class>org.apache.myfaces.trinidad.component.UIXTree</component-class>
<xi:include href="includes/CommonTableAttrs.xml" xpointer="/faces-config/component/*"/>
<xi:include href="includes/RowDisclosureEvent.xml" xpointer="/faces-config/component/*"/>
<xi:include href="includes/DisclosedRowKeys.xml" xpointer="/faces-config/component/*"/>
<xi:include href="includes/SelectionEvent.xml" xpointer="/faces-config/component/*"/>
<facet>
<description><![CDATA[the component to use to stamp each element in the
tree. Only certain types of components are supported,
including all
components with no behavior and most components that implement the
EditableValueHolder or ActionSource interfaces. In a treeTable, this must be a column.]]>
</description>
<facet-name>nodeStamp</facet-name>
</facet>
<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 the row indices of heirarchy of the currrent row, for e.g. [0,1,2]
Please use this attribute with caution since it requires moving currency to calculate the row index for
each parent collection in the tree hierarchy.
</li>
<li>"hierarchicalLabel" - returns a string label representing the hierarchy of that row, for e.g. 1.1, 1.1.1.
It should be noted that the labels are 1 based vs 0 based for rowIndex.
Please use this attribute with caution since it requires moving currency to calculate the row index for
each parent collection in the tree hierarchy.
</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 hierarchy of tree data - must be of type
org.apache.myfaces.trinidad.model.TreeModel]]></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 rowKey of the currently focused row.
The rowKeys of the ancestor rows of the focus row are added
to the expandedRowKeys RowKeySet by default.]]>
</description>
<property-name>focusRowKey</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[a method reference to a focus listener]]></description>
<property-name>focusListener</property-name>
<property-class>javax.el.MethodExpression</property-class>
<property-extension>
<mfp:method-binding-signature>
<mfp:parameter-type>org.apache.myfaces.trinidad.event.FocusEvent</mfp:parameter-type>
<mfp:return-type>void</mfp:return-type>
</mfp:method-binding-signature>
<mfp:property-metadata/>
<fmd:property-metadata>
<fmd:preferred>true</fmd:preferred>
</fmd:property-metadata>
</property-extension>
</property>
<property>
<description>
<![CDATA[If upon initial rendering, the current subtree under the focused row path
should be expanded. A RowDisclosureEvent is broadcast from the encode begin of the
component so that listeners are properly notified of the disclosure.]]>
</description>
<property-name>initiallyExpanded</property-name>
<property-class>boolean</property-class>
<default-value>false</default-value>
<property-extension>
<mfp:property-metadata/>
<fmd:property-metadata>
<fmd:preferred>true</fmd:preferred>
</fmd:property-metadata>
</property-extension>
</property>
<component-extension>
<mfp:component-family>org.apache.myfaces.trinidad.Tree</mfp:component-family>
<mfp:component-supertype>org.apache.myfaces.trinidad.CollectionBase</mfp:component-supertype>
<mfp:component-superclass>org.apache.myfaces.trinidad.component.UIXHierarchy</mfp:component-superclass>
<mfp:renderer-type>org.apache.myfaces.trinidad.Tree</mfp:renderer-type>
<mfp:tag-class>org.apache.myfaces.trinidadinternal.taglib.UIXTreeTag</mfp:tag-class>
<mfp:naming-container>true</mfp:naming-container>
<mfp:long-description><![CDATA[<html:p>
Apache Trinidad tree components are used to display hierarchical data.
For example,
if we have a personnel organization chart depicting all the direct
reports under
each employee, we could use a tree component to display this
chart. While each element (employee) in the hierarchy may have any
number of
child elements, each element can only have one parent element.
</html:p>
<section name="The Tree Model">
<html:P>
The Apache Trinidad tree components use a model to access the data in the
underlying hierarchy. The specific model class is
<html:code>org.apache.myfaces.trinidad.model.TreeModel</html:code>.
You may find the
<html:code>org.apache.myfaces.trinidad.model.ChildPropertyTreeModel</html:code> class
useful when constructing a <html:code>TreeModel</html:code>.
</html:P>
</section>
<section name="Data">
<html:P>
The tree components use a stamping strategy similar to the Trinidad Table
component. Child components are used to display the
data for each element in the tree. Each child component is not recreated
per element; instead, each child is repeatedly
rendered (stamped) once per element. Because of this stamping
behavior, only certain types of components are supported as
children. Supported components include all
components with no behavior and most components that implement the
EditableValueHolder or ActionSource interfaces.
</html:P>
<html:P>
Each time a child component is stamped, the data for the current
element is copied into an EL reachable property. The
name of this property is defined by the <html:code>var</html:code>
property on
the tree component. Once the tree has completed rendering, this property is
removed (or reverted back to its previous value).
</html:P>
</section>
<section name="Events">
<html:P>
When the user expands or collapses a subtree the tree
generates a <html:code>DisclosureEvent</html:code>. This event has an
<html:code>isExpanded</html:code> method that returns whether the user wants
to expand or collapse the subtree of a particular element. That
particular element is made current on the Tree before the event is
delivered.
</html:P>
</section>
<section name="Expand/Collapse State">
<html:P>
The Trinidad tree components use an instance of the
<html:code>org.apache.myfaces.trinidad.model.RowKeySet</html:code>
class to keep track
of which elements are expanded. This instance is stored
as the "expandedRowKeys" attribute on the component. You may use this
instance to programmatically control the expand/collapse state of an
element in the hierarchy.
</html:P>
</section>]]>
</mfp:long-description>
<mfp:author>Arjuna Wijeyekoon</mfp:author>
<mfp:tag-class-modifier>abstract</mfp:tag-class-modifier>
<mfp:event>
<mfp:description>Event delivered when user clicks to focus on (or zoom into) a particular element's subtree of children.
The TreeTable responds to this event by modifying the "focusRowKey" property appropriately.
Subsequently, any registered FocusListener instances are called.
</mfp:description>
<mfp:event-type>org.apache.myfaces.trinidad.Focus</mfp:event-type>
<mfp:event-delivery-phase>Apply Request Values</mfp:event-delivery-phase>
<mfp:event-delivery-phase>Invoke Application</mfp:event-delivery-phase>
</mfp:event>
</component-extension>
</component>
</faces-config>