svn commit: r429972 [3/4] - in /incubator/adffaces/trunk/trinidad: src/ src/site/ src/site/xdoc/ src/site/xdoc/devguide/ trinidad-api/src/site/ trinidad-demo/src/site/ trinidad-impl/src/site/

[aw...@apache.org]

Added: incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/fileUpload.xml
URL: http://svn.apache.org/viewvc/incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/fileUpload.xml?rev=429972&view=auto
==============================================================================
--- incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/fileUpload.xml (added)
+++ incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/fileUpload.xml Tue Aug  8 22:46:09 2006
@@ -0,0 +1,256 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<document>
+  <properties>
+    <title>Processing file uploads</title>
+  </properties>
+  <body>
+    <section name="Processing file uploads">
+      <p>
+        <ul>
+          <li>
+            <a href="#Overview">Overview</a>
+          </li>
+          <li>
+            <a href="#Setup">Setup</a>
+          </li>
+          <li>
+            <a href="#inputFile">inputFile</a>
+          </li>
+          <li>
+            <a href="#updateMode">Update Mode</a>
+          </li>
+          <li>
+            <a href="#Configuration">Configuration</a>
+          </li>
+        </ul>
+      </p>
+    </section>
+    <section name="Overview">
+
+      <p>
+The JavaServer Faces (JSF) 1.1 specification provides no direct support for
+file uploads.  (And, unfortunately, nothing else in the J2EE
+technology stack does either.)  Apache Trinidad provides integrated support
+for processing file uploads in a manner natural to JSF applications,
+by providing  a component that delivers standard
+<code>ValueChangeEvents</code> as files are uploaded, and managing
+processing of the uploaded content transparently.
+      </p>
+    </section>
+    <section name="Setup">
+      <p>
+File upload processing requires the installation of the Apache Trinidad Filter.
+This filter is required for all Apache Trinidad applications.  One of its features
+is handling file uploads.  To install the filter,
+first add the following entry to your <code>WEB-INF/web.xml</code> file:
+      </p>
+<source>
+  &lt;filter&gt;
+    &lt;filter-name&gt;trinidad&lt;/filter-name&gt;
+    &lt;filter-class&gt;org.apache.myfaces.trinidad.webapp.TrinidadFilter&lt;/filter-class&gt;
+  &lt;/filter&gt;
+</source>
+      <p>
+Second, map that filter to process all <code>FacesServlet</code>
+requests.  For example, if you've named the <code>FacesServlet</code> "faces":
+      </p>
+<source>
+  &lt;servlet&gt;
+    &lt;servlet-name&gt;faces&lt;/servlet-name&gt;
+    &lt;servlet-class&gt;javax.faces.webapp.FacesServlet&lt;/servlet-class&gt;
+  &lt;/servlet&gt;
+</source>
+      <p>...then use the following filter-mapping:</p>
+<source>
+  &lt;filter-mapping&gt;
+    &lt;filter-name&gt;trinidad&lt;/filter-name&gt;
+    &lt;servlet-name&gt;faces&lt;/servlet-name&gt;
+  &lt;/filter-mapping&gt;
+</source>
+    </section>
+    <section name="inputFile">
+      <p>
+To support uploading a file on your page, use the <a
+href="../trinidad-api/tags/core/inputFile.html"><code>&lt;tr:inputFile&gt;
+component</code></a>.  Like all other input components, <code>&lt;tr:inputFile&gt;</code> sends
+<code>ValueChangeEvents</code>.  And like all Apache Trinidad input components,
+it has built-in support for accessibility, labels, and messages.
+<source>
+       &lt;tr:inputFile label="Upload:"
+                     valueChangeListener="#{backingBean.fileUploaded}"/&gt;
+                          
+</source>
+      </p>
+      <p>
+<code>&lt;tr:inputFile&gt;</code> can be placed in either an
+<code>&lt;h:form&gt;</code> tag or an <code>&lt;tr:form&gt;</code>
+tag, but in either case you have to set it to support file
+upload.  For the JSF Basic HTML form, that involves setting
+the "enctype" to the correct magic value;  for the Apache Trinidad
+form, just set "usesUpload" to true:
+
+<source>
+     &lt;tr:form usesUpload="true"&gt;
+       &lt;tr:inputFile label="Upload:"
+                     valueChangeListener="#{backingBean.fileUploaded}"/&gt;
+     &lt;/tr:form&gt;
+     &lt;!-- or --&gt;
+     &lt;h:form enctype="multipart/form-data"&gt;
+       &lt;tr:inputFile label="Upload:"
+                     valueChangeListener="#{backingBean.fileUploaded}"/&gt;
+     &lt;/h:form&gt;
+</source>
+      </p>
+      <p>
+
+The <code>"value"</code> of an inputFile component is an instance of
+the <a
+href="../trinidad-api/apidocs/org/apache/myfaces/trinidad/model/UploadedFile.html"><code>org.apache.myfaces.trinidad.model.UploadedFile</code></a>
+interface.  This API lets you get at the actual byte stream of the file, as
+well as the file's name, its MIME type, and its size.  The
+<code>UploadedFile</code> might be stored as a file in the filesystem,
+but might also be stored in memory;  this API hides that difference.
+The filter ensures that the <code>UploadedFile</code> content
+is cleaned up after the request is complete.  Because of this,
+you cannot usefully cache <code>UploadedFile</code> objects across requests.
+If you need to keep the file, you must copy it into persistent storage
+before the request finishes.
+      </p>
+      <subsection name="Example">
+        <p>
+For an example of processing a file upload, instead of actually storing
+it anywhere, we'll just add a message telling the user that the file
+was successfully uploaded.  The page content is simple:
+<source>
+     &lt;tr:form usesUpload="true"&gt;
+       &lt;tr:inputFile label="Upload:"
+                     valueChangeListener="#{backingBean.fileUploaded}"/&gt;
+       &lt;tr:commandButton text="Begin"/&gt;
+     &lt;/tr:form&gt;
+</source>
+        </p>
+        <p>
+Now, in our backing bean, we'll handle the <code>ValueChangeEvent</code>:
+<source>
+import javax.faces.application.FacesMessage;
+import javax.faces.context.FacesContext;
+import javax.faces.event.ValueChangeEvent;
+import org.apache.myfaces.trinidad.model.UploadedFile;
+
+public class ABackingBean
+{
+  ...
+  public void fileUploaded(ValueChangeEvent event)
+  {
+    UploadedFile file = (UploadedFile) event.getNewValue();
+    if (file != null)
+    {
+      FacesContext context = FacesContext.getCurrentInstance();
+      FacesMessage message = new FacesMessage(
+         "Successfully uploaded file " + file.getFilename() +
+         " (" + file.getLength() + " bytes)");
+      context.addMessage(event.getComponent().getClientId(context), message);
+      // Here's where we could call file.getInputStream()
+    }
+  }
+}
+</source>
+        </p>
+        <p>
+Here, we've chosen to use <code>ValueChangeEvents</code>.  You
+could also bind the value of the inputFile directly to a managed
+bean:
+<source>
+     &lt;tr:form usesUpload="true"&gt;
+       &lt;tr:inputFile label="Upload:" value="#{managedBean.file}"/&gt;
+       &lt;tr:commandButton text="Begin" action="#{managedBean.doUpload}"/&gt;
+     &lt;/tr:form&gt;
+</source>
+<source>
+import org.apache.myfaces.trinidad.model.UploadedFile;
+
+public class AManagedBean
+{
+  public UploadedFile getFile()
+  {
+    return _file;
+  }
+
+  public void setFile(UploadedFile file)
+  {
+    _file = file;
+  }
+
+  public String doUpload()
+  {
+    UploadedFile file = getFile();
+    // ... and process it in some way
+  }
+
+
+  private UploadedFile _file;
+}
+</source>
+        </p>
+      </subsection>
+    </section>
+    <section name="Configuration">
+      <p>
+Because Apache Trinidad will temporarily store incoming files (either on
+disk or in memory), by default it limits the size of acceptable
+incoming requests to avoid denial-of-service attacks that might
+attempt to fill a hard drive or flood memory with uploaded files.  By
+default, only the first 100 kilobytes in any one request will be
+stored in memory.  Once that has been filled, disk space will be used.
+Again, by default, that is limited to 2,000 kilobytes of disk storage
+for any one request for all files combined.  Once these limits are
+exceeded, the filter will throw an <code>EOFException</code>.  Files
+are, by default, stored in the temporary directory used by
+<code>java.io.File.createTempFile()</code>, which is usually defined by the
+system property <code>java.io.tmpdir</code>.  Obviously, this will be
+insufficient for some applications, so you can configure these values 
+using three servlet context initialization parameters:
+<source>
+  &lt;context-param&gt;
+    &lt;!-- Maximum memory per request (in bytes) --&gt;
+    &lt;param-name&gt;org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY&lt;/param-name&gt;
+    &lt;!-- Use 500K --&gt;
+    &lt;param-value&gt;512000&lt;/param-value&gt;
+  &lt;/context-param&gt;
+  &lt;context-param&gt;
+    &lt;!-- Maximum disk space per request (in bytes) --&gt;
+    &lt;param-name&gt;org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE&lt;/param-name&gt;
+    &lt;!-- Use 5,000K --&gt;
+    &lt;param-value&gt;5120000&lt;/param-value&gt;
+  &lt;/context-param&gt;
+  &lt;context-param&gt;
+    &lt;!-- directory to store temporary files --&gt;
+    &lt;param-name&gt;org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR&lt;/param-name&gt;
+    &lt;!-- Use a TrinidadUploads subdirectory of /tmp --&gt;
+    &lt;param-value&gt;/tmp/TrinidadUploads/&lt;/param-value&gt;
+  &lt;/context-param&gt;
+
+  &lt;!-- This filter is always required;  one of its functions is 
+          file upload. --&gt;
+  &lt;filter&gt;
+    &lt;filter-name&gt;trinidad&lt;/filter-name&gt;
+    &lt;filter-class&gt;org.apache.myfaces.trinidad.webapp.TrinidadFilter&lt;/filter-class&gt;
+  &lt;/filter&gt;
+</source>
+      </p>
+      <p>
+Developers can also customize file upload more comprehensively
+by replacing the entire
+<code>org.apache.myfaces.trinidad.webapp.UploadedFileProcessor</code>
+with the <code>&lt;uploaded-file-processor&gt;</code> element
+in <code>trinidad-config.xml</code>.  Please see the
+<a href="configuration.html">Configuration</a> chapter for
+more information on that element.  Replacing the
+<code>UploadedFileProcessor</code> makes the init-params listed
+above irrelevant;  they are only processed by the default
+<code>UploadedFileProcessor</code>.
+      </p>
+    </section>
+  </body>
+</document>
+

Added: incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/index.xml
URL: http://svn.apache.org/viewvc/incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/index.xml?rev=429972&view=auto
==============================================================================
--- incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/index.xml (added)
+++ incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/index.xml Tue Aug  8 22:46:09 2006
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<document>
+  <properties>
+    <title>Developer Guide Index</title>
+  </properties>
+
+  <body>
+    <section name="Development Guidelines for Oracle ADF Faces Applications">
+      <p>
+        <ul>        
+            <li><a href="configuration.html">Configuring ADF Faces</a></li>
+            <li><a href="communicatingBetweenPages.html">Communicating Between Pages: pageFlowScope</a></li>
+            <li><a href="dialogs.html">The ADF Faces Dialog Framework</a></li>
+            <li><a href="fileUpload.html">File Upload</a></li>            
+            <li><a href="table.html">Using ADF Faces Tables</a></li>     
+            <li><a href="tree.html">Using ADF Faces Trees</a></li>       
+            <li><a href="navigation.html">Navigation</a></li>      
+            <!--li><a href="clientValidation.html">Client-side Converters and Validators</a></li-->     
+        </ul>
+      </p>
+      </section>
+  </body>
+</document>

Added: incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/navigation.xml
URL: http://svn.apache.org/viewvc/incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/navigation.xml?rev=429972&view=auto
==============================================================================
--- incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/navigation.xml (added)
+++ incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/navigation.xml Tue Aug  8 22:46:09 2006
@@ -0,0 +1,711 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<document>
+  <properties>
+    <title>Navigation in Apache Trinidad</title>
+  </properties>
+
+  <body>
+    <section name="Navigation in Apache Trinidad">
+      <p>
+        <ul>
+          <li><a href="#Introduction">Introduction</a></li>
+          <li><a href="#Navigation Components and Children">Navigation Components and Children</a></li>
+          <li><a href="#The Navigation Model">The Navigation Model</a></li>
+          <li><a href="#Navigation Components and the NavigationModel">Navigation Components and the NavigationModel</a></li>
+          <li><a href="#Page">Page</a></li>
+        </ul>
+      </p>
+    </section>
+
+  <section name="Introduction">
+    <p>Pages are not written in isolation, an application consists of many pages. Often these pages are organized in a tree, and the user drills down into the tree to access more specific information. The figure below represents a tree of pages. 
+
+  <a name="fig1"></a>
+<source>
+Depth 0:                            <b>a1</b>                         a2        a3    a4
+                            /                \                /  \
+Depth 1:                a1b1                  <b>a1b2</b>         a2b1  a2b2
+                     /        \             /      \
+Depth 2:          a1b1c1    a1b1c2    <b>a1b2c1</b>  a1b2c2
+                 /      \
+Depth 3:    a1b1c1d1  a1b1c2d1
+</source>
+<div align="center">
+<strong >Figure 1</strong>
+</div>
+<br></br>
+Here's an example at the kind of navigation rules you might find in faces-config for the group of pages above.
+
+<source>
+&lt;navigation-rule&gt;
+    &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_root&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+    &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a1&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a1.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+    &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a2&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a2.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+    &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a3&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a3.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+    &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a4&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a4.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+     &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a1b1&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a1b1.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+     &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a1b2&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a1b2.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+     &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a2b1&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a2b1.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+     &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a2b2&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a2b2.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+     &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a1b1c1&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a1b1c1.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+     &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a1b1c2&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a1b1c2.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+     &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a1b2c1&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a1b2c1.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+     &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a1b2c2&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a1b2c2.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+     &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a1b1c1d1&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a1b1c1d1.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+     &lt;navigation-case&gt;
+      &lt;from-outcome&gt;guide.navigationModel_a1b1c2d1&lt;/from-outcome&gt;
+      &lt;to-view-id&gt;/components/navmodel/page_a1b1c2d1.jspx&lt;/to-view-id&gt;
+      &lt;redirect/&gt;
+    &lt;/navigation-case&gt;
+  &lt;/navigation-rule&gt;
+</source>
+<br></br>
+<p>
+So what components should be used in Apache Trinidad to achieve the layout above?  There are multiple options: use panelPage and navigation components that take a series of commandNavigationItem children, use panelPage and navigation components that use a navigation model and a single commandNavigationItem child in the nodeStamp facet, or use the page component with a navigation model and a single commandNavigationItem child in the nodeStamp facet.  These techniques are discussed in this chapter.
+</p>
+</p>
+</section>
+<section name="Navigation Components and Children">
+<p>
+The panelPage component organizes the content of an entire page.  The panelPage has multiple facets which are used to render the navigation areas of the page (among other navigation-related areas).  The navigation components then go inside these facets.  The "intuitive" way to build up the navigation components is to just add children to the navigation components.   The example that follows should produce the same output as seen in <a href="#fig2">figure 2</a>.
+
+<source>
+&lt;?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?&gt;
+&lt;jsp:root version="1.2"
+  xmlns:jsp="http://java.sun.com/JSP/Page"
+  xmlns:f="http://java.sun.com/jsf/core"
+  xmlns:tr="http://myfaces.apache.org/"&gt;
+  &lt;jsp:directive.page contentType="text/html;charset=utf-8"/&gt;
+  &lt;f:view&gt;
+    &lt;tr:document title="NavigationModel Demo" maximized="true"&gt;
+      &lt;tr:form&gt;
+        &lt;tr:panelPage&gt;
+          &lt;f:facet name="branding"&gt;
+            &lt;tr:panelGroup layout="horizontal"&gt;
+              &lt;tr:objectIcon name="logo"/&gt;
+              &lt;tr:outputText value="NavigationModel Demo"/&gt;
+            &lt;/tr:panelGroup&gt;
+          &lt;/f:facet&gt;
+          &lt;f:facet name="navigationGlobal"&gt;
+            &lt;tr:navigationLevel&gt;
+              &lt;tr:commandNavigationItem text="a1" action="guide.navigationModel_a1"
+                selected="true"/&gt;
+              &lt;tr:commandNavigationItem text="a2" action="guide.navigationModel_a2"/&gt;
+              &lt;tr:commandNavigationItem text="a3" action="guide.navigationModel_a3"/&gt;
+              &lt;tr:commandNavigationItem text="a4" action="guide.navigationModel_a4"/&gt;
+            &lt;/tr:navigationLevel&gt;
+          &lt;/f:facet&gt;
+          &lt;f:facet name="navigation1"&gt;
+            &lt;tr:navigationLevel&gt;
+              &lt;tr:commandNavigationItem text="a1b1" action="guide.navigationModel_a1b1"/&gt;
+              &lt;tr:commandNavigationItem text="a1b2" action="guide.navigationModel_a1b2"
+                selected="true"/&gt;
+            &lt;/tr:navigationLevel&gt;
+          &lt;/f:facet&gt;
+          &lt;f:facet name="navigation2"&gt;
+            &lt;tr:navigationLevel&gt;
+              &lt;tr:commandNavigationItem text="a1b2c1" action="guide.navigationModel_a1b2c1"
+                selected="true"/&gt;
+              &lt;tr:commandNavigationItem text="a1b2c2" action="guide.navigationModel_a1b2c2"/&gt;
+            &lt;/tr:navigationLevel&gt;
+          &lt;/f:facet&gt;
+          &lt;f:facet name="location"&gt;
+            &lt;tr:navigationPath&gt;
+              &lt;tr:commandNavigationItem text="a1" action="guide.navigationModel_a1"/&gt;
+              &lt;tr:commandNavigationItem text="a1b2" action="guide.navigationModel_a1b2"/&gt;
+              &lt;tr:commandNavigationItem text="a1b2c1" action="guide.navigationModel_a1b2c1"/&gt;
+            &lt;/tr:navigationPath&gt;
+          &lt;/f:facet&gt;
+        &lt;/tr:panelPage&gt;
+      &lt;/tr:form&gt;
+    &lt;/tr:document&gt;
+  &lt;/f:view&gt;
+&lt;/jsp:root&gt;
+</source>
+
+  </p>
+</section>
+<section name="Navigation Model">
+<p>
+  <b>NOTE</b>: Work on modeling navigation continues and it is very possible that there will be changes in a future release. 
+   </p>
+   
+  <p>So what is wrong with the panelPage approach described above? It's simple and easy to understand and it works. The problem is that it's not easy to get things right. For example the page author must take care to show the correct nodes as "selected". It's also not easily maintained. What if  a page is moved from one place to another in the tree (see <a href="#fig1">figure 1</a>)?  
+  </p>
+  
+  <p>
+  What is needed is a model object that knows the application hierarchy and also knows how to say what is the current "focus path" in that hierarchy. The NavigationModel class was created for this purpose. NavigationModel extends TreeModel, so if you are not familiar with the model for the tree it is important that you first read the <a href="tree.html">tree</a> chapter.
+  </p>
+
+  <p>
+  The navigation model knows how to go from the current viewId to the focus path. For example if I am on page a1b2c1, a call to getFocusPath() will return the focus path of a1, a1b2, and a1b2c1. 
+   </p>
+ 
+  <p>Notice that the navigationModel has no special knowledge of page navigation and places no requirements on the nodes that go into the tree. The components that take a navigationModel use a commandNavigationItem component to stamp out the data in the tree. The default actionListener mechanism is used for page navigation.
+  </p>
+ 
+  <p>
+  The following example shows how a navigation model can be created in faces-config. The DemoNavigationItem class is a bean. The TreeModelAdapter class creates a ChildPropertyTreeModel instance, and the NavigationModelAdapter creates a ViewIdPropertyNavigationModel instance which can be retrieved by calling NavigationModelAdapter.getModel(). Please see the javadoc for more information on ChildPropertyTreeModel and ViewIdPropertyNavigationModel.
+  </p>
+
+  <p><a href="#endfacesconfig">Skip to end of faces-config fragment.</a></p>
+<source>
+   &lt;!-- create the navigationModel nodes --&gt;
+
+   &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a1b1c1d1&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a1b1c1d1&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a1b1c1d1.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a1b1c1d1&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+  &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a1b1c2d1&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a1b1c2d1&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a1b1c2d1.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a1b1c2d1&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+   &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a1b1c1&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;children&lt;/property-name&gt;
+      &lt;list-entries&gt;
+        &lt;value-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/value-class&gt;
+        &lt;value&gt;#{navItem_a1b1c1d1}&lt;/value&gt;
+      &lt;/list-entries&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a1b1c1&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a1b1c1.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a1b1c1&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+   &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a1b1c2&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;children&lt;/property-name&gt;
+      &lt;list-entries&gt;
+        &lt;value-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/value-class&gt;
+        &lt;value&gt;#{navItem_a1b1c2d1}&lt;/value&gt;
+      &lt;/list-entries&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a1b1c2&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a1b1c2.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a1b1c2&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+   &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a1b2c1&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a1b2c1&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a1b2c1.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a1b2c1&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+   &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a1b2c2&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a1b2c2&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a1b2c2.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a1b2c2&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+   &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a1b1&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;children&lt;/property-name&gt;
+      &lt;list-entries&gt;
+        &lt;value-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/value-class&gt;
+        &lt;value&gt;#{navItem_a1b1c1}&lt;/value&gt;
+        &lt;value&gt;#{navItem_a1b1c2}&lt;/value&gt;
+      &lt;/list-entries&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a1b1&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a1b1.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a1b1&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+   &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a1b2&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;children&lt;/property-name&gt;
+      &lt;list-entries&gt;
+        &lt;value-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/value-class&gt;
+        &lt;value&gt;#{navItem_a1b2c1}&lt;/value&gt;
+        &lt;value&gt;#{navItem_a1b2c2}&lt;/value&gt;
+      &lt;/list-entries&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a1b2&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a1b2.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a1b2&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+   &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a2b1&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a2b1&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a2b1.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a2b1&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+
+   &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a2b2&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a2b2&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a2b2.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a2b2&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+  &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a1&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;children&lt;/property-name&gt;
+      &lt;list-entries&gt;
+        &lt;value-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/value-class&gt;
+        &lt;value&gt;#{navItem_a1b1}&lt;/value&gt;
+        &lt;value&gt;#{navItem_a1b2}&lt;/value&gt;
+      &lt;/list-entries&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a1&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;!-- For a one-and-only-one selected navigation item behavior, remove the
+         "viewId" declaration and modify the "outcome" declaration so that it
+         takes the user to a deeper page, e.g. guide.navigationModel_a1b2.
+         Doing this eliminates the page_a1.jspx, so it could be deleted too.
+         This would also need to be done for all of the other navigation item
+         definitions (i.e. not just "navItem_a1"). --&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a1.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a1&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+  &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a2&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;children&lt;/property-name&gt;
+      &lt;list-entries&gt;
+        &lt;value-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/value-class&gt;
+        &lt;value&gt;#{navItem_a2b1}&lt;/value&gt;
+        &lt;value&gt;#{navItem_a2b2}&lt;/value&gt;
+      &lt;/list-entries&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a2&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a2.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a2&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+  &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a3&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a3&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a3.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a3&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+ &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navItem_a4&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;label&lt;/property-name&gt;
+      &lt;value&gt;a4&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewId&lt;/property-name&gt;
+      &lt;value&gt;/components/navmodel/page_a4.jspx&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;outcome&lt;/property-name&gt;
+      &lt;value&gt;guide.navigationModel_a4&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+  &lt;!-- create the treemodel --&gt;
+  
+ &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navTreeList&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;
+       java.util.ArrayList
+    &lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;
+       none
+    &lt;/managed-bean-scope&gt;
+     &lt;list-entries&gt;
+        &lt;value-class&gt;org.apache.myfaces.trinidaddemo.nav.DemoNavigationItem&lt;/value-class&gt;
+        &lt;value&gt;#{navItem_a1}&lt;/value&gt;
+        &lt;value&gt;#{navItem_a2}&lt;/value&gt;
+        &lt;value&gt;#{navItem_a3}&lt;/value&gt;
+        &lt;value&gt;#{navItem_a4}&lt;/value&gt;
+      &lt;/list-entries&gt;
+  &lt;/managed-bean&gt;
+  
+  &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navTreeModel&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidad.model.ChildPropertyTreeModel&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;childProperty&lt;/property-name&gt;
+      &lt;value&gt;children&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;wrappedData&lt;/property-name&gt;
+      &lt;value&gt;#{navTreeList}&lt;/value&gt;
+    &lt;/managed-property&gt;
+  &lt;/managed-bean&gt;
+
+  &lt;!-- create the navigationModel --&gt;
+  
+  &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;viewIdNavigationModel&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidad.model.ViewIdPropertyNavigationModel&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;none&lt;/managed-bean-scope&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;viewIdProperty&lt;/property-name&gt;
+      &lt;value&gt;viewId&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;wrappedData&lt;/property-name&gt;
+      &lt;value&gt;#{navTreeModel}&lt;/value&gt;
+    &lt;/managed-property&gt;    
+  &lt;/managed-bean&gt;  
+  
+  &lt;managed-bean&gt;
+    &lt;managed-bean-name&gt;navigationModel&lt;/managed-bean-name&gt;
+    &lt;managed-bean-class&gt;org.apache.myfaces.trinidaddemo.nav.NavigationModelAdapter&lt;/managed-bean-class&gt;
+    &lt;managed-bean-scope&gt;session&lt;/managed-bean-scope&gt;   
+    &lt;managed-property&gt;
+      &lt;property-name&gt;model&lt;/property-name&gt;
+      &lt;value&gt;#{viewIdNavigationModel}&lt;/value&gt;
+    &lt;/managed-property&gt;
+    &lt;managed-property&gt;
+      &lt;property-name&gt;aliasList&lt;/property-name&gt;
+      &lt;list-entries&gt;
+        &lt;value-class&gt;java.lang.String&lt;/value-class&gt;
+        &lt;value&gt;/components/navmodel/page_p1.jspx&lt;/value&gt;
+        &lt;value&gt;#{navItem_a2b1.viewId}&lt;/value&gt;
+        &lt;value&gt;/components/navmodel/page_p2.jspx&lt;/value&gt;
+        &lt;value&gt;#{navItem_a2b1.viewId}&lt;/value&gt;
+        &lt;value&gt;/components/navmodel/page_p3.jspx&lt;/value&gt;
+        &lt;value&gt;#{navItem_a2b1.viewId}&lt;/value&gt;
+        &lt;value&gt;/components/navmodel/page_p4.jspx&lt;/value&gt;
+        &lt;value&gt;#{navItem_a2b1.viewId}&lt;/value&gt;
+      &lt;/list-entries&gt;
+    &lt;/managed-property&gt;
+
+  &lt;/managed-bean&gt;
+</source>
+  <a name="endfacesconfig"></a>
+  </section>
+  <section name="Navigation Components and the NavigationModel">
+  <p>
+  <b>Note</b>: In a subsequent release the use of the level and startLevel attributes will almost certainly be replaced with an el expression in the 'value' attribute.
+  </p>
+  <p>
+  As in the first example, we are still using the panelPage and navigation components, but in the example that follows we are binding the navigation components to a navigationModel.  Notice it is the commandNavigationItem component stamp which renders the data in the node.  The example that follows should produce the same output as seen in <a href="#fig2">figure 2</a>.
+<source>
+&lt;?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?&gt;
+&lt;jsp:root version="1.2"
+  xmlns:jsp="http://java.sun.com/JSP/Page"
+  xmlns:f="http://java.sun.com/jsf/core"
+  xmlns:tr="http://myfaces.apache.org/trinidad"&gt;
+  &lt;jsp:directive.page contentType="text/html;charset=utf-8"/&gt;
+  &lt;f:view&gt;
+    &lt;tr:document title="NavigationModel Demo" maximized="true"&gt;
+      &lt;tr:form&gt;
+        &lt;tr:panelPage&gt;
+          &lt;f:facet name="branding"&gt;
+            &lt;tr:panelGroup layout="horizontal"&gt;
+              &lt;tr:objectIcon name="logo"/&gt;
+              &lt;tr:outputText value="NavigationModel Demo"/&gt;
+            &lt;/tr:panelGroup&gt;
+          &lt;/f:facet&gt;
+          &lt;f:facet name="navigationGlobal"&gt;
+            &lt;tr:navigationLevel var="foo" value="#{navigationModel.model}"&gt;
+              &lt;f:facet name="nodeStamp"&gt;
+                &lt;tr:commandNavigationItem
+                  text="#{foo.label}"
+                  action="#{foo.getOutcome}"/&gt;
+              &lt;/f:facet&gt;
+            &lt;/tr:navigationLevel&gt;
+          &lt;/f:facet&gt;
+          &lt;f:facet name="navigation1"&gt;
+            &lt;tr:navigationLevel var="foo" value="#{navigationModel.model}" level="1"&gt;
+              &lt;f:facet name="nodeStamp"&gt;
+                &lt;tr:commandNavigationItem
+                  text="#{foo.label}"
+                  action="#{foo.getOutcome}"/&gt;
+              &lt;/f:facet&gt;
+            &lt;/tr:navigationLevel&gt;
+          &lt;/f:facet&gt;
+          &lt;f:facet name="navigation2"&gt;
+            &lt;tr:navigationLevel var="foo" value="#{navigationModel.model}" level="2"&gt;
+              &lt;f:facet name="nodeStamp"&gt;
+                &lt;tr:commandNavigationItem
+                  text="#{foo.label}"
+                  action="#{foo.getOutcome}"/&gt;
+              &lt;/f:facet&gt;
+            &lt;/tr:navigationLevel&gt;
+          &lt;/f:facet&gt; 
+          &lt;f:facet name="navigation3"&gt;
+            &lt;tr:navigationLevel var="foo" value="#{navigationModel.model}" level="3"&gt;
+              &lt;f:facet name="nodeStamp"&gt;
+                &lt;tr:commandNavigationItem
+                  text="#{foo.label}"
+                  action="#{foo.getOutcome}"/&gt;
+              &lt;/f:facet&gt;
+            &lt;/tr:navigationLevel&gt;
+          &lt;/f:facet&gt;
+          &lt;f:facet name="location"&gt;
+            &lt;tr:navigationPath var="foo" value="#{navigationModel.model}"&gt;
+              &lt;f:facet name="nodeStamp"&gt;
+                &lt;tr:commandNavigationItem
+                  text="#{foo.label}"
+                  action="#{foo.getOutcome}"/&gt;
+              &lt;/f:facet&gt;
+            &lt;/tr:navigationPath&gt;
+          &lt;/f:facet&gt;
+        &lt;/tr:panelPage&gt;
+      &lt;/tr:form&gt;
+    &lt;/tr:document&gt;
+  &lt;/f:view&gt;
+&lt;/jsp:root&gt;
+</source>
+  </p>
+  </section>
+  <section name="Page">
+  <p>
+  <p>
+  Using the navigationModel with navigation components has made some things easier, but it hasn't solved all our problems.  For example, if we were looking at page a1b1c1 instead of a1b2c1 (see <a href="#fig1">figure 1</a>), we should use a navigationTree in the navigation3 facet rather than a navigationLevel.  If we were looking at page a1, we don't need anything at all in the navigation3 facet. 
+  </p>
+  <p>
+  More importantly, what if we want to make a dramatic change the way navigation looks.  Maybe we want the page component to render cascading popups, meaning list of items that drop down off of an item when you click it.  Using the panelPage and navigation components ties you to specific renderers for the navigation components. 
+  </p>
+  The page component is more flexible still, binding to a navigationModel and stamping out the navigation items.  The advantages of using a page componenent are that the renderer could render the navigation items in many different ways, for example it could render the cascading popups described above.  Also, the page author doesn't need to know anything about where this page is in the hierarchy of pages.  To render a1b1c1 or a1 we would use the exact same syntax as below.
+  </p>
+  <p>
+The example that follows should produce the same output as seen in <a href="#fig2">figure 2</a>.
+<source>
+&lt;?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?&gt;
+&lt;jsp:root version="1.2"
+  xmlns:jsp="http://java.sun.com/JSP/Page"
+  xmlns:f="http://java.sun.com/jsf/core"
+  xmlns:tr="http://myfaces.apache.org/trinidad"&gt;
+  &lt;jsp:directive.page contentType="text/html;charset=utf-8"/&gt;
+  &lt;f:view&gt;
+    &lt;tr:document title="NavigationModel Demo" maximized="true"&gt;
+      &lt;tr:form&gt;
+        &lt;tr:page&gt;
+          &lt;f:facet name="branding"&gt;
+            &lt;tr:panelGroup layout="horizontal"&gt;
+              &lt;tr:objectIcon name="logo"/&gt;
+              &lt;tr:outputText value="NavigationModel Demo"/&gt;
+            &lt;/tr:panelGroup&gt;
+          &lt;/f:facet&gt;
+          &lt;f:facet name="nodeStamp"&gt;
+            &lt;tr:commandNavigationItem
+              text="#{foo.label}"
+              action="#{foo.getOutcome}"/&gt;
+          &lt;/f:facet&gt;
+        &lt;/tr:page&gt;
+      &lt;/tr:form&gt;
+    &lt;/tr:document&gt;
+  &lt;/f:view&gt;
+&lt;/jsp:root&gt;
+</source>
+  </p>
+  </section>
+  </body>
+</document>

Added: incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/table.xml
URL: http://svn.apache.org/viewvc/incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/table.xml?rev=429972&view=auto
==============================================================================
--- incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/table.xml (added)
+++ incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/table.xml Tue Aug  8 22:46:09 2006
@@ -0,0 +1,504 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<document>
+  <properties>
+    <title>Using the Apache Trinidad Component</title>
+  </properties>
+
+  <body>
+    <section name="Using the Apache Trinidad Component">
+      <p>
+        <ul>
+          <li><a href="#Introduction">Introduction</a></li>
+          <li><a href="#The Table Model">The Table Model</a></li>
+          <li><a href="#Columns">Columns</a>
+            <ul>
+              <li><a href="#Headers">Headers</a></li>
+              <li><a href="#Data">Data</a></li>
+              <li><a href="#Formatting">Formatting</a></li>
+            </ul>
+          </li>
+          <li><a href="#Selection">Selection</a></li>
+          <li><a href="#Sorting">Sorting</a>
+            <ul>
+              <li><a href="#SortEvent">SortEvent</a></li>
+            </ul>
+          </li>
+          <li><a href="#Grid Lines and Banding">Grid Lines and Banding</a></li>
+        </ul>
+      </p>
+    </section>
+
+
+    <section name="Introduction">
+      <P>
+        The Apache Trinidad component is used to display a list of structured data.
+        For example, if we have a data structure called Person that has two
+        properties - firstname and lastname, we could use a Table with two
+        columns - one for firstname, and the other for lastname - to display
+        a list of Person objects.
+      </P>
+      <P>
+        The Table component is similar to the standard <code>UIData</code>
+        component in JSF, but includes a number of extra features,  including
+        support for identifying rows by key (instead of by index),
+        built-in support for paging through large models,
+        sorting the model, and selecting single or multiple items in
+        the model.
+      </P>
+    </section>
+
+    <section name="The Table Model">
+      <P>
+        The Apache Trinidad component uses a model to access the data in the underlying list.
+        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>. The Table will
+        automatically convert the instance into a CollectionModel.
+      </P>
+      <P>
+        To access a particular row in the list, first make that row current,
+        and then call the <code>getRowData()</code> method on the Table. To
+        make a row current, call the <code>setRowIndex(...)</code> method (on
+        the Table) with the appropriate index into the list. Alternatively,
+        call the <code>setRowKey(...)</code> method with the appropriate rowKey.      </P>
+      <P>
+        To obtain the total number of rows in the list, call the
+        <code>getRowCount()</code> method on the Table. In the case where the
+        model does not yet know the total number of rows that are
+        available, <code>getRowCount()</code> will return -1.
+      </P>
+      <P>
+        The Table has an <code>isRowAvailable()</code> method that returns
+        <code>true</code> if the current row ( see <code>setRowIndex(...)</code> )
+        is available. This method is especially useful when the total number
+        of rows is unknown.
+      </P>
+    </section>
+
+    <section name="Columns">
+      <P>
+        The immediate children of a Table component must all be
+        <code>&lt;tr:column&gt;</code> components. Each visible ADF Column
+        component creates a separate column in the Table.
+      </P>
+      <subsection name="Headers">
+        <P>
+          Use the "header" facet on a Column to create the column header. You
+          can also use the "headerText" attribute to set the column header.
+          The following example creates a two-column table with the column
+          headers - "Firstname" and "Lastname":
+        </P>
+        <source><![CDATA[
+<tr:table>
+  <tr:column>
+    <f:facet name="header">
+      <tr:outputText value="Firstname"/>
+    </f:facet>
+    ...
+  </tr:column>
+  <tr:column headerText="Lastname">
+    ...
+  </tr:column>
+</tr:table>]]>
+        </source>
+        <p>
+Note that both ADF Faces and JSF HTML tags can be used inside of
+the ADF table.
+        </p>
+      </subsection>
+      <subsection name="Data">
+        <P>
+          The child components of each Column display the data for each row in
+          that column. The Column does not create child components per row;
+          instead, each child is repeatedly rendered (stamped) once per
+          row. Because of this stamping behavior, some components many
+          not work inside the table.  Anything that is just pure output,
+	  with no behavior, will work without problems, as will components that
+          don't "mutate" even as they deliver events (for example,
+          command components are fine).  Components that mutate
+          their state are affected, but any that implement 
+          EditableValueHolder are supported (this includes all
+          form input controls from the JSF specification as well
+          as ADF Faces input controls), as are UIXShowDetail components.
+        </P>
+        <P>
+          As each row is stamped, the data for the current row ( see
+          <code>getRowData()</code> ) is copied into an EL reachable property.
+          The name of this property is defined by the <code>var</code>
+          property on the Table. Once the Table has completed rendering, this
+          property is removed (or reverted back to its previous value). In
+          the following example, the data for each row is placed under the EL
+          property "row". Each Column displays the data for each row by getting
+          further properties from the "row" property:
+        </P>
+        <source><![CDATA[
+<tr:table var="row" value="#{myBean.allEmployees}">
+  <tr:column>
+    <tr:outputText value="#{row.firstname}"/>
+  </tr:column>
+  <tr:column>
+    tr:outputText value="#{row.lastname}"/>
+  </tr:column>
+</tr:table>]]>
+        </source>
+      </subsection>
+      <subsection name="Formatting">
+        <p>
+          The Column component supports the following attributes related to
+          formatting:
+          <dl>
+            <dt>align</dt>
+
+            <dd>The type of alignment to use for this column. The legal
+              values are "left", "right", "start", "end" and "center".
+              Use "left" for left-justified, "right" for
+              right-justified, and "center" for center-justified columns.
+              For BiDi columns use "start" and "end".
+              Use "start" (instead of "left") to left-align columns in a
+              left-to-right locale, and right-align columns in a right-to-left
+              locale.
+              Similarly, use "end" (instead of "right") to
+              right-align columns in a
+              left-to-right locale, and left-align columns in a right-to-left
+              locale.
+            </dd>
+
+            <dt>width</dt>
+            <dd>The width of this column, e.g. "100px".
+            </dd>
+
+            <dt>noWrap</dt>
+            <dd>Controls whether long lines of text in the column data should
+            be wrapped.</dd>
+          </dl>
+        </p>
+      </subsection>
+      <subsection name="Column Groups">
+            <P>
+              <code>&lt;tr:column&gt; </code> tags can be nested to produce
+              groups of columns. The header of a column group spans across
+              all the columns it contains. The following example creates
+              a column group that has the header "Name" and contains
+              two sub columns with headers "First" and "Last":
+            </P>
+          <source><![CDATA[
+  <tr:table var="row" value="#{myBean.employees}">
+    <tr:column headerText="Name">
+      <tr:column headerText="First">
+        <tr:outputText value="#{row.firstname}"/>
+      </tr:column>
+      <tr:column headerText="Last">
+        tr:outputText value="#{row.lastname}"/>
+      </tr:column>
+    </tr:column>
+  </tr:table>]]>
+          </source>
+      </subsection>
+      <subsection name="Row Headers">
+        <P>
+          Columns can be rendered as row headers by setting the
+          "rowHeader" attribute on &lt;column&gt; to be true.
+          Row header columns must be the first columns in a table.
+        </P>
+      </subsection>
+    </section>
+
+    <section name="Range Navigation">
+      <P>
+        When the list being displayed by a Table is huge, you can enable the Table 
+        to break up the list into ranges and display a single range at a time. 
+        Range controls are provided on the Table to let the user scroll to the next range, 
+        or to go back to the previous range. If the total size of the list is known, a 
+        control to let the user jump directly to a particular part of the list is also 
+        provided on the Table. Use the Table attributes "rows" and "first" to control the 
+  range navigation feature.
+      </P>
+      <P>
+        The maximum number of rows to display in a single range is controlled
+        by the "rows" attribute, which defaults to a reasonable size (e.g.,
+        25). To disable range navigation (and display all the rows on one
+        page) set this attribute to 0. In the following example, the maximum
+        number of rows to display per range is set to 10: 
+        <source>&lt;tr:table rows="10" ...&gt;</source>
+      </P>
+      <P>
+        The current range to display is controlled by the "first"
+        attribute. This attribute is an index (based at zero) of a row in the
+        list. Each range starts with the row identified by "first", and only
+        contains as many rows as indicated by the "rows" attribute. Initially,
+        the "first" attribute defaults to zero, which displays the range 
+        with the first row at the top.
+      </P>
+      <subsection name="RangeChangeEvent">
+        <P>
+          When the user changes the range (being displayed in the Table), the
+          Table generates a <code>RangeChangeEvent</code>. This event includes the
+          index (based at zero) of the row that should now be at the top of the
+          range. The Table responds to this event by automatically changing the
+          value of the "first" attribute to this index.
+        </P>
+        <P>
+          In some cases it is necessary to know when the user changes the range
+          on the Table (e.g., when the user navigates forward it might be necessary
+          to release any cached data created for a previous range). To receive
+          notifications of when the user changes the range, a
+          <code>RangeChangeListener</code> instance should be registered with the
+          Table. This is done by calling the <code>addRangeChangeListener</code>
+          method, or by using the <code>rangeChangeListener</code> MethodBinding on the Table.
+          These listeners are called after the Table has changed the
+          "first" attribute in response to the event.
+        </P>
+      </subsection>
+    </section>
+
+    <section name="Displaying Details">
+      <P>
+        You can configure the Table to display or hide additional details of a
+        particular row in response to a user gesture. When the details feature
+        is enabled, a new column containing a toggle (per row) will render in
+        the Table. When a toggle is activated, the details for that row are
+        displayed. When a toggle is deactivated, the details for the row are
+        hidden. The user can also display or hide the details for all rows at
+        the same time (the controls for this feature are enabled by setting
+        the "allDetailsEnabled" property to true.)
+      </P>
+      <P>
+        To enable the details feature set the "detailStamp" facet on the
+        Table. Place the components that are used to show the details (of a
+        row), inside this facet. In the following example, the Person's age is
+        displayed in the details section:
+
+        <source><![CDATA[
+<tr:table var="row" value="#{myBean.allEmployees}">
+  <f:facet name="detailStamp">
+    <tr:outputText value="#{row.age}"/>
+  </f:facet>
+</tr:table>]]>
+        </source>
+      </P>
+      <P>
+        Usually, the default behavior of the Table (with respect to displaying
+        and hiding details) is sufficient. In some cases, however, it might be
+        desirable to programmatically display or hide the details for a
+        particular row. This can be done via the <code>RowKeySet</code> object
+        obtained from the Table by calling the
+        <code>getDisclosureState()</code> method. First, make the relevant row
+        current by calling <code>setRowIndex(...)</code> or
+        <code>setRowKey(...)</code> on the Table, and then call
+        <code>add()</code> or <code>remove()</code> on the
+        <code>RowKeySet</code> object. Adding the row to the set displays
+        the details of the row. Removing the row hides them.
+      </P>
+      <subsection name="RowDisclosureEvent">
+        <P>
+          When the user hides or shows the details of a row, the Table
+          generates a <code>RowDisclosureEvent</code>. This event has
+          properties that return which rows were disclosed and which were
+          undisclosed. The Table responds to this by expanding or collapsing
+          the details of those rows.
+        </P>
+        <p>
+          You can register custom <code>RowDisclosureListener</code> instances
+          (that can do post processing) on the Table component.
+        </p>
+      </subsection>
+    </section>
+
+    <section name="Selection">
+      <p>
+        The selection feature of a Table lets the user select one or more rows
+        in the list. The user can then perform some operation on the selected
+        rows by activating an appropriate ActionSource component (e.g., by
+        clicking on an ADF CommandButton). Use the "rowSelection" attribute on
+        the Table to enable the selection feature (see the examples below).
+      </p>
+      <p>
+        There are two types of selection - single and multiple. The type of
+        selection is determined by the value of the "selection" attribute.
+        Use the value "single" to enable single selection, and "multiple" to
+        enable multiple selection.
+      </p>
+      <P>
+        The current selection of rows on the Table can be programmatically
+        inspected and modified via the <code>RowKeySet</code> object obtained
+        by calling <code>getSelectedRowKeys()</code> on the Table. To
+        programmatically change a selection, add or remove rowKeys from this
+        Set. Alternatively, the appropriate row can be made current by calling
+        <code>setRowIndex(...)</code> or <code>setRowKey(...)</code> on the
+        Table, and then the selection of that row may be changed by calling
+        <code>add()</code> or <code>remove()</code> on the
+        <code>RowKeySet</code>.
+      </P>
+      <subsection name="Selection Example">
+        <P>
+          In the following example, the <code>performDelete</code> method is
+          called when the "Delete" button is clicked.
+        </P>
+        <source><![CDATA[
+<tr:table binding="#{mybean.table}" rowSelection="multiple" ...>
+  <f:facet name="footer">
+      <tr:commandButton text="Delete" actionListener="#{mybean.performDelete}"/>
+  </f:facet>
+  ...
+</tr:table>]]>
+        </source>
+        <P>
+          The <code>performDelete</code> method iterates through all the
+          selected rows and calls the <code>markForDeletion()</code> method on
+          each one:
+        </P>
+        <source>
+public void performDelete(ActionEvent action)
+{
+  UIXTable table = getTable();
+  Iterator selection = table.getSelectedRowKeys().iterator();
+  Object oldKey = table.getRowKey();
+  while(selection.hasNext())
+  {
+    Object rowKey = selection.next();
+    table.setRowKey(rowKey);
+    MyRowImpl row = (MyRowImpl) table.getRowData();
+    row.markForDeletion();
+  }
+  // restore the old key:
+  table.setRowKey(oldKey);
+}
+
+// Binding methods for access to the table.
+public void setTable(UIXTable table) { _table = table; }
+public UIXTable getTable() { return _table; }
+private UIXTable _table;
+        </source>
+      </subsection>
+      <subsection name="SelectionEvent">
+        <P>
+          The &lt;tr:table&gt; component triggers SelectionEvents when
+          the selection state is changed. The SelectionEvent
+          reports which rows were just deselected and which rows were just
+          selected. Listeners for this event may be registered on the table
+          using the "selectionListener" attribute or by adding the listener to
+          the table using the "addSelectionListener" method.
+        </P>
+      </subsection>
+    </section>
+
+    <section name="Sorting">
+      <p>
+        The Table component supports sorting columns in ascending or
+        descending order. A special UI indicator on a column header lets the
+        user know that the column is sortable. When the user clicks on a
+        column header to sort a previously unsorted column, the Table sorts
+        the column data in ascending order. Subsequent clicks on the same
+        header sort the data in the reverse order.
+      </p>
+      <p>
+        There are three requirements to enable sorting: the underlying table
+        model must support sorting, the "sortProperty" and "sortable"
+        attributes must be set on the column to enable the sort capability for
+        that column.
+      </p>
+      <P>
+        To support sorting, the <code>CollectionModel</code> instance must implement the following methods:</P>
+        <source>
+public boolean isSortable(String propertyName)
+public List getSortCriteria()
+public void setSortCriteria(List criteria)
+        </source>
+      <P>
+        If the underlying model is not a <code>CollectionModel</code>, the
+        Table automatically examines the actual data to determine which
+        properties are sortable. Any column that has data that implements
+        <code>java.lang.Comparable</code> are sortable.  This automatic
+        support cannot be nearly as efficient as coding sorting directly into
+        a <code>CollectionModel</code> (for instance, by translating the sort
+        into an "ORDER BY" SQL clause), but is sufficient for small data sets.
+      </P>
+      <P>
+        To associate a column with a particular property-name to be used for
+        sorting purposes, use the "sortProperty" attribute on the column.
+        To enable the UI for sorting a particular column, set the
+        "sortable" property to <code>true</code>.
+      </P>
+      <P>
+        In the following example,
+        both columns are sortable. Sorting the first column sorts by the
+        "firstname" property; sorting the second column sorts by the "lastname"
+        property.
+      </P>
+      <source><![CDATA[
+<tr:table ...>
+  <tr:column sortProperty="firstname" sortable="true">
+    <f:facet name="header">
+      <tr:outputText value="Firstname" />
+    </f:facet>
+    ...
+  </tr:column>
+  <tr:column>
+    <f:facet name="header" sortProperty="lastname" sortable="true">
+      <tr:outputText value="Lastname" />
+    </f:facet>
+    ...
+  </tr:column>
+</tr:table>]]>
+      </source>
+
+      <subsection name="SortEvent">
+        <p>
+          When the user clicks a sortable column header, the
+          <code>&lt;tr:table&gt;</code> component generates a
+          <code>SortEvent</code>. This event has a
+          <code>getSortCriteria()</code> property that returns the criteria
+          that the table must be sorted by.
+        </p>
+        <p>
+          The Table responds to this event by calling the
+          <code>setSortCriteria</code> method on the underlying
+          <code>CollectionModel</code>. Any registered
+          <code>SortListener</code> instances will also be called.
+        </p>
+      </subsection>
+
+    </section>
+
+    <section name="Grid Lines and Banding">
+      <P>
+        By default, the table draws both horizontal and vertical grid lines.
+        These may be independently turned off by setting the
+        "horizontalGridVisible" and/or "verticalGridVisible" attributes to
+        "false".
+      </P>
+      <P>
+        Banding is a technique where groups of rows (or columns)
+        are displayed with alternating background colors. This helps to
+        differentiate between adjacent groups of rows (or columns).
+      </P>
+      <P>
+        The "rowBandingInterval" attribute on the Table controls how many
+        consecutive rows form a row group (for the purposes of banding). If
+        this is "0" all rows will have the same background color. If this is a
+        positive number then adjacent row groups will have different
+        background colors.
+      </P>
+      <P>
+        The "columnBandingInterval" attribute on the Table controls how many
+        columns form a column group (for the purposes of banding). If this is
+        "0" all columns will have the same background color. If this is a
+        positive number then adjacent column groups will have different
+        background colors.
+      </P>
+      <P>
+        In the following example, the row banding pattern is to have two rows
+        with a light background, followed by two rows with a dark
+        background. The pattern is repeated across all rows. Similarly the
+        column banding pattern is to have alternating light/dark columns.
+      </P>
+      <source><![CDATA[
+<tr:table rowBandingInterval="2" columnBandingInterval="1" ...>
+  ...
+</tr:table>]]>
+      </source>
+    </section>
+
+  </body>
+</document>

Added: incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/tree.xml
URL: http://svn.apache.org/viewvc/incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/tree.xml?rev=429972&view=auto
==============================================================================
--- incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/tree.xml (added)
+++ incubator/adffaces/trunk/trinidad/src/site/xdoc/devguide/tree.xml Tue Aug  8 22:46:09 2006
@@ -0,0 +1,321 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<document>
+  <properties>
+    <title>Using the Apache Trinidad Tree Component</title>
+  </properties>
+
+  <body>
+    <section name="Using the Apache Trinidad Tree Component">
+      <p>
+        <ul>
+          <li><a href="#Introduction">Introduction</a></li>
+          <li><a href="#The Tree Model">The Tree Model</a></li>
+          <li><a href="#Tree">Tree</a>
+            <ul>
+              <li><a href="#Data">Data</a></li>
+              <li><a href="#RowDisclosureEvent">RowDisclosureEvent</a></li>
+              <li><a href="#SelectionEvent">SelectionEvent</a></li>
+            </ul>
+          </li>
+          <li><a href="#TreeTable">TreeTable</a>
+            <ul>
+              <li><a href="#RowDisclosureEvent - TreeTable">RowDisclosureEvent</a></li>
+              <li><a href="#SelectionEvent - TreeTable">SelectionEvent</a></li>
+            </ul>
+          </li>
+          <li><a href="#Expand/Collapse State">Expand/Collapse State</a></li>
+          <li><a href="#Selection State">Selection State</a></li>
+          <li><a href="#Grid Lines and Banding">Grid Lines and Banding</a></li>
+        </ul>
+      </p>
+    </section>
+
+
+    <section name="Introduction">
+      <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. Each element (employee) in the hierarchy may have
+        any number of child elements (direct reports). In addition several
+        parent elements may share the same child elements.
+      </P>
+
+      <P>
+        Apache Trinidad currently provides two tree components: Tree and TreeTable. 
+        The Apache Trinidad Tree component supports multiple root elements, and it has a
+        simple user interface (UI) - each element in the Tree is appropriately indented to indicate
+        its level in the hierarchy, and is connected to its parent.
+        The features of the Tree component include mechanisms for expanding and
+        collapsing portions of the hierarchy.
+      </P>
+
+      <P>
+        The Apache Trinidad TreeTable component displays a hierarchy
+        in a UI similar to an Apache Trinidad Table, and is more elaborate than the Tree component. TreeTable supports displaying columns of data per element in the hierarchy. The features of the TreeTable
+        component include mechanisms for focusing in on subtrees (within the main
+        tree), as well as expanding and collapsing elements in the hierarchy.
+      </P>
+
+      <P>
+        We recommend that you familiarize yourself with the <a
+        href="table.html">Table component</a> before reading the rest of this chapter.
+      </P>
+    </section>
+
+    <section name="The Tree Model">
+      <P>
+        The Apache Trinidad tree components use a model to access the data in the
+        underlying hierarchy.  The specific model class is
+        <code>org.apache.myfaces.trinidad.model.TreeModel</code>.
+        <code>TreeModel</code> extends <code>CollectionModel</code> (see <a
+        href="table.html">Using Apache Trinidad Tables</a> for more information
+        about the <code>CollectionModel</code>). In other words, the
+        <code>TreeModel</code> is a collection of rows. It has an
+        <code>isContainer</code> method that returns <code>true</code> if the
+        current row contains child rows. The children of the current row can
+        be accessed by calling the <code>enterContainer</code> method. Once
+        this method is called the <code>TreeModel</code> instance will change
+        to be a collection of the child rows. To jump back up to the parent
+        collection, call the <code>exitContainer</code> method.
+      </P>
+
+      <P>
+        You may find the
+        <code>org.apache.myfaces.trinidad.model.ChildPropertyTreeModel</code> class
+        useful when constructing a <code>TreeModel</code>.
+      </P>
+
+    </section>
+
+    <section name="Tree">
+      <P>
+        The Tree component displays a multi-root hierarchy in a simple UI
+        where each element in the hierarchy is indented relative to
+        the corresponding parent element.
+      </P>
+
+      <subsection name="Data">
+        <P>
+          The Tree uses a stamping strategy similar to the Apache Trinidad Table
+          component.  The "nodeStamp" facet of the Tree is used to display the
+          data for each element in the tree. The Tree does not create
+          components per element; instead, the "nodeStamp" is repeatedly
+          rendered (stamped) once per element. Because of this stamping
+          behavior, only certain types of components are supported as
+          children inside a Tree. Supported components include all
+          components with no behavior and most components that implement the
+          ValueHolder or ActionSource interfaces.
+        </P>
+        <P>
+          Each time the "nodeStamp" is stamped, the data for the current
+          element (see <code>getRowData()</code> in <a href="table.html">Using
+          Apache Trinidad Tables</a>) is copied into an EL reachable property.  The
+          name of this property is defined by the <code>var</code> property on
+          the Tree. Once the Tree has completed rendering, this property is
+          removed (or reverted back to its previous value). In the following
+          example, the data for each element is placed under the EL property
+          "node". The "nodeStamp" displays the data for each element by
+          getting further properties from the "node" property:
+        </P>
+        <source><![CDATA[
+<tr:tree var="node">
+  <f:facet name="nodeStamp">
+    <tr:outputText value="#{node.firstname}"/>
+  </f:facet>
+</tr:tree>]]>
+        </source>
+      </subsection>
+      <subsection name="RowDisclosureEvent">
+        <P>
+          The Tree renders expand/collapse icons that the user can click on to
+          expand or collapse a subtree. When these icons are clicked, the Tree
+          generates a <code>RowDisclosureEvent</code>. This event has two <code>
+          RowKeySet</code> objects. One, called RemovedSet, for all the collapsed
+          nodes and one, called AddedSet, for all the expanded nodes. The Tree 
+          expands the subtrees under all nodes in the added set and collapses the
+          subtrees under all nodes in the removed set.
+        </P>
+        <p>
+          You can register custom <code>RowDisclosureListener</code> instances
+          (that can do post processing) on the Tree component.
+        </p>
+      </subsection>
+
+      <subsection name="SelectionEvent">
+        <P>
+          The Tree supports a <code>rowSelection</code> attribute. Valid
+          values for the <code>rowSelection</code> attribute are: single, multiple,
+          and none. If a Tree is selectable, clicking on a node causes the tree to 
+          highlight the node and render it as selected. ctrl-click and shift-click
+          operations are supported for trees which support multiple selections. 
+          When nodes are selected/unselected, the Tree fires a <code>SelectionEvent
+          </code>. This event has two <code>RowKeySet</code> objects. One, called 
+          RemovedSet, for all the unselected nodes and one, called AddedSet, 
+          for all the selected nodes.
+        </P>
+        <p>
+          You can register custom <code>SelectionListener</code> instances
+          (that can do post processing) on the Tree component.
+        </p>
+      </subsection>
+
+    </section>
+    
+    <section name="TreeTable">
+      <P>
+        The TreeTable component displays a hierarchy in a UI 
+        similar to Table. Like the Table, the TreeTable's children must be Apache Trinidad
+        Column components (Please see <a
+        href="table.html#Columns">Table Columns</a>). Like the Tree, the TreeTable has a "nodeStamp"
+        facet which renders the "Object Name" Column. The TreeTable has a
+        "pathStamp" facet for rendering the focus path.
+      </P>
+      <P>
+        The "Object Name" Column contains the primary identifier of an element
+        in the hierarchy. For example, in an organization chart of employees, the "Object Name"
+        Column might be the employee name.
+      </P>
+      <P>
+        The TreeTable supports the same stamping behavior as the
+        Tree component. In the following example, The "Object Name" Column is
+        the "Employee Name" Column. For each element (that is, employee) the
+        TreeTable stamps out the name, ID and the department.
+      </P>
+      <source><![CDATA[
+<tr:treeTable var="node">
+  <f:facet name="nodeStamp">
+    <tr:column>
+      <f:facet name="header">
+        <tr:outputText value="Employee Name"/>
+      </f:facet>
+      <tr:outputText value="#{node.ename}"/>
+    </tr:column>
+  </f:facet>
+  <f:facet name="pathStamp">
+    <tr:outputText value="#{node.ename}"/>
+  </f:facet>
+  <tr:column>
+    <f:facet name="header">
+      <tr:outputText value="Employee Id"/>
+    </f:facet>
+    <tr:outputText value="#{node.empid}"/>
+  </tr:column>
+  <tr:column>
+    <f:facet name="header">
+      <tr:outputText value="Department"/>
+    </f:facet>
+    <tr:outputText value="#{node.dname}"/>
+  </tr:column>
+</tr:treeTable>]]>
+      </source>
+      <P>
+        The TreeTable supports all the formatting properties that are supported by the
+        Column component.  Please see <a
+        href="table.html#Columns">Using Apache Trinidad Tables</a> for more
+        information about the Apache Trinidad Column component.
+      </P>
+
+     <subsection name="FocusEvent">  	 
+        <P> 	 
+          In addition to displaying expand/collapse icons, the TreeTable also 	 
+          renders a column containing "focus" icons that a user can click to 	 
+          focus on (or zoom into) a particular element's subtree of children. 	 
+        </P> 	 
+        <p> 	 
+          To focus (or zoom) out of a subtree, the user can click on 	 
+          path links that are rendered above the TreeTable. These path links 	 
+          are rendered by the "pathStamp" facet. If this facet is not provided 	 
+          the focus column and the path links are not rendered. 	 
+        </p> 	 
+        <P> 	 
+          The TreeTable has a "focusPath" property that controls which element 	 
+          has the current focus. This property is a 	 
+          <code>java.util.List</code> of row-keys that describe a path from 	 
+          the root to the element that has the focus. 	 
+        </P> 	 
+        <P> 	 
+          When the user focuses in or out, the TreeTable generates a 	 
+          <code>FocusEvent</code>. The element that the user focused in, is 	 
+          made current before the event is delievered. The TreeTable responds 	 
+          to this event by modifying the "focusPath" property appropriately. 	 
+          Subsequently, any registered <code>FocusListener</code> instances 	 
+          are called. 	 
+        </P> 	 
+      </subsection>
+
+     <subsection name="DisclosureAllEvent">
+        <P> 	 
+          The TreeTable allows the user to expand or collapse all the subtrees 	 
+          by clicking on special "expand-all" or "collapse-all" links. In 	 
+          response to this, the TreeTable generates a 	 
+          <code>DisclosureAllEvent</code>. This event has an 	 
+          <code>isExpandAll</code> method that returns whether the user wants 	 
+          to show or hide all the subtrees. 	 
+        </P> 	 
+        <P>
+          The TreeTable responds to this by expanding or collapsing all the
+          elements under the current focus root. If the tree is massive, the
+          expand-all operation will not propagate beyond the children of the
+          current focus root.
+        </P>
+      </subsection>
+
+      <subsection name="RowDisclosureEvent - TreeTable">
+        <P>
+          Like the Tree component the TreeTable generates a
+          <code>RowDisclosureEvent</code>. Please see the Tree's <a
+          href="#RowDisclosureEvent">RowDisclosureEvent</a> description for more
+          information about this event.
+        </P>
+      </subsection>
+
+      <subsection name="SelectionEvent - TreeTable">
+        <P>
+          Like the Tree component the TreeTable generates a
+          <code>SelectionEvent</code>. Please see the Tree's <a
+          href="#SelectionEvent">SelectionEvent</a> description for more
+          information about this event.
+        </P>
+      </subsection>
+
+    </section>
+
+    <section name="Expand/Collapse State">
+      <P>
+        The Apache Trinidad tree components use an instance of the
+        <code>org.apache.myfaces.trinidad.model.RowKeySet</code> class to keep track
+        of which elements are expanded. This instance is stored as the
+        "disclosedRowKeys" attribute on the component. You may use this instance to
+        programmatically control the expand/collapse state of an element in
+        the hierarchy. Any element contained by the <code>RowKeySet</code>
+        instance is deemed expanded. All other elements are collapsed.  This
+        class also supports operations like <code>addAll()</code> and
+        <code>removeAll()</code>.
+      </P>
+    </section>
+
+    <section name="Selection State">
+      <P>
+        The Apache Trinidad tree components use an instance of the
+        <code>org.apache.myfaces.trinidad.model.RowKeySet</code> class to keep track
+        of which elements are selected. This instance is stored as the
+        "selectedRowKeys" attribute on the component. You may use this instance to
+        programmatically control the selection state of an element in
+        the hierarchy. Any element contained by the <code>RowKeySet</code>
+        instance is deemed selected. All other elements are not selected.  This
+        class also supports operations like <code>addAll()</code> and
+        <code>removeAll()</code>.
+      </P>
+
+    </section>
+
+    <section name="Grid Lines and Banding">
+        Like the Table component, the TreeTable component supports vertical and horizontal
+        grid lines and banding. Please see <a
+        href="table.html#Grid Lines and Banding">Table Grid Lines and Banding</a> for more
+        information.
+    </section>
+
+  </body>
+</document>

Added: incubator/adffaces/trunk/trinidad/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/incubator/adffaces/trunk/trinidad/src/site/xdoc/index.xml?rev=429972&view=auto
==============================================================================
--- incubator/adffaces/trunk/trinidad/src/site/xdoc/index.xml (added)
+++ incubator/adffaces/trunk/trinidad/src/site/xdoc/index.xml Tue Aug  8 22:46:09 2006
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<document>
+  <properties>
+    <title>Index</title>
+  </properties>
+
+  <body>
+    <section name="Contents">
+      <p>
+        <ul>
+          <li>
+            <a href="#Overview">Overview</a>
+          </li>
+          <li>
+            <a href="#Releases">Releases</a>
+          </li>
+          <li>
+            <a href="#Live Demos">Live Demos</a>
+          </li>
+          <li>
+            <a href="#FAQ and Support">FAQ and Support</a>
+          </li>
+        </ul>
+      </p>
+      </section>
+
+      <section name="Overview">
+        <p>
+      Apache Trinidad is based on Java Server Faces (JSF).
+      We've done our best to solidify
+      APIs, but we must warn developers that APIs may change after this release.
+      </p>
+      </section>
+
+      <section name="FAQ and Support">
+        <p>
+Please see the <a href="FAQ.html" >Apache Trinidad FAQ</a> for help.
+        </p>
+        <p>
+If the FAQ is insufficient, please send e-mail to the <a href="mailto:adffaces_user@incubator.apache.org">adffaces_user</a> mailing list.
+        </p>
+      </section>
+  </body>
+</document>