You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by do...@apache.org on 2005/08/26 00:46:21 UTC
svn commit: r240153 -
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsTree.xml
Author: dolander
Date: Thu Aug 25 15:46:20 2005
New Revision: 240153
URL: http://svn.apache.org/viewcvs?rev=240153&view=rev
Log:
Update the Tree doc for review by Krista
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsTree.xml
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsTree.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsTree.xml?rev=240153&r1=240152&r2=240153&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsTree.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsTree.xml Thu Aug 25 15:46:20 2005
@@ -10,10 +10,12 @@
<title>Introduction</title>
<p>The following topic explains the tree tags and classes and how they are used to create
and render trees. A tree is rendered in an HTML page based upon an
- object based representation of the tree. NetUI defines a set of classes which
- create a tree structure which is rendered. The object representation may be created
+ object representation of the tree. NetUI defines a set of classes which
+ create the tree structure which is rendered. The object representation may be created
either through NetUI JSP tags found in a JSP page or may be created programmatically
- in a Page Flow.
+ in a Page Flow or Shared Flow. This means that there are parallel representations
+ of a tree. In a JSP page, a set of JSP tags represent the tree. This representation is
+ then transformed into an tree data structure defined by a set of tree classes.
</p>
</section>
@@ -50,30 +52,34 @@
</netui:body>
</netui:html>
]]></source>
- <p>The <netui:tree> tag is JSP tag that includes a tree into the page. It is responsible
+ <p> The <code><netui:tree></code> tag is JSP tag that includes a tree into the page. It is responsible
for rendering the tree in the generated HTML page. In this example, the contents of the tree
itself is also
- defined in the <netui:tree> tag by using the <netui:treeItem> tags and nesting them
+ defined in the <code><netui:tree></code> tag by using the <code><netui:treeItem></code>
+ tags and nesting them
in a tree structure. In this simple case, the tree has a root (0) with three children (0.0,
0.1, and 0.2).
</p>
- <p> There are two required attributes on the <netui:tree> tag,
- <strong>dataSource</strong>
+ <p> There are two required attributes on the <code><netui:tree></code> tag,
+ <code>dataSource</code>
and
- <strong>selectionAction</strong>. The dataSource is used to bind to a
- <strong>TreeElement</strong> based data structure representing the tree to be displayed.
+ <code>selectionAction</code>. The <code>dataSource</code> is used to bind to a
+ <code>TreeElement</code> based data structure representing the tree to be displayed.
The selectionAction is the action that will be called when a node is selected
- in the tree. It will also be called in some cases when a node in the tree is expanded or
- collapsed.
+ in the tree. In some cases, it may also be called when a node in the tree is expanded or
+ collapsed. In addition, the <code>tagId</code> attribute is also required. If
+ <code>runAtClient</code> is <code>true</code> then you must also specify the name of the
+ tree by setting the <code>tagId</code>.
</p>
<p>
<strong>Note:</strong> In the example above, the leaf nodes are defined in two manners. The
- first child (0.0) uses the <netui:treeLabel> to set the nodes label. The next two
- children (0.1 and 0.2) are defined with the label as the body of the <netui:treeItem>. The
- treeItem supports setting the label value from the treeItem body only if that treeItem is
- a leaf. You are required to use the <netui:treeLabel> for all interior nodes. In other
- words, <netui:treeItem> does not support mixed content; meaning that interior nodes must use
- <netuiLabel> to set the label value and all text inside the body is ignored.
+ first child (0.0) uses the <code><netui:treeLabel></code> to set the nodes label. The next two
+ children (0.1 and 0.2) are defined with the label as the body of the <code><netui:treeItem></code>. The
+ <code><netui:treeItem></code> supports setting the label value from the body of the
+ <code><netui:treeItem></code> it is a leaf in the tree. You are required to use
+ the <code><netui:treeLabel></code> for all interior nodes. In other
+ words, <code><netui:treeItem></code> does not support mixed content; meaning that interior nodes must use
+ <code><netui:treeLabel></code> to set the label value and all text inside the body is ignored.
</p>
<p>
<strong>Controller.jpf</strong>
@@ -106,47 +112,49 @@
}
]]></source>
<p>This very simple Page Flow Controller supports displaying a tree. There is a single property
- "simpleTree" which holds a reference to a TreeElement. This TreeElement represents the root
- of the underlying tree object structure which is rendered by the <netui:tree> tag. There are
- two actions defined, the standard
- <strong>begin</strong> action and the
- <strong>postback</strong>
+ "simpleTree" which holds a reference to a <code>TreeElement</code>. This <code>TreeElement</code> represents the root
+ of the underlying tree object structure which is rendered by the <code><netui:tree></code> tag.
+ There are two actions defined, the standard
+ <code>begin</code> action and the
+ <code>postback</code>
action. The
- <strong>postback</strong> action is called when a selection or expand link is selected
+ <code>postback</code> action is called when a selection or expand link is selected
in the rendered tree.
</p>
</section>
<section id="ExampleLifecycle">
<title>Simple Sample Lifecycle</title>
<p> This section describes the basic tree lifecycle using the SimpleTree example above. The
- following figure represents the basic lifecycle of a tree being rendered by a <netui:tree>
+ following figure represents the basic lifecycle of a tree being rendered by a <code><netui:tree></code>
tag.
</p>
<p>
<img src="images/simpleTreeFlow.png" alt="Tree Tag Lifecycle"/>
</p>
- <p> The <strong>dataSource</strong> attribute is a required attribute on all trees. It binds
- to an instance of a
- <strong>TreeElement</strong> [defined in
- <strong>org.apache.beehive.netui.tags.tree</strong>]. All trees are represented as tree data
- structure with a single root. The dataSource attribute binds to this root.
+ <p> The <code>dataSource</code> attribute is a required attribute on all trees. It binds
+ to an instance of a <code>TreeElement</code> [defined in
+ <code>org.apache.beehive.netui.tags.tree</code>]. All trees are represented as tree data
+ structure with a single root. The <code>dataSource</code> attribute binds to this root.
</p>
- <p>When the <netui:tree> tag begins processing it checks to see if the variable
- bound to by the <strong>dataSource</strong> is equal to null. If it is, then the tree will
+ <p>When the <code><netui:tree></code> tag begins processing it checks to see if the variable
+ bound to by the <code>dataSource</code> is equal to null. If it is, then the tree will
process it's body content to create the tree data structure. If the
- <strong>dataSource</strong> is not null, then that tree data structure is used to render content.
+ <code>dataSource</code> is not null, then that tree's data structure is used to render content.
+ If you want to programmatically (or dynamically) create a tree, you may create the tree structure
+ before the bound variable is accessed. Typically this would be done in the <code>onCreate</code>
+ method of a shared flow or page flow.
</p>
<p>In the simpleTree sample, the first time the page is displayed the body of the tree tag is
processed because the Page Flow property
- <strong>simpleTree</strong> is null. This creates the initial
+ <code>simpleTree</code> is null. This creates the initial
tree data structure which is then rendered. When the page is requested
again, for example when a tree element is selected, the tree data structure created on the first
- request continues to be used and the body of the <netui:tree> tag is ignored.
+ request continues to be used and the body of the <code><netui:tree></code> tag is ignored.
</p>
<p> <strong>Note:</strong> A very common development task is to iteratively develop the
- <netui:tree>'s body content. In order for any changes to be reflected when the tree is
+ <code><netui:tree></code>'s body content. In order for any changes to be reflected when the tree is
rendered, the variable bound to by
- <strong>dataSource</strong> must be null. It is
+ <code>dataSource</code> must be null. It is
common to add an action to the page flow that will reset the value to null and call
that from a link on a page. If variable is not null, changes to the JSP page will not be
reflected in the rendered tree.
@@ -166,7 +174,7 @@
</section>
<section id="Classes">
<title>NetUI Tree Classes</title>
- <p>This section describes the underlying classes which represent a tree</p>
+ <p>This section describes the underlying classes which represent a tree.</p>
</section>
<section id="TagToClassMapping">
<title>Tag to Class Mapping</title>
@@ -177,70 +185,65 @@
<p>
<strong>Note: </strong> in many cases, this document describes setting attributes on the tree
JSP tags to enable features. In reality, the attributes are passed through to the
- <strong>TreeElement</strong> class which usually has a corresponding property. Other tags
+ <code>TreeElement</code> class which usually has a corresponding property. Other tags
map their values to properties of the
- <strong>TreeElement</strong>. If you
- are programmatically creating a tree by building the tree hierarchy using TreeElements, you
+ <code>TreeElement</code>. If you
+ are programmatically creating a tree by building the tree hierarchy using <code>TreeElement</code>s, you
directly set properties on the tree class.
</p>
<p> The following list describes the mapping of the tree JSP tags to underlying tree classes:
</p>
<ul>
- <li><strong>Tree</strong> -- The Tree tag doesn't create a TreeElement. It binds to
- a TreeElement representing the root of the tree data structure. The Tree tag does create
- the initial
- <strong>TreeRenderState</strong> object representing how the tree is rendered.
- </li>
- <li><strong>TreeItem</strong> -- The TreeItem tag will create a
- <strong>TreeElement</strong>.
- If the TreeItem is the root of a tree, then the
- <strong>TreeRootElement</strong> will be created.
- </li>
- <li><strong>TreeLabel</strong> -- The TreeLabel tag sets the value of the Label which is
- stored as a property of a TreeItem. This is required for non-leaf nodes. For leaf nodes
- the body content of the TreeItem will be used as the label value as long as that body does
+ <li><strong><code>Tree</code></strong> -- The <code><netui:tree></code> tag doesn't create
+ a <code>TreeElement</code>. It binds to
+ a <code>TreeElement</code> representing the root of the tree data structure. The <code><netui:tree></code>
+ tag does create the initial <code>TreeRenderState</code> object representing how the tree is rendered.
+ </li>
+ <li><strong><code>TreeItem</code></strong> -- The <code><netui:treeItem></code> tag will create a
+ <code>TreeElement</code>. If the <code><netui:treeItem></code> is the root of a tree, then the
+ <code>TreeRootElement</code> will be created.
+ </li>
+ <li><strong><code>TreeLabel</code></strong> -- The <code><netui:treeLabel></code> tag sets
+ the value of the label which is stored as a property of a <code>TreeElement</code>.
+ Using this tag is required for non-leaf nodes. For leaf nodes
+ the body content of the <code><netui:treeItem></code> will be used as the label value as long as that body does
not contain other JSP tags (mixed content).
</li>
- <li><strong>TreeContent</strong> -- The TreeContent tag sets the value of the content for a
- TreeItem. The content is a property of the
- <strong>TreeElement</strong>.
- </li>
- <li><strong>TreeProperyOverride</strong> -- The TreePropertyOverride tag is used to override various
- attributes on the tree such as the selection action and images. This tag will create an
- <strong>InheritableState</strong> object and set it on the
- <strong>TreeElement</strong>.
- </li>
- <li><strong>TreeHtmlAttribute</strong> -- The TreeHtmlAttribute tag is used to set additional
- attributes on the HTML generated when rendering the node. This tag will create a
- <strong>TreeHtmlAttributeInfo</strong> class that is set on the
- <strong>TreeElement</strong>.
+ <li><strong><code>TreeContent</code></strong> -- The <code><netui:treeContent></code> tag sets the
+ value of the content for a <code>TreeElement</code>. The content is a property of the
+ <code>TreeElement</code>.
+ </li>
+ <li><strong><code>TreeProperyOverride</code></strong> -- The <code><netui:treePropertyOverride></code>
+ tag is used to override various attributes on the tree such as the selection action and images.
+ This tag will create an <code>InheritableState</code> object and set it on the
+ <code>TreeElement</code>.
+ </li>
+ <li><strong><code>TreeHtmlAttribute</code></strong> -- The <code><netui:treeHtmlAttribute></code>
+ tag is used to set additional attributes on the HTML generated when rendering the node.
+ This tag will create a <code>TreeHtmlAttributeInfo</code> class that is set on the
+ <code>TreeElement</code>.
</li>
</ul>
</section>
<section id="ITreeRootElement">
<title>ITreeRootElement</title>
<p>In the SimpleTree example above, we described the tree data structure as being a
- hierarchy of
- <strong>TreeElement</strong> nodes. Many advanced features, including runAtClient, of the tree
- require the root of the tree to implement the interface
- <strong>ITreeRootElement</strong>.
- The class
- <strong>TreeRootElement</strong> extends
- <strong>TreeElement</strong> and
- implements
- <strong>ITreeRootElement</strong>, providing a default implementation.
- In the SimpleTree example, when the body
- of the <netui:tree> is processed, the root <netui:treeItem> is created as a
- TreeRootElement and all other <netui:treeItem>'s are created as TreeElements.
+ hierarchy of <code>TreeElement</code> nodes. Many advanced features, including runAtClient, of the tree
+ require the root of the tree to implement the interface <code>ITreeRootElement</code>.
+ The class <code>TreeRootElement</code> extends <code>TreeElement</code> and implements
+ <code>ITreeRootElement</code>, providing a default implementation. In the SimpleTree example,
+ when the body
+ of the <code><netui:tree></code> is processed, the root <code><netui:treeItem></code> is created as a
+ <code>TreeRootElement</code> and all other <code><netui:treeItem></code>'s are created as <code>TreeElements</code>.
</p>
- <p> The following features require the root element in a tree to implement ITreeRootElement:
+ <p> The following features require the root element in a tree to implement <code>ITreeRootElement</code>:
</p>
<ul>
- <li><strong>runAtClient</strong> -- runAtClient support allows the tree to be expanded and
+ <li><strong><code>runAtClient</code></strong> -- runAtClient support allows the tree to be expanded and
collapsed on the client without round trips to the server.
</li>
<li><strong>Root Images</strong> -- Allows setting different expand and collapse images
- on the root.
+ on the root node of the tree.
</li>
</ul>
<p>The following additional state is tracked by the root element:
@@ -251,7 +254,8 @@
<li><strong>Tree State</strong> -- Access to the InheritableState and TreeRenderState
defined on the tree. (Explained below)
</li>
- <li><strong>Images</strong> -- Allows different expand and collapse images to be set on the root.
+ <li><strong>Images</strong> -- Allows different expand and collapse images to be set on the root
+ supporting the Root Images feature.
</li>
</ul>
</section>
@@ -260,21 +264,21 @@
<title>Tree Features</title>
<p>This section describes the basic features of the NetUI Tree. The SimpleTree example introduces the
basic mechanics for creating a tree in a Page Flow. A tree is output into the HTML page as
- a hierarchy of TreeElements. The SimpleTree example output the following:
+ a hierarchy of <code>TreeElement</code>s. The SimpleTree example renders the following:
</p>
<p>
<img src="images/simpleTreePage.png" alt="Tree Tag Display"/>
</p>
<p>The root of the tree supports expanding and collapsing. The children of a node appear
- at the same level. Trees appear commonly in applications such as file system explorers, and
+ at the same level. Trees appear commonly in applications such as file system explorers and
are good at representing limited hierarchical data sets.
</p>
<section id="runAtClient">
<title>runAtClient</title>
- <p> The <netui:tree> tag has an attribute
- <strong>runAtClient</strong> which when
+ <p> The <code><netui:tree></code> tag has an attribute
+ <code>runAtClient</code> which when
set to
- <strong>true</strong> will enabled expanding and collapsing the tree on the client
+ <code>true</code> will enabled expanding and collapsing the tree on the client
without server round trips. When runAtClient is on, the tree will be completely rendered
into the generated HTML. Client side JavaScript will then collapse and expand nodes when
the user interacts with the tree. The following image describes the interactions between
@@ -284,7 +288,7 @@
<img src="images/runAtClientFlow.png" alt="Flow of the tree when runAtClient is true"/>
</p>
<p> runAtClient uses
- <strong>XmlHttpRequest</strong> to update the underlying state on the server
+ <code>XmlHttpRequest</code> to update the underlying state on the server
as the user interacts with the tree on the client. This mode requires JavaScript and XmlHttpRequest
support in the client browser. This mode of operation is commonly referred to as AJAX
(Asynchronous JavaScript and XML). It minimizes the amount of information sent between
@@ -303,12 +307,12 @@
interacted with the tree.
</p>
</section>
- <section id="expandOnClient">
- <title>expandOnClient</title>
- <p> When a tree has the <strong>runAtClient</strong> attribute set, then individual elements
+ <section id="expandOnServer">
+ <title>expandOnServer</title>
+ <p> When a tree has the <code>runAtClient</code> attribute set, then individual elements
can indicate that they need to be expanded on the server by setting the
- <strong>expandOnServer</strong> attribute on the <netui:treeItem> tag. When
- expandOnClient is enabled, if the node is in a collapsed state,
+ <code>expandOnServer</code> attribute on the <code><netui:treeItem></code> tag. When
+ <code>expandOnServer</code> is enabled, if the node is in a collapsed state,
the node itself will be rendered in the generated HTML, but
all children nodes will not. When the user expands the node, an XmlHttpRequest is made
to the server and the children (and possibly their children) will be rendered into HTML
@@ -316,12 +320,12 @@
displayed. Once the children are received, all further expand and collapse operations happen
on the client.
</p>
- <p> runAtClient and expandOnClient can be used together to optimize the amount of tree state
+ <p> runAtClient and <code>expandOnServer</code> can be used together to optimize the amount of tree state
rendered into the initial request and then to minimize the amount of state transferred
when the user is exploring the tree. It is very common for people to drill
into one or two areas of a tree after searching the top level nodes. To optimize for
this type of browsing, render out the top few levels of a tree and then create a layer
- of children that set expandOnClient to true. The top few layers will be initially rendered
+ of children that set <code>expandOnServer</code> to true. The top few layers will be initially rendered
and when a user goes deep into one, the server provides the branch asynchronously when requested.
</p>
</section>
@@ -349,7 +353,7 @@
<img src="images/lastNodeExpanded.gif" alt="lastNodeExpanded.gif"/> - lastNodeExpanded.gif
<img src="images/rootExpanded.gif" alt="rootExpanded.gif"/> - rootExpanded.gif
] -- There are six images that represent the expand and collapse links on an interior
- node. The root images are only available if the root of the tree implements ITreeRootElement.
+ node. The root images are only available if the root of the tree implements <code>ITreeRootElement</code>.
</li>
<li><strong>Icon</strong> [
<img src="images/folder.gif" alt="folder.gif"/> - folder.gif,
@@ -357,15 +361,15 @@
link that will call the selection action.
</li>
<li><strong>Label</strong> -- The label is a text item representing the node. This is a
- property of the TreeElement. This is a selectable link that will call the selection action.</li>
+ property of the <code>TreeElement</code>. This is a selectable link that will call the selection action.</li>
<li><strong>Content</strong> -- This is an optional text item that may appear after the label.
It is not selectable.
</li>
</ul>
- <p> The tree supports setting a default location where the images are picked found within a
- WebApp. All of the images are found by default in the resources\beehive\version1\images
- directory. It is possible to change both the default location for finding the image
- in addition to the images themselves by explicitly setting the name of the image.
+ <p> The tree supports setting a default location where the images are picked from within a
+ WebApp. All of the images are found by default in the <code>resources\beehive\version1\images</code>
+ directory. It is possible to change both the default location for finding the images
+ in addition to the images themselves by explicitly setting the name of the image on the Tree.
</p>
</section>
</section>